9.1 — App Builder architecture

Pro+ feature. The App Builder is a premium add-on gated behind the buildApp feature flag, which is true on Pro, Team, and Enterprise (and for admins) and false on Free and Starter. This page is for contributors working on the feature; the user-facing guide is User docs: 12 App Builder.

The App Builder compiles a VibeMap project's atomic blueprint into a complete, deployable Next.js + Supabase app. Where VibeMap's other pipelines stop at a structured spec, this one emits source code, verifies it, and ships it.

The core reframe: this is not a from-scratch "Bolt clone." VibeMap already owns the hardest thing prompt-first builders lack — a validated, normalized spec (entities, access rules, interactions, acceptance criteria). The App Builder brings the coding agent in-house and gives it a place to run.

The build pipeline

A single Inngest orchestrator runs the whole thing. The shape mirrors the existing prepare-for-development.ts pattern: an event triggers a multi-step function that writes status back as it goes.

build/app.requested ──▶ inngest/functions/build-app.ts
  │
  1. PREFLIGHT   blueprint ready + entitlement + (at GA) OAuth connected
  2. COMPILE     deterministic compiler: blueprint -> file tree + GAPS         (no LLM)
  3. FILL        one scoped agent per gap, write-clamped to its own files      (LLM)
  4. VERIFY      install · type-check · lint · build -> structured errors
  5. REPAIR      red? per-file repair agents -> re-verify (≤ 3 rounds)         (LLM)
  6. DEPLOY      push to GitHub repo (Octokit) · deploy on Vercel
  7. REPORT      live URL · repo · gap/fill counts · error summary -> build_runs

runBuild() in lib/builder/orchestrate.ts owns stages 2–5: it calls compileBlueprint, then fillGaps, then runVerifyRepair, and returns a BuildOutcome (ok, stage, files, gap/fill counts, ownership violations, remaining errors, per-gap gapResults). It never throws on a build failure — it returns ok: false with diagnostics. Deploy (stage 6) lives in the Inngest function so the pure pipeline stays side-effect-free.

Around the core pipeline:

• Dry-run plan — GET /api/projects/[id]/build/plan runs compile + lintBlueprint (no LLM, no writes) and powers the Build tab's plan card and the Prepare page's spec-check banner; it is also where the build route gets the real gap count it reserves tokens against.
• Prepare gate — the build route 412s for unprepared projects unless the caller passes force: true.
• Acceptance-test pass — after verify goes green, the optional VerifyDriver.runTests runs the emitted tests/specs/ Vitest suite in the temp app (--reporter=json, parsed by verify/parse-vitest.ts). Report-only: failures route to the owning gap by criterion ref onto GapResult.testFailures; a crashing runner never fails a verified build.
• Incremental rebuild — every GapResult carries a specHash (sha256 of the gap's full context pack) and successful runs persist a files.json snapshot to app-builder-artifacts. The next build's compute-prefills step reuses files for gaps whose hash is unchanged and whose fill succeeded — no LLM call (GapResult.reused). Any failure degrades to a full rebuild.
• Post-build chat edit — POST /api/projects/[id]/build/edit + inngest/functions/build-edit.ts patch one gap of a succeeded run: buildEditPrompt (user request + current built files + the gap's spec context), ownership clamp, verify with one repair round, then snapshot update + full-tree push to the user's repo. Status lands on the gap's gap_results entry (editStatus / lastEdit) so the existing run polling surfaces it.

Why this is the differentiator

The blueprint is used three ways in one run:

• Input — the compiler walks it deterministically (stage 2).
• Goal — each gap's acceptanceCriteriaIds become the agent's objective (stage 3).
• Test oracle — verification gates the output against the same spec (stage 4).

access_rules + op_conditions become RLS policies and route guards deterministically; acceptance_criteria become both the agent goals and the verify gate. That triangle is what a prompt-only competitor can't replicate.

The emitter model

The compiler is a pure function — compileBlueprint(blueprint) → { files, gaps, unsupported }, no I/O, no Date.now() / Math.random(). Same blueprint in, same tree out (file keys sorted, gaps sorted by id) so output is reproducible and fully unit-testable. See lib/builder/compile.ts.

It runs an ordered registry of emitters, each consuming one slice of the blueprint and contributing files (later emitters overlay earlier ones). The registry lives in lib/builder/emitters/index.ts:

The registry has since grown with config-driven emitters — fileStorageEmitter, contentEmitter, teamEmitter, and marketingPagesEmitter — and several of the emitters above now branch on the project's architecture config: authEmitter trims to the chosen sign-in method (+ MFA), paymentsEmitter to the chosen payment model, and accessEmitter to the roles model. Each gates on a config accessor and emits nothing when its slice is off. See 9.2 Architecture configuration for the full config→output mapping.

Cross-emitter invariant — authentication "none": pagesEmitter and authEmitter must agree on the auth mode. Pages call requireUser() unconditionally, so for authentication: "none" the auth emitter emits a no-op lib/auth/guards.ts (there is no /login route to redirect to) and the pages emitter omits the sign-out form (there is no app/(auth)/actions.ts to import). This is covered by tests/unit/builder/import-integrity.test.ts — a 2026-07 regression where the two emitters disagreed made the deterministic scaffold fail tsc before any AI stage ran.

The emitter contract

An emitter implements the Emitter interface from lib/builder/types.ts:

interface Emitter {
  name: string;
  emit(ctx: EmitterContext): EmitterResult;
}

EmitterContext is read-only ({ blueprint, projectName }). EmitterResult carries the files it produced, plus optional gaps, unsupported, npm dependencies / devDependencies, and env vars. The compiler merges declared dependencies into the generated package.json and assembles declared env vars into a generated .env.example — so an emitter never edits those files directly; it just declares what its code needs.

Adding a new emitter or template

• New emitter → add a file under lib/builder/emitters/, implement Emitter, and register it in emitters/index.ts (order matters — later emitters overlay earlier ones).
• New template → add it under lib/builder/templates/ (organized by domain: scaffold, schema, access, auth, pages, payments). Templates are versioned, same convention as lib/prompts/, and every emitted file carries a provenance comment so repair/rebuild can reason about its origin.
• Keep emitters pure. Anything non-deterministic belongs in the gap-fill or deploy stages, not the compiler.

Gaps, fill, and verify

A Gap is a slot the compiler can't fully resolve — a non-CRUD page body, an interaction handler, or an acceptance criterion with no covering file:

interface Gap {
  id: string;
  kind: "page_body" | "interaction_handler" | "uncovered_ac";
  targetFiles: string[];            // the ownership manifest — the only files this gap may write
  acceptanceCriteriaIds: string[];  // the agent's goal
  context: string;
}

• Fill (lib/builder/gaps/) dispatches one scoped agent per gap, in parallel and capped. Each agent gets the frozen skeleton as context and is write-clamped to its targetFiles via the ownership manifest; writes outside the manifest are reported as ownershipViolations, not silently applied.
• Verify + repair (lib/builder/verify/) runs the generated tree through install / type-check / lint / build, parses the output into structured errors, and routes per-file repair agents. Repair is hard-capped at 3 rounds (maxRepairRounds), then the build is marked failed with the remaining errors.

LLM calls reuse the shared generation infrastructure (createGapLLM); CI runs through an injected VerifyDriver (createNodeDriver), so the pipeline is testable with fakes.

Deploy

Provisioning + deploy adapters live in lib/builder/deploy/ (github.ts / github-client.ts via Octokit, vercel.ts, env.ts). The orchestrator pushes the verified tree to a new private GitHub repo, then triggers a Vercel deploy linked to it; secrets are stamped into the Vercel project env and never committed (the repo ships .env.example only). A Vercel failure leaves the repo intact (deployUrl stays null) rather than losing the build.

Current state of the last mile. Per-user token provisioning is live for all three providers: deploy resolves each user's OAuth token from app_integrations → Supabase Vault via getUserProviderToken (lib/builder/integrations/tokens.ts); tokens are captured by the OAuth callback at app/api/integrations/[provider]/callback. For GitHub there is no silent fallback to VibeMap's shared GITHUB_PAT (that would push the user's app into VibeMap's account) — the shared PAT is only used behind the internal BUILDER_ALLOW_SHARED_GITHUB_PAT flag; without a token the build runs in build-only mode (no deploy, graceful skip). Vercel falls back to process.env.VERCEL_TOKEN. Repo reuse across rebuilds is handled by a stable per-project repo name (builderRepoName) plus an idempotent createRepoWithFiles, and a ZIP-artifact producer uploads to the app-builder-artifacts bucket with a 30-day retention prune after each successful run. The Inngest function runs with retries: 0 — by design, a user must manually retry from the UI (cost control).

Per-user Supabase connect

lib/builder/integrations/supabase-mgmt.ts owns everything against the management API (https://api.supabase.com/v1) with the user's OAuth grant — there is no VibeMap-credential fallback anywhere; an unresolvable grant reads as "not connected" and the deploy keeps placeholders:

• OAuth — provider supabase in the registry: PKCE S256 (verifier in an httpOnly cookie scoped to the callback), Basic-auth token exchange, response_type=code. Requires SUPABASE_OAUTH_CLIENT_ID / SUPABASE_OAUTH_CLIENT_SECRET (OAuth app registered in the Supabase org dashboard); until set, the Build tab shows "Setup required".
• Expiring grants — the Vault secret is a JSON grant {access_token, refresh_token, expires_at}; getSupabaseConnection transparently refreshes and rotates the secret (create new → repoint row → delete old; Vault has no update RPC).
• Deploy target — GET/POST /api/integrations/supabase/projects lists the user's projects and persists the chosen ref on app_integrations.metadata.project_ref (validated against the live project list first). Deploy stamps https://{ref}.supabase.co + the anon key into the Vercel env via resolveUserSupabaseEnv.
• Schema apply (opt-in) — with applySchema: true on the build request (per-build checkbox, never remembered), a successful build runs the generated supabase/migrations/*.sql in filename order via POST /v1/projects/{ref}/database/query; the first failure stops the sequence and is surfaced in the stage line + PostHog, without failing the build.
• Kill switch — the whole feature sits behind the builder_supabase_connect subsystem flag.

Data model

build_runs.status is constrained to pending → compiling → filling → verifying → deploying → succeeded / failed (migration supabase/migrations/20260605120001_build_runs.sql, which also defines the report columns gap_results / unsupported / ownership_violations). The generated file tree itself is stored in a Supabase Storage bucket keyed by build run ({userId}/{buildRunId}.files.json + .zip), not in Postgres. Per-gap state — including spec hashes, reuse, report-only test failures, and chat-edit status — lives inside the gap_results JSONB (shape: GapResult in lib/builder/types.ts), so iteration features need no extra tables.

Surfaces

The gating flag

Access is controlled by the buildApp feature flag in lib/billing/plans-config.ts, checked with canAccessFeature(planName, "buildApp") on both the API route and the Build page:

• Free / Starter — false.
• Pro / Team / Enterprise — true (App Builder is a Pro+ feature).
• Admin — true (admins, resolved via the is_billing_exempt RPC, get all features).

Where to go next

• The data model the compiler reads → 2.2 The data model in plain English.
• How the rest of the pipeline works → 2.1 How VibeMap works.
• How architecture choices drive the build → 9.2 Architecture configuration.
• The user-facing guide → User docs: 12 App Builder.