Runtime Pipeline

Accepted

A generation in Almathal moves through eight stages. Five are blocking (compatibility, approval, seam validation, scaffolding, build verification). Three are non-blocking or user-driven (spec resolution input, stitching with retry, output review). The order is fixed; stages do not run in parallel except where explicitly noted.

Pipeline Diagram

User input
   │
   ▼
┌─────────────────────────────┐
│ 1. Spec Resolution          │  Resolver  · deterministic
└─────────────────────────────┘
   │
   ▼
┌─────────────────────────────┐
│ 2. Compatibility Validation │  Compatibility Validator  ·  blocking
└─────────────────────────────┘
   │
   ▼
┌─────────────────────────────┐
│ 3. Build Approval           │  Briefing Generator  ·  blocking on user
└─────────────────────────────┘
   │
   ▼
┌─────────────────────────────┐
│ 4. Seam Validation          │  Seam Validator  ·  deterministic  ·  blocking
└─────────────────────────────┘
   │
   ▼
┌─────────────────────────────┐
│ 5. Scaffolding              │  Scaffolder Runner  ·  deterministic
└─────────────────────────────┘
   │
   ▼
┌─────────────────────────────┐
│ 6. Stitching                │  Stitcher (LLM)  ·  bounded by Seam contracts
└─────────────────────────────┘
   │
   ▼
┌─────────────────────────────┐
│ 7. Build Verification       │  Build Validator  ·  deterministic  ·  blocking
└─────────────────────────────┘
   │
   ▼
┌─────────────────────────────┐
│ 8. Output Review            │  AI Reviewer  ·  advisory  ·  non-blocking
└─────────────────────────────┘
   │
   ▼
Generated application delivered

Stage Detail

1. Spec Resolution

Doer: Resolver (subcomponent of the Composer) Input: User selection of an Archetype, completed hybrid form, and conversational refinement Output: A fully populated Archetype Spec Blocking: No (waits on user input only)

The Resolver takes the user’s intent and produces a structured Spec. The hybrid input model works as follows:

• Form-driven for known Variation Points: the user selects from enums, fills in entity definitions, picks options. Form fields are auto-generated from the Archetype’s variation_points declaration.
• Conversational for the unstructured parts: the user describes additional requirements in natural language, which an LLM interprets and either fits to existing Variation Points or surfaces as items that don’t fit (potentially triggering the fallback path).

The Resolver also performs slot resolution: for each adapter_slot and module_slot in the Archetype, it picks a default Adapter or Module (overridable by the user), and locks the version.

The output is a complete, self-contained Spec that downstream stages can consume without re-asking the user.

2. Compatibility Validation

Doer: Compatibility Validator Input: Fully resolved Spec Output: Pass / fail / warning, with explanation Blocking: Yes (on failure)

A purely deterministic walk over the distributed compatibility matrix. Each Adapter and Module Manifest declares which versions of which other Adapters and Modules it is compatible with. The Validator computes the intersection.

Three possible outcomes:

• Pass: All declared compatibilities align. Generation proceeds.
• Warning: Edge cases or known-good combinations not explicitly verified. The AI Reviewer drafts a human-readable explanation; the user can choose to proceed.
• Fail: Declared incompatibility detected. Generation does not proceed. The user is shown what conflicts and offered options (different Adapter, different version, etc.).

The AI Reviewer is invoked only to explain the result, not to make the determination. The determination is mechanical.

3. Build Approval

Doer: Briefing Generator (with AI summary) → User Input: Resolved Spec + Compatibility Validation result Output: User-approved Spec (or user-edited and re-approved) Blocking: Yes (on user sign-off)

The Briefing Generator produces a human-readable summary of what is about to be built:

• What kind of app (Archetype, display name)
• What stack (which language slices, which key Adapters)
• What Modules are included
• What versions are locked
• What Variation Points the user chose
• Any warnings from Compatibility Validation
• Estimated token cost for Stitching (so the user knows what they’re authorizing)

The user can:

• Approve as-is, and the Spec is recorded with the approval in the audit trail.
• Edit specific fields (swap an Adapter, change a version, modify a Variation Point), which returns to Stage 1 for re-resolution.
• Cancel, ending the generation.

Substitutions surfaced during Compatibility Validation (e.g., missing chicken stock, alternatives proposed) appear here for user choice rather than as separate prompts.

4. Seam Validation

Doer: Seam Validator Input: Approved Spec Output: Pass / fail with specific errors Blocking: Yes (on failure)

Static analysis of every Seam in the Spec, performed before any LLM is invoked. Validates:

