System Architecture Overview

_Last updated: September 2025_

Mosaic Builder centres on a single source of truth – the Intermediate Representation (IR). Everything you do in the product flows through the same pipeline:

Conversation → Canon (normalised spec) → IR → { runtime preview │ code generation │ validation }

This document describes that pipeline, the core services behind it, and how data moves through the system end‑to‑end.

---

1. High-Level Flow

graph LR
    subgraph Chat Loop
        User[User] -->|messages| ChatUI[Chat UI]
        ChatUI --> SSE[SSE Stream]
        SSE -->|dsl_update| DSLMgr[DSL Manager]
        DSLMgr --> Canon[Canonical Model]
        Canon --> IRBuilder[IR Builder]
    end

    subgraph IR World
        IRBuilder --> IR[(IR Snapshot)]
        IR --> Runtime[Runtime Preview]
        IR --> Codegen[Code Generation]
        IR --> Validation[Validation Pipeline]
    end

    IR -. persist .-> PG[(PostgreSQL)]
    Runtime --> Browser
    Codegen --> Repo[(Exported Project)]

  • Chat gathers requirements. Each assistant message may emit DSL deltas via SSE.
  • DSL Manager stores events and compacts them into snapshots.
  • Canon + IR Builder normalise the domain model into a deterministic, typed IR.
  • IR Snapshot is now the source of truth. The runtime preview, validators, and code generator consume it.

    • ---

    2. Core Domains

    Chat & Extraction

  • • app/(chat)/api/chat/route.ts streams assistant responses and DSL deltas.
  • • lib/dsl/manager.ts records DSL events and snapshots (in-memory for tests, Postgres for prod).
  • • lib/ir/validation.ts, lib/runtime/ir-bridge.ts canonicalise DSL into IR and run structural validation.

    • IR Persistence & Caching

  • • IR snapshots live in app_models.ir_data and are cached server-side via lib/runtime/server/ir-store.ts (5 minute TTL, background eviction).
  • • Public API: GET /api/runtime/ir/[tenantId] and GET /api/dsl/[chatId] return the snapshot plus metadata/event history.

    • Runtime Preview

  • • The preview is snapshot-driven. UIRuntimeProvider receives a RuntimeSnapshot and derives a light view model on the fly.
  • • RuntimePage uses the snapshot to resolve routes, render tables/forms/detail views, and coordinate CRUD calls via DataCache.
  • • No AppModel conversion remains in the hot path; all renderers understand snapshot structures directly.

    • Code Generation

  • • scripts/codegen/index.ts converts an IR file into a Next.js project, Drizzle schema, migrations, workflows, and tests.
  • • Segmented files preserve developer-owned code blocks. The manifest tracks hashes so conflicts surface when a manual edit collides with regenerated content.
  • • --verify (optional) runs pnpm exec tsc --noEmit and pnpm lint inside the generated project for quick smoke validation.

    • ---

    3. Data Contracts

    | Layer | Artifact | Key Files | |-------|----------|-----------| | DSL Extraction | DSLContext deltas | lib/dsl/types.ts, lib/dsl/manager.ts | | Canon | Normalised domain model | lib/generation/canonizer.ts | | IR | ir/v1 schema | lib/ir/types.ts, lib/runtime/ir-runtime.ts | | Runtime Snapshot | UI-focused projection | lib/runtime/ir-runtime.ts | | Manifest | Codegen output ledger | scripts/codegen/utils/manifest.ts |

    ---

    4. Runtime Internals

    graph TB
    Snapshot[(RuntimeSnapshot)]
    Snapshot --> ViewModel[buildViewModelFromSnapshot]
    ViewModel --> Provider[UIRuntimeProvider]
    Provider --> Registry[ComponentRegistry]
    Provider --> Cache[DataCache]
    Provider --> View{View Renderer}
    View --> TableRenderer
    View --> FormRenderer
    View --> DetailsRenderer
    Cache --> API[/api/runtime/:tenant/]

  • • UIRuntimeProvider keeps both the lightweight view model (for UI hints) and the raw snapshot (for routing/data decisions).
  • • RuntimePage performs route matching against snapshot.routes, interpolates parameters, then dispatches to renderers.
  • • CRUD operations delegate to DataCache, which handles optimistic updates, IndexedDB persistence, and backend syncing.

    • ---

    5. Codegen Pipeline

  • Plan – scripts/codegen/pipeline.ts walks the IR and produces an ArtifactPlan[].
  • Write – writeArtifacts() handles segmented diffing, conflict detection, hashing, and manifest updates.
  • Report – CLI prints added/updated/unchanged/conflict counts; conflicts emit .mosaic-conflict files to resolve manually.
  • Verify – optional --verify runs type-check + lint inside the output for early feedback.

    • Key templates: scripts/codegen/templates/entity*.ts, serverActions.ts, migration.ts, schema.ts.

    ---

    6. Testing Surfaces

    | Suite | Command | Purpose | |-------|---------|---------| | Unit | pnpm test:unit | IR bridge, runtime helpers, codegen writer | | Integration | NODE_ENV=test pnpm dev + pnpm test:integration | Chat lifecycle, DSL replay, runtime endpoints | | Runtime smoke | tests/runtime.test.mjs | CRUD + migration status via runtime APIs | | Codegen smoke | invoked from unit suite | Ensures CLI produces expected artifacts |

    Playwright E2E is re-enabling soon (chat → preview loop).

    ---

    7. External Integrations

  • • LLM provider: OpenRouter (tool calling only; extraction is schema-driven).
  • • Persistence: PostgreSQL for DSL + IR; S3/GitHub for exports (via codegen).
  • • Auth: Supabase/NextAuth hybrid (guest fallback only active in test mode).

    • ---

    8. Where to Go Next

  • • IR Runtime Deep Dive
  • • Codegen CLI Guide
  • • End-to-End Tutorial
  • • Testing Guide

    • These docs build on the architecture overview and walk through concrete usage of each subsystem.