# SpecVerse Architecture Guide
This is the **internal architecture reference** for SpecVerse — for engineers contributing to the engines, evaluators auditing the design, and readers (investor or technical) who want to understand how the pieces compose. If you're a SPEC AUTHOR rather than a CONTRIBUTOR, read [SPECVERSE-SPECIFYING.md](SPECVERSE-SPECIFYING.md) first; this doc assumes you've seen the language and now want to know what's under the hood.
## Overview
SpecVerse is a specification language ecosystem. You write `.specly` files that describe **WHAT** a system does. The engines figure out **HOW** to implement it. The technology choices live in a separate **manifest** file, so swapping Fastify for NestJS or PostgreSQL for MongoDB never touches the spec.
The shortest possible mental model:
```
.specly file (WHAT)
|
v
[Parser Engine] --> SpecVerseAST
|
v
[Inference Engine] --> Controllers, Services, Events, Views, Deployments
|
v
[Realize Engine] --> Generated Code (Prisma, Fastify, React, CLI, etc.)
```
The architecture rests on three load-bearing claims:
- **Define Once, Implement Anywhere™.** The same `.specly` spec produces a Fastify+Prisma+SQLite app, a NestJS+TypeORM app, or a runtime-interpreted dynamic app. The spec is the source of truth; the manifest controls the technology choice.
- **The entity-module abstraction is the unit of extensibility.** Adding a new entity type (the language gets a new noun like `workflows` or `policies`) is one new directory of nine facets — every existing engine + composer picks it up automatically. Codified as **R12** in the [Golden Rules](../GOLDEN-RULES.md).
- **Self-hosting is the proof.** SpecVerse specified itself, generated its own CLI, and that generated output is the production release `@specverse/self` on npm. The bootstrap promotion cycle (R30–R36 + R31a) keeps the regeneration safe.
### What this guide covers
- **Architecture Diagrams** — three views of the architecture (end-to-end flow, language extension, test lifecycle), each answering a distinct question. Start here if you're new.
- **Repository Structure** — the four-package npm workspace layout and what lives where.
- **The Three Layers** — Specification (what users write) / Entity Modules (extensible building blocks) / Engines (independent processors).
- **How the Pipeline Works** — parse → infer → realize, in detail.
- **How Things Connect** + **Composition Pipelines** — wiring reference: which facet feeds which engine; which composer emits which artifact.
- **Key Design Decisions** — the rationale: why double-validation, why explicit engine registration, why self-hosting.
- **Current Implementation** — what's wired today + the short list of open work.
### Companion guides
| When you want to | Read |
|---|---|
| Write a `.specly` spec (language reference) | [SPECVERSE-SPECIFYING.md](SPECVERSE-SPECIFYING.md) |
| Run the toolchain (`spv` CLI) | [SPECVERSE-TOOLING.md](SPECVERSE-TOOLING.md) |
| Generate code from a spec | [SPECVERSE-REALIZING.md](SPECVERSE-REALIZING.md) |
| Add a new entity type / engine / instance factory / LLM provider | [SPECVERSE-EXTENDING.md](SPECVERSE-EXTENDING.md) |
| Understand the AI subsystem (four-mode provider, prompt partials) | [SPECVERSE-AI.md](SPECVERSE-AI.md) + [SPECVERSE-AI-ARCHITECTURE.md](SPECVERSE-AI-ARCHITECTURE.md) |
| Understand bootstrap and self-hosting | [SPECVERSE-SELF-HOSTING.md](SPECVERSE-SELF-HOSTING.md) |
| Read the 44 golden rules | [GOLDEN-RULES.md](../GOLDEN-RULES.md) |
## End-to-End Flow
This is the visual entry-point — how a SpecVerse-based solution comes into existence, from either input path (natural-language requirements OR an existing codebase) through every architectural layer to a running application. Three more diagrams live alongside the sections they elaborate:
- **[`.specly` Schema](#specly-schema--what-a-spec-actually-contains)** (under Layer 1: Specification) — what a spec actually contains
- **[Entity-module facets exploded](#entity-module-facets-exploded)** (under Layer 2: Entity Modules) — how the language is extended
- **[Release & Quality Lifecycle](#release--quality-lifecycle)** (its own section near the end) — how code reaches users
```mermaid
flowchart TD
subgraph INPUTS["Input paths"]
NL["Natural-language requirements (user prose)"]
SRC["Existing codebase (source dir)"]
end
subgraph AI["AI workflows (LLM-mediated)"]
CREATE["spv ai create (+ verify-create)"]
ANALYSE["spv ai analyse (+ verify-analyse)"]
PREPASS["Structural prepass 3 backends: grep-only / CodeGraph / GitNexus"]
end
SRC --> PREPASS
PREPASS -->|"deterministic facts (entities, relationships, method fact sheets)"| ANALYSE
NL --> CREATE
SPEC[".specly spec (structured intent) + manifest + deployments"]
CREATE --> SPEC
ANALYSE --> SPEC
subgraph PACKAGES["@specverse npm packages"]
TYPES["@specverse/types AST + interfaces + spec-rules"]
ENTITIES["@specverse/entities 11 entity modules × 9 facets (schema, conventions, inference, generators, behaviour, examples, tests, docs, behavioural grammar)"]
ASSETS["@specverse/assets 6 prompts + 10 partials + canonical examples"]
ENGINES["@specverse/engines parser / inference / realize / generators / ai / registry"]
RUNTIME["@specverse/runtime walker + React/Tailwind view adapters"]
end
SPEC --> ENGINES
ENTITIES -.->|"discovered at runtime via registry"| ENGINES
TYPES -.->|"shared types"| ENGINES
ASSETS -.->|"prompts + schema + examples"| ENGINES
subgraph PIPELINE["Engine pipeline"]
PARSE["Parser engine schema-validates + expands conventions"]
INFER["Inference engine fills in CURVED ops, events, views, deployment shells"]
REALIZE["Realize engine per-component fan-out; resolves manifest → capability → factory"]
end
ENGINES --> PARSE
PARSE -->|"AST"| INFER
INFER -->|"expanded spec"| REALIZE
subgraph FACTORIES["Instance factories (HOW) — 13 categories, swap any without spec changes"]
F_DB["Storage (DB) PostgreSQL15 MongoDB6 Redis7"]
F_ORM["ORM PrismaORM"]
F_CTRL["Controller (API/RPC) FastifyAPI"]
F_SVC["Service PrismaServices"]
F_VIEW["View ReactAppRuntime ReactAppStarter"]
F_CMD["Command (CLI) CommanderJS"]
F_TOOLS["Tools VSCodeExtension MCPServer"]
F_COMM["Communication EventEmitter RabbitMQEvents"]
F_VAL["Validation ZodValidation"]
F_TEST["Testing VitestTests"]
F_SDK["SDK TypeScriptSDK PythonSDK"]
F_SCAF["Scaffolding GenericScaffold"]
F_INFRA["Infrastructure DockerKubernetes"]
end
MANIFEST["manifest (capability → factory mappings)"]
SPEC --> MANIFEST
MANIFEST --> REALIZE
REALIZE --> F_DB
REALIZE --> F_ORM
REALIZE --> F_CTRL
REALIZE --> F_SVC
REALIZE --> F_VIEW
REALIZE --> F_CMD
REALIZE --> F_TOOLS
REALIZE --> F_COMM
REALIZE --> F_VAL
REALIZE --> F_TEST
REALIZE --> F_SDK
REALIZE --> F_SCAF
REALIZE --> F_INFRA
subgraph CODEGEN["Generated code (L1 / L2 / L3 / L4)"]
L1["L1 Templates (scaffolding, no LLM)"]
L2["L2 Convention (CURVED ops, 15 patterns)"]
L3["L3 constraint guards (runtime, fail-open; only if constraints:)"]
L4["L4 *.ai.ts (LLM-generated from steps)"]
end
F_DB --> L1
F_ORM --> L1
F_CTRL --> L1
F_SVC --> L1
F_VIEW --> L1
F_CMD --> L1
F_TOOLS --> L1
F_COMM --> L1
F_VAL --> L1
F_TEST --> L1
F_SDK --> L1
F_SCAF --> L1
F_INFRA --> L1
REALIZE --> L2
REALIZE --> L3
REALIZE --> L4
OUTPUT["Generated bundle backend + frontend + CLI + MCP + VSCode + contract tests"]
L1 --> OUTPUT
L2 --> OUTPUT
L3 --> OUTPUT
L4 --> OUTPUT
subgraph DELIVERY["Running solution"]
APP["Production app (Fastify + Prisma + React etc.)"]
DYNAMIC["app-demo (runtime interpreter, same spec, no codegen)"]
end
OUTPUT -->|"npm install + prisma push + spin up"| APP
SPEC -.->|"alternative path: load + execute"| DYNAMIC
RUNTIME -.->|"view rendering"| APP
RUNTIME -.->|"view rendering"| DYNAMIC
style NL fill:#2874a6,stroke:#1a5276,stroke-width:2px,color:#fff
style SRC fill:#2874a6,stroke:#1a5276,stroke-width:2px,color:#fff
style SPEC fill:#7d3c98,stroke:#4a235a,stroke-width:3px,color:#fff
style MANIFEST fill:#b9770e,stroke:#7d6608,stroke-width:2px,color:#fff
style F_DB fill:#a04000,stroke:#6e2c00,color:#fff
style F_ORM fill:#a04000,stroke:#6e2c00,color:#fff
style F_CTRL fill:#a04000,stroke:#6e2c00,color:#fff
style F_SVC fill:#a04000,stroke:#6e2c00,color:#fff
style F_VIEW fill:#a04000,stroke:#6e2c00,color:#fff
style F_CMD fill:#a04000,stroke:#6e2c00,color:#fff
style F_TOOLS fill:#a04000,stroke:#6e2c00,color:#fff
style F_COMM fill:#a04000,stroke:#6e2c00,color:#fff
style F_VAL fill:#a04000,stroke:#6e2c00,color:#fff
style F_TEST fill:#a04000,stroke:#6e2c00,color:#fff
style F_SDK fill:#a04000,stroke:#6e2c00,color:#fff
style F_SCAF fill:#a04000,stroke:#6e2c00,color:#fff
style F_INFRA fill:#a04000,stroke:#6e2c00,color:#fff
style OUTPUT fill:#1e8449,stroke:#0e6655,stroke-width:2px,color:#fff
style APP fill:#229954,stroke:#0e6655,stroke-width:2px,color:#fff
style DYNAMIC fill:#229954,stroke:#0e6655,stroke-width:2px,color:#fff
```
**Reading the diagram:**
- **Two input paths converge on the spec** — users either describe a system in prose (`spv ai create`) or point at an existing codebase (`spv ai analyse`, with a deterministic structural-prepass step injecting facts before the LLM sees source). Both end at a `.specly` spec + a manifest + a deployments block.
- **The five `@specverse/*` packages** form the toolchain. `engines` is the runtime; it discovers `entities` via registry, pulls AST types from `types`, and reads prompts + canonical content from `assets`. `runtime` ships independently and is consumed by both the generated frontend and the dynamic interpreter.
- **The engine pipeline is three stages** — parser (validates + expands), inference (fills in everything the user didn't write), realize (matches capabilities to factories and emits code).
- **Instance factories are the technology layer** — 13 first-class categories (Storage / ORM / Controller / Service / View / Command / Tools / Communication / Validation / Testing / SDK / Scaffolding / Infrastructure). Each category has one or more concrete factories (e.g. Storage has PostgreSQL15 + MongoDB6 + Redis7; View has ReactAppRuntime + ReactAppStarter). The manifest maps capabilities to specific factories — swap any factory in any column and the spec stays unchanged.
- **Generated code is layered** — L1 from templates (no LLM), L2 from convention patterns (no LLM), L3 from Quint-verified guards (formally checked), L4 from per-step LLM calls (the smallest sliver, ~5% of typical output).
- **Two delivery modes** — generate code once and ship a self-contained app, OR load the spec into `app-demo` and execute it as a live interpreter (no code generation). Both render UI through the same `@specverse/runtime` walker (R2: one pattern library, three consumers).
The dotted arrows are runtime / data-only relationships (configuration, types, registry lookup); solid arrows are forward execution flow.
## Repository Structure
```
specverse-engines/ -- 4-package npm workspace (source of truth)
types/ -- Shared types (AST, engine interfaces, spec-rules)
entities/ -- Entity module system + EngineRegistry + schema composition
engines/ -- Toolchain — subpath exports:
src/
parser/ -- Parse .specly --> AST
inference/ -- Models --> full architecture (Handlebars templates)
realize/ -- Spec + manifest --> generated code
generators/ -- Diagrams, UML, documentation
ai/ -- LLM providers + orchestration
registry/ -- Explicit engine registration (R36)
libs/
instance-factories/ -- Code generators per technology
runtime/ -- Walker + React + Tailwind + test-harness
specverse-self/ -- Production release (@specverse/self): CLI, templates, self-spec
specverse-app-demo/ -- Dynamic runtime interpreter (consumer of @specverse/engines + /runtime)
```
`specverse-lang` is the historical CLI orchestrator — fully superseded by specverse-self and archived.
### Documentation Infrastructure
Documentation freshness is maintained by four standalone scripts under `specverse-self/scripts/indexing/` — the R28 + R29 compliance tooling. They hash-index every file in every repo, audit guide coverage against discovered content areas, compare indexes across repos for drift, and generate the canonical `docs/DOCUMENTATION-INDEX.md` map. All four are idempotent, fast, and safe to run any time. See [`scripts/indexing/README.md`](../../scripts/indexing/README.md) for usage.
## The Three Layers
### Layer 1: Specification (what users write)
A `.specly` file has three sections:
```yaml
components: # WHAT the system does
MyApp:
models: ...
controllers: ...
services: ...
events: ...
views: ...
commands: ...
deployments: # WHERE it runs
development:
instances: ...
manifests: # HOW it's built (technology choices)
implementation:
capabilityMappings: ...
```
#### `.specly` Schema — what a spec actually contains
The diagram below is the hierarchical tree of every concept the `.specly` language admits — generated from the canonical JSON Schema at `entities/schema/SPECVERSE-SCHEMA.json` (62 `$defs`, composed from 15 entity-module fragments). Three top-level sections, each with its own deep child shape. Names of sub-fields are exact — anything you can write in a `.specly` file appears below.
```mermaid
flowchart LR
SPECLY[".specly file (structured intent — top-level)"]
SPECLY --> COMPONENTS["components: { ComponentName: { ... } } WHAT the system does"]
SPECLY --> DEPLOYMENTS["deployments: { DeploymentName: { ... } } WHERE it runs"]
SPECLY --> MANIFESTS["manifests: { ManifestName: { ... } } HOW it's built (technology choices)"]
subgraph COMP_SHAPE["Component-level keys"]
direction LR
COMP_META["version / description / tags import / export primitives / constraints"]
ENTITIES["models · controllers · services · views events · commands · measures conventions · promotions · distributions"]
end
COMPONENTS --> COMP_META
COMPONENTS --> ENTITIES
subgraph MODEL_SHAPE["Model entity (most-used)"]
direction TB
M_ATTR["attributes typed fields with conventions: 'String required unique min=1 max=20' 'UUID auto=uuid4'"]
M_REL["relationships hasMany / hasOne / belongsTo / manyToMany + cascade / dependent / through"]
M_LIFE["lifecycles oneOf: { flow: 'a -> b -> c' } { states: [], transitions: { name: 'from -> to' } }"]
M_BHV["behaviors { description, parameters, returns, requires, ensures, publishes, steps: [] } (L3 generation source)"]
M_OTHER["metadata / profiles profile-attachment / extends"]
end
ENTITIES --> MODEL_SHAPE
subgraph CTRL_SHAPE["Controller entity"]
direction TB
C_MODEL["model (entity reference)"]
C_CURED["cured { create / update / retrieve / retrieve_many / validate / evolve / delete } (CURVED operations)"]
C_ACTIONS["actions (custom ops, same shape as model behaviors — steps drive L3)"]
C_SUB["subscribes_to { EventName: handlerMethod }"]
end
ENTITIES --> CTRL_SHAPE
subgraph SVC_SHAPE["Service entity"]
direction TB
S_OPS["operations (same ExecutableProperties: parameters / returns / requires / ensures / publishes / steps)"]
S_SUB["subscribes_to (event handlers)"]
end
ENTITIES --> SVC_SHAPE
subgraph VIEW_SHAPE["View entity"]
direction TB
V_TYPE["type list / detail / form / dashboard / board / timeline / calendar / analytics"]
V_LAYOUT["layout responsive grid spec"]
V_UI["uiComponents (walker pattern instances)"]
V_PROPS["properties { sortable, filterable, pagination, exportable, ... }"]
end
ENTITIES --> VIEW_SHAPE
subgraph EVT_SHAPE["Event entity"]
direction TB
E_ATTR["attributes (payload schema, same shape as model attributes)"]
E_VER["version / previousVersions (event versioning)"]
end
ENTITIES --> EVT_SHAPE
subgraph CMD_SHAPE["Command entity"]
direction TB
CMD_ARG["arguments / flags (positional + named options)"]
CMD_RET["returns / exitCodes (structured CLI output)"]
CMD_SUB["subcommands (nested command trees)"]
end
ENTITIES --> CMD_SHAPE
subgraph DEP_SHAPE["Deployment-level keys"]
direction LR
D_META["version / description / environment"]
D_INST["instances: controllers · services · views · communications · storage · security · infrastructure · monitoring (8 instance categories with policy blocks: rateLimit, retry, circuitBreaker, idempotency, cache, ...)"]
end
DEPLOYMENTS --> D_META
DEPLOYMENTS --> D_INST
subgraph MAN_SHAPE["Manifest-level keys"]
direction TB
MAN_DEP["deployment (deploymentSource + deploymentName)"]
MAN_DEFAULTS["defaultMappings: storage / orm / routing / controller / service / communication / validation / frontend / cache / authentication"]
MAN_CAPS["capabilityMappings [{ capability, instanceFactory }] e.g. api.rest → FastifyAPI"]
end
MANIFESTS --> MAN_DEP
MANIFESTS --> MAN_DEFAULTS
MANIFESTS --> MAN_CAPS
style SPECLY fill:#7d3c98,stroke:#4a235a,stroke-width:3px,color:#fff
style COMPONENTS fill:#6c3483,stroke:#4a235a,color:#fff,stroke-width:2px
style DEPLOYMENTS fill:#6c3483,stroke:#4a235a,color:#fff,stroke-width:2px
style MANIFESTS fill:#6c3483,stroke:#4a235a,color:#fff,stroke-width:2px
style COMP_META fill:#1f618d,stroke:#0e3a5c,color:#fff
style ENTITIES fill:#1f618d,stroke:#0e3a5c,color:#fff,stroke-width:2px
style M_ATTR fill:#117864,stroke:#0e6655,color:#fff
style M_REL fill:#117864,stroke:#0e6655,color:#fff
style M_LIFE fill:#117864,stroke:#0e6655,color:#fff
style M_BHV fill:#117864,stroke:#0e6655,color:#fff,stroke-width:2px
style M_OTHER fill:#117864,stroke:#0e6655,color:#fff
style C_MODEL fill:#117864,stroke:#0e6655,color:#fff
style C_CURED fill:#117864,stroke:#0e6655,color:#fff
style C_ACTIONS fill:#117864,stroke:#0e6655,color:#fff,stroke-width:2px
style C_SUB fill:#117864,stroke:#0e6655,color:#fff
style S_OPS fill:#117864,stroke:#0e6655,color:#fff,stroke-width:2px
style S_SUB fill:#117864,stroke:#0e6655,color:#fff
style V_TYPE fill:#117864,stroke:#0e6655,color:#fff
style V_LAYOUT fill:#117864,stroke:#0e6655,color:#fff
style V_UI fill:#117864,stroke:#0e6655,color:#fff
style V_PROPS fill:#117864,stroke:#0e6655,color:#fff
style E_ATTR fill:#117864,stroke:#0e6655,color:#fff
style E_VER fill:#117864,stroke:#0e6655,color:#fff
style CMD_ARG fill:#117864,stroke:#0e6655,color:#fff
style CMD_RET fill:#117864,stroke:#0e6655,color:#fff
style CMD_SUB fill:#117864,stroke:#0e6655,color:#fff
style D_META fill:#1f618d,stroke:#0e3a5c,color:#fff
style D_INST fill:#1f618d,stroke:#0e3a5c,color:#fff,stroke-width:2px
style MAN_DEP fill:#1f618d,stroke:#0e3a5c,color:#fff
style MAN_DEFAULTS fill:#1f618d,stroke:#0e3a5c,color:#fff
style MAN_CAPS fill:#1f618d,stroke:#0e3a5c,color:#fff,stroke-width:2px
```
**Reading the schema diagram:**
- **Three top-level sections** (purple): `components` / `deployments` / `manifests`. Every `.specly` file has these three keys at the root.
- **Component-level keys** (blue): metadata (version / description / tags / import / export) plus the eleven **entity types** the component declares. Models / controllers / services / views / events are the most-used; commands / measures / conventions / promotions / distributions cover meta-language and analytics needs.
- **Per-entity sub-fields** (teal): each entity type has its own deep shape. Models have attributes + relationships + lifecycles + behaviors. Controllers have CURVED operations + actions. Services have operations. Views have type + layout + uiComponents + properties. Events have attributes (payload) + versioning. Commands have arguments + flags + subcommands.
- **Behaviors / actions / operations all share one shape** — `ExecutableProperties` with `parameters / returns / requires / ensures / publishes / steps`. The `steps` array is what drives L3 AI behavior generation; everything else is contract surface (preconditions / postconditions / event emissions).
- **Two valid lifecycle shapes** (oneOf in the schema): a simple `flow: "a -> b -> c"` string OR an explicit `states: [] + transitions: { name: "from -> to" }` map. Mixing them or adding extra keys (`initial:`, `final:`) fails schema validation.
- **Deployment.instances** is where operational policy lives — eight instance categories (controllers / services / views / communications / storage / security / infrastructure / monitoring) each accept policy blocks like `rateLimit`, `retry`, `circuitBreaker`, `idempotency`, `cache` with concrete fields (`requestsPerMinute`, `backoffMs`, `halfOpenAfterMs`, etc.).
- **Manifests** are the "swap any technology" layer — `defaultMappings` give a category-level shorthand (e.g. `storage: PostgreSQL15`) and `capabilityMappings` give explicit capability→factory edges (e.g. `api.rest → FastifyAPI`). Realize resolves capabilities through this layer to pick which instance factory to invoke.
**Why this matters:** every word in the diagram is a real key the parser accepts. Spec authors writing `.specly` are filling in this tree. The 9-facet entity-module shape (see Layer 2 below) is what makes adding a new branch to this tree a one-directory change.
### Layer 2: Entity Modules (extensible building blocks)
Every concept in a `.specly` file (models, controllers, services, events, views, commands, etc.) is an **entity type**. Each entity type is defined by an **entity module** with up to 9 facets:
```
entity-module/
module.yaml -- Manifest: name, version, dependencies, facet paths
schema/ -- JSON Schema: what's valid in .specly syntax
conventions/ -- Convention processor: shorthand expansion
inference/ -- Inference rules: what to generate from this entity
generators/ -- Code generators: instance factory templates
behaviour/ -- Quint specs: formal invariants and rules
conventions/ -- Behavioural conventions: human-readable -> Quint
__examples__/ -- Canonical example .specly snippets
__tests__/ -- Test references (regression + parity)
__behaviour__/ -- Quint .qnt files (invariants + rules + verify + test)
```
**Core entities** ship with SpecVerse: models, controllers, services, events, views, deployments.
**Extension entities** are added via packages: commands, conventions, measures.
#### Entity-module facets exploded
The block above shows entity modules as nine directory names. The diagram below expands one entity module to make each facet's flow concrete: which engine reads it, which composer writes it, what tracked artifact comes out. The same nine-facet shape applies to all 11 entity types.
```mermaid
flowchart LR
subgraph EMOD["Entity module (1 of 11 — same shape applies to each)"]
F_SCH["schema/ JSON Schema fragments"]
F_CONV["conventions/ shorthand processor (.ts)"]
F_INF["inference/ rules (Handlebars JSON)"]
F_GEN["generators/ factory templates (.ts/.hbs)"]
F_BHV["__behaviour__/ Quint specs (.qnt)"]
F_BGRAM["conventions/behavioural-grammar.yaml natural-language → Quint"]
F_EX["__examples__/ canonical .specly snippets"]
F_TST["__tests__/ vitest references"]
F_DOC["docs/ md references"]
end
subgraph COMPOSERS["Composition pipelines (deterministic)"]
COMP_SCH["compose-schema.cjs walks every entity's schema/ 15 fragments → 62 $defs"]
COMP_EX["compose-examples.mjs walks every entity's __examples__/ + engines/assets/examples-*"]
COMP_DOC["docs-index.mjs walks every entity's docs/ + guides/ + plans/"]
COMP_BUNDLE["validateBundle v2 walks every facet (schema + tests + behaviour)"]
end
F_SCH --> COMP_SCH
F_EX --> COMP_EX
F_DOC --> COMP_DOC
F_SCH --> COMP_BUNDLE
F_TST --> COMP_BUNDLE
F_BHV --> COMP_BUNDLE
F_EX --> COMP_BUNDLE
SCH_OUT["SPECVERSE-SCHEMA.json (tracked artifact — parser AJV input)"]
EX_OUT["self/examples/ (tracked, ~120 files — shipped to spv init)"]
DOC_OUT["DOCUMENTATION-INDEX.md (tracked, every .md mapped)"]
BUNDLE_OUT["BundleReport (facet × status × duration)"]
COMP_SCH --> SCH_OUT
COMP_EX --> EX_OUT
COMP_DOC --> DOC_OUT
COMP_BUNDLE --> BUNDLE_OUT
subgraph ENGINES_V2["Engines — runtime aggregators (no explicit composer; aggregated at load time)"]
REG["EntityRegistry (bootstrap from each module's index.ts)"]
UPARSER["UnifiedSpecVerseParser + ConventionProcessor per-entity dispatch"]
IRENG["Inference engine Handlebars rule renderer + rule loader"]
REALIZE_V2["Realize engine per-component fan-out; resolves manifest→capability→factory"]
BGEN["BehavioralConventionProcessor (reads behavioural grammars)"]
QGUARDS["Quint transpiler (validate-time spec invariants)"]
DGRAM["Diagram engine (per-entity ManifestPlugin)"]
end
F_CONV -.->|"discovered via registry"| UPARSER
F_INF -.->|"loaded by rule-loader"| IRENG
F_GEN -.->|"resolved by capability lookup"| REALIZE_V2
F_BHV -.->|"transpiled at build time"| QGUARDS
F_BGRAM -.->|"loaded by BehaviouralConventionProcessor"| BGEN
EMOD -.->|"each module's index.ts"| REG
REG --> UPARSER
REG --> IRENG
REG --> REALIZE_V2
REG --> DGRAM
SPEC_V2[".specly spec (structured intent)"]
SCH_OUT --> UPARSER
SPEC_V2 --> UPARSER
UPARSER -->|"AST"| IRENG
BGEN --> IRENG
QGUARDS -->|"validate-time spec invariants"| IRENG
IRENG -->|"expanded spec"| REALIZE_V2
OUTPUT_V2["Generated bundle (L1 templates / L2 convention / L3 Quint guards / L4 *.ai.ts)"]
REALIZE_V2 --> OUTPUT_V2
style F_SCH fill:#1f618d,stroke:#0e3a5c,color:#fff
style F_CONV fill:#1f618d,stroke:#0e3a5c,color:#fff
style F_INF fill:#1f618d,stroke:#0e3a5c,color:#fff
style F_GEN fill:#1f618d,stroke:#0e3a5c,color:#fff
style F_BHV fill:#1f618d,stroke:#0e3a5c,color:#fff
style F_BGRAM fill:#1f618d,stroke:#0e3a5c,color:#fff
style F_EX fill:#1f618d,stroke:#0e3a5c,color:#fff
style F_TST fill:#1f618d,stroke:#0e3a5c,color:#fff
style F_DOC fill:#1f618d,stroke:#0e3a5c,color:#fff
style COMP_SCH fill:#b9770e,stroke:#7d6608,color:#fff
style COMP_EX fill:#b9770e,stroke:#7d6608,color:#fff
style COMP_DOC fill:#b9770e,stroke:#7d6608,color:#fff
style COMP_BUNDLE fill:#b9770e,stroke:#7d6608,color:#fff
style SCH_OUT fill:#7d3c98,stroke:#4a235a,color:#fff
style EX_OUT fill:#7d3c98,stroke:#4a235a,color:#fff
style DOC_OUT fill:#7d3c98,stroke:#4a235a,color:#fff
style BUNDLE_OUT fill:#7d3c98,stroke:#4a235a,color:#fff
style REG fill:#6c3483,stroke:#4a235a,color:#fff
style UPARSER fill:#6c3483,stroke:#4a235a,color:#fff
style IRENG fill:#6c3483,stroke:#4a235a,color:#fff
style REALIZE_V2 fill:#6c3483,stroke:#4a235a,color:#fff,stroke-width:3px
style BGEN fill:#6c3483,stroke:#4a235a,color:#fff
style QGUARDS fill:#6c3483,stroke:#4a235a,color:#fff
style DGRAM fill:#6c3483,stroke:#4a235a,color:#fff
style SPEC_V2 fill:#7d3c98,stroke:#4a235a,stroke-width:3px,color:#fff
style OUTPUT_V2 fill:#1e8449,stroke:#0e6655,stroke-width:2px,color:#fff
```
**Reading the diagram:**
- **Blue boxes** are the nine facets every entity module ships. The same nine names show up under every entity type (`models/`, `controllers/`, `services/`, etc.).
- **Amber boxes** are the four explicit composition pipelines (each is a tracked walker script — `compose-schema.cjs`, `compose-examples.mjs`, `docs-index.mjs`, `validateBundle v2`). Each walks the tree, gathers its facet of interest from every entity module, and emits a deterministic artifact. R12 (adding a new entity type = 3 changes) and R16d (decision points belong to the user) both rely on these composers being side-effect-free and re-runnable.
- **Purple "tracked artifact" boxes** are the deterministic outputs of those composers. They're the concrete files committed to the repo (parser sees `SPECVERSE-SCHEMA.json`, `spv init` ships `self/examples/`, the docs site reads `DOCUMENTATION-INDEX.md`).
- **Dark-purple "engine" boxes** are the runtime aggregators — they don't have an explicit composer step, they just walk the tree at load time. `UnifiedSpecVerseParser` discovers convention processors per-entity-type, the inference rule loader pulls every entity's `inference/*.json`, and the realize engine resolves capability mappings to factories at runtime.
- **Solid arrows** are forward execution; **dotted arrows** are runtime discovery (registry lookups, dynamic imports, plugin loading).
**The R12 punchline:** to add a new entity type, you create one new directory under `entities/src/extensions/` with the same nine facets, and register it in bootstrap. Every composer + every engine picks it up automatically because they all walk the tree by convention. No engine code changes. No parser changes. Just three edits (the directory + an entry in `_bootstrap.js` + a one-line schema enum addition). That's the load-bearing test of whether the architecture's claim "Define Once, Implement Anywhere" actually holds.
### Layer 3: Engines (independent, discoverable processors)
Each engine is an npm package implementing the `SpecVerseEngine` interface:
```typescript
interface SpecVerseEngine {
name: string; // 'parser', 'inference', 'realize', etc.
version: string;
capabilities: string[]; // ['parse', 'validate', 'import-resolution']
initialize(config?: any): Promise;
getInfo(): EngineInfo;
}
```
Engines are discovered at runtime by `EngineRegistry`:
```typescript
const registry = new EngineRegistry();
await registry.discover(); // finds @specverse/engine-* packages
const parser = registry.getEngineForCapability('parse');
await parser.initialize({ schema });
const result = parser.parseContent(content, filename);
```
## How the Pipeline Works
### Step 1: Parse
The parser engine takes `.specly` content and produces a `SpecVerseAST`.
```
Raw YAML
--> YAML parser (js-yaml)
--> JSON Schema validation (pre-processing)
--> Convention processor (entity modules expand shorthand)
--> JSON Schema validation (post-processing)
--> Semantic validation (cross-entity checks)
--> SpecVerseAST
```
Key: The convention processor discovers entity types from the **entity registry**. Each entity module provides a convention processor that knows how to expand its shorthand syntax. When you add a new entity type, the parser automatically processes it.
### Step 2: Infer
The inference engine takes models from the AST and generates full architecture.
```
Models (from AST)
--> Rule loader (loads JSON rules from entity modules)
--> For each registered generator:
--> Pattern match models against rules
--> Generate controllers/services/events/views
--> Deployment generator (instances, channels)
--> ComprehensiveInferenceResult
```
Key: Generators are registered in a `Map`. Each generator loads rules from its entity module. Adding a new generator means adding it to the map and providing rules.
### Step 3: Realize
The realize engine takes an inferred spec + manifest and generates code.
```
AI-optimized spec + Manifest
--> Instance factory library (loads factory YAMLs)
--> Capability resolver (maps capabilities to factories)
--> For each capability:
--> Resolve factory
--> Load template generator (TypeScript file)
--> Execute generator with context
--> Write output file
--> Generated code (Prisma, Fastify, React, etc.)
```
Key: Instance factories are YAML files that declare what they generate. Template generators are TypeScript files that produce code. The manifest controls which factories are used. Adding a new technology means adding a new instance factory.
### Step 3b: Constraint resolution (Phase 2 IR pipeline)
When a model declares `constraints: [{on, requires}]`, the realize pipeline runs a parallel four-stage IR pipeline before the controller-generator emits code. The author's natural-language predicate becomes a Quint `pure def` becomes a TypeScript guard function:
```
"Poll is open" (author input, in spec)
--> BehaviouralConventionProcessor.expand() [entities/src/_shared/behaviour/convention-processor.ts]
match against 9 sugar conventions; emit Quint AST node
--> { name, params, body: 'self.poll.votingStatus == "open"', source }
--> transpilePhase2Guard() [engines/src/inference/quint-transpiler.ts]
Quint --> TS function body; auto-upgrades '==' to '===' strict equality
--> guard: (self, actor) => self.poll.votingStatus === "open"
--> guards-generator.ts [engines/libs/instance-factories/services/templates/_shared/]
wraps the guard in MODEL_CONSTRAINTS + runGuards runtime
--> .guards.ts file emitted, sibling to Controller.ts
```
The shared `_shared/guards-generator.ts` backs **all three ORM controllers** (prisma / mongodb-native / postgres-native) — the constraint runtime is ORM-agnostic. ORM-specific controllers add the `import` + a `runConstraintGuards(_data, _context.operation, _actor)` call inside their `validate()` method.
**The five enforcement modes** consume the same `MODEL_CONSTRAINTS` table:
| Mode | Layer | Mechanism |
|---|---|---|
| α — FK dropdown filter | Browser (`@specverse/runtime/views/react`) | `annotateFkOptions` evaluates `on:[create]` constraints against each FK option's parent entity. Adds `disabled` + reason tooltip to ineligible `