• Input reference resolution — does each Seam’s declared input exist in the Spec?
• Adapter availability — are required Adapters resolved into slots?
• Path conflict detection — would any two Seams write to the same output file?
• Capability coverage — do required capabilities exist in the resolved Adapter set?
• Verification feasibility — are the tools needed for verification (compile, lint, etc.) actually present?
• Cross-Seam consistency — do paired Seams (e.g., backend API and frontend caller) reference matching shapes?

A failure here indicates a bug in the Archetype definition, not user error. The user is told the Archetype has a defect; the platform team is alerted to fix the Archetype.

5. Scaffolding

Doer: Scaffolder Runner (subcomponent of the Composer) Input: Approved, validated Spec Output: Scaffolded code skeleton + post-processing applied Blocking: Yes (on scaffolder failure)

The Scaffolder Runner invokes each Scaffolder declared in the Archetype, in the right order, with configuration derived from the Spec:

• JHipster receives its JDL and config
• Spring Initializr receives its dependency list
• create-t3-app receives its options
• Yeoman receives its prompt answers

Scaffolders run in a sandboxed environment. Output is captured to a working directory. The platform may apply post-processing: removing files not relevant to this Archetype, renaming default identifiers, injecting Almathal-specific metadata files.

6. Stitching

Doer: Stitcher (LLM) Input: Scaffolded skeleton + Spec + list of Seams to fill Output: Code that fills each Seam, plus generated UI Blocking: Soft — fails can trigger up to N retry attempts before hard failure

For each Seam, the Stitcher receives:

• The Seam contract (output paths, required Adapters, behaviors, verification criteria)
• The relevant context from the scaffolded skeleton
• The Spec for any cross-Seam information needed

The Stitcher produces the code for that Seam. Seams are processed in dependency order (backend before frontend that calls it, for example) so later Seams have the earlier Seams’ outputs as context.

UI generation is treated as a special category of Seam with its own contract style.

If a Seam’s verification fails, the Stitcher is given the verification output as additional context and asked to retry. The bound is typically 3 attempts; persistent failure escalates to a hard failure surfaced to the user.

Token economics live here

This is the only stage where significant LLM tokens are spent. The Composer, Validators, and Scaffolders are deterministic and free. Stitching cost is bounded by the number and complexity of Seams declared in the Archetype, which the platform team controls. This is why archetype-matched generations are an order of magnitude cheaper than pure-LLM regeneration.

7. Build Verification

Doer: Build Validator Input: Stitched application Output: Pass / fail with details Blocking: Yes (on failure)

Mechanical verification of the generated app:

• Compile — does the code compile/typecheck without errors?
• Lint — does it pass the linter configuration declared by the Archetype?
• Smoke tests — does the smoke test suite declared by the Archetype pass?
• Seam verification — does each Seam’s specific verification block (declared in the Spec) pass?

Build Verification is the gate of correctness. Nothing reaches the user without passing.

On failure: depending on the failure type, the system may loop back to Stitching with the failure context, or hard-fail with a diagnostic message.

8. Output Review

Doer: AI Reviewer Input: Verified generated app Output: Warnings (advisory, surfaced to user) Blocking: No

A separate LLM from the Stitcher reviews the generated app holistically for:

• Anti-patterns (“business logic in controllers”, “N+1 queries”, etc.)
• Security concerns (“endpoint missing auth middleware”, “secret in code”)
• Consistency issues (“API and frontend disagree on naming convention”)
• Quality concerns that don’t break tests but matter long-term

The AI Reviewer is advisory. Its findings are surfaced as warnings; the user can choose to accept them or address them in a follow-up generation. The intent is to catch things mechanical verification misses, not to be a second blocking gate.

Using a different LLM model than the Stitcher is deliberate: it reduces the chance that an LLM rubber-stamps its own work.

Failure Paths

Each blocking stage has a defined failure behavior:

Stage	On failure
Compatibility Validation	Surface conflict, offer alternatives, return to Spec Resolution
Build Approval	User cancels or edits; return to Spec Resolution
Seam Validation	Hard fail with archetype-defect alert (user error not possible)
Scaffolding	Hard fail with scaffolder diagnostic
Stitching	Retry up to N times with failure context; then hard fail
Build Verification	Retry Stitching once with verification failure as context; then hard fail

The pure-LLM fallback path (for requests that don’t match any Archetype) bypasses Stages 4–6 and uses an LLM-orchestrated flow with explicit user warning.

Audit Trail

Every stage records to the build’s audit trail:

• Inputs and outputs
• Decisions made (which Adapter chosen, which version)
• User actions (approvals, edits)
• LLM invocations (model, token counts)
• Verification results
• Final delivery

The audit trail is part of the generated app’s deliverables, alongside the code itself. Enterprise customers receive a full record of how their app was assembled.

Related

• Architecture Overview — the layered architecture
• Glossary — every stage and doer formally defined
• ADR-0012: Sanity checks at five pipeline stages