Reference — the `demo/` app (as-built)¶

status: living
date: 2026-06-10
scope: documents the demo/ Next.js app as it actually exists (a framework showcase), not a planned solution

What this is. demo/ is the framework showcase — a single Next.js (App Router) app, in this repo, that exercises the whole docgen pipeline over seeded solution templates. It is not the Odyssey production solution that r3-tdd specs (a separate FastAPI + Next monorepo); that design diverged. The demo is the real, running surface where the framework's features are demonstrated and reviewed. This doc captures its shape so the canonical docs reflect what shipped.

Architecture¶

One repo, one fetch. docgen (Python package, the engine) + demo/ (Next.js) + vendor/altaforge-ui (submodule, the design system) + vendor/altaforge-libraries + vendor/altaml-claude. demo/ consumes altaforge-ui and the built docgen-ui via the pnpm workspace.
Transport. The Next app talks to Python over a long-lived HTTP service — docgen.server (uvicorn @ 127.0.0.1:8769); apps/web/lib/docgen-bridge.ts is the async HTTP client (callBridge(command, args)). No per-call spawnSync (see repo CLAUDE.md).
Auth / tenancy. Real bearer-token auth via @altaml/altaforge-auth (#147) and per-request tenancy via altaforge.auth — the active org is resolved per request (no active-org global; #145). Demos may fake the credential, but the per-request resolution path is the production one.
Dev loop. cd apps/web && pnpm dev (predev builds docgen-ui, frees ports, runs uvicorn + Next together). pnpm dev:stop is the canonical clean restart. pnpm ci:local (= tsc --noEmit && next lint) mirrors the CI gates — run it before pushing.

The document page (`app/docs/[id]`)¶

Region order mirrors the pipeline (gather → compute → synthesize → render):

Region	Component	Notes
Settings	`DocumentActionBar`	Title, description, State (above the title — no badge), Verify-citations toggle, Show-section-headings toggle, and a model/temp row (`Model`, `Temperature`, `Gather model`, `Gather temperature`).
Gather	`FieldsPanel` + `GatheredDataPanel`	Fields and Data sources share one bounding box. Fields = per-doc blanks (badge·key·value rows, hover Edit/Delete, dialog-based create/edit via `AddFieldDialog`). Data sources = the gather data needs.
Compute	`ComputedInspector`	Read-only view of the compute stage (`[T2-computed]`): derived `computed.*` values (JSON), the readiness verdict, and a collapsible "View compute source" (the registered fn's full module, Python-highlighted). On-load + post-Generate via `router.refresh()`.
Synthesis	`SynthesisInspector`	Read-only mega-synth payload (only populated for docs with `synthesized` sections).
Sections	`SectionEditor`	Per-section cards; output rendered in a `ProsePane` (bordered prose box matching the code panes); edit drawer for prompt/render-mode/template.
Versions	`VersionsPanel`	Snapshot history (`[T2-entity-versions]`).
Composition	hidden	`SHOW_COMPOSITION = false` flag; the Snippet-binding panel exists but is hidden in the demo for now.

Left nav (DocNav) mirrors these regions; active state is a container-aware, threshold-based scroll-spy with bottom-of-page handling. The editor/preview drawer opens at ~35% width.

Per-document settings surfaced¶

Model / temperature ([T2-llm-config]): dropdowns; temperature is grayed when the model won't honor it (Claude omits it; OpenAI reasoning models drop it) — only non-reasoning OpenAI models (e.g. gpt-4.1) enable it. Current OpenAI options: GPT-5.5 / 5.5-mini / 4.1.
Show section headings (include_section_headings, default on): when off, section titles are omitted from both the in-app preview (PreviewPanel) and the .docx / markdown export — so memo-style docs read as a flowing letter.
Verify citations: opt-in engine.verify fact-check pass.

Shared UI primitives (altaforge-ui)¶

CodePane — bordered monospace code box (json/yaml/python highlighting).
ProsePane — bordered prose box sharing CodePane's chrome via a composed paneChrome.module.css (zero duplication). Used for rendered section output.

Seeded solutions (demo templates)¶

Each is a seeded template the demo can instantiate + Generate; they prove framework genericity:

Phoenix firm-order memo (fixtures/phoenix.py) — reinsurance memo. P1–P3 templated (deterministic, computed metrics), P4–P5 synthesized (rationale + underlying book — grounded, cited, verified; converted from isolated in the one-big-call rollout, 2 sections = a single batch). Computed layer (phoenix_compute.py) derives MLR/ROL/auth + readiness. 7 seeded deals incl. edge cases. Gold: reference/phoenix-data/expected-memos.json; eval: scripts/demo_phoenix_eval.py.
JBRK reporting letter (fixtures/jbrk.py) — legal letter; Section I templated, Sections II/III composed (composed from Texts + approved risk_blocks). The composition exemplar.
Background check (fixtures/background_check.py) — 12 synthesized sections (the batched mega-synth call) + a templated Disclaimer; the synthesis exemplar.
DealDesk (proposal + SOW), SITE, Carbon Media — all synthesized (dealdesk proposal uses synth_group batching); the one-big-call showcases.

Pointers¶

Engine pipeline + render modes: ../releases/r2-framework-production-features/r2-tdd.md ([T2-render-modes], [T2-computed], [T2-readiness], [T2-llm-config]).
Phoenix as-built analysis: ./phoenix-uc2-analysis.md.
The (divergent, historical) Odyssey solution design: ../releases/r3-odyssey-uat/r3-tdd.md — see its banner.

Reference — the demo/ app (as-built)¶