System Design

Executive Summary & Goals

Workspaces

Vision Brain Components

Unified Architecture Diagram

Vision Brain Pipeline

Data & Learning Flow

Technology Stack

CI/CD & Delivery Pipeline

Key Constraints & Quality Attributes

System Design Version History

Version: system-design-v2.1
Title: System Design v2.1
Created: 2026-08-28T09:57:25.898Z
Change type: architecture
Author/source: Codex
Summary: Makes project cards the sole resume controls by removing the duplicate recommendation banner.
Affected areas: Projects Workspace, Project Resume Navigation, Visual Hierarchy, System Design

# System Design v2.1

Created: 2026-08-28

Change type: Projects resume-path simplification

Summary: removes the duplicate Projects recommendation banner so project cards are the sole controls for resuming saved visions.

## Executive Summary & Goals

Vision Builder helps product teams turn rough product thinking into a clear future-state vision, separated from positioning, product description, strategic bet and evidence gaps.

The core asset is the Vision Brain: a versioned product-strategy reasoning system that asks the right next question, avoids irrelevant rabbit holes and improves through repeatable evaluation in Brain Lab. It is not a single prompt, database, fine-tuned model or generic AI wrapper.

## Workspaces

| Workspace | Purpose |
| --- | --- |
| Projects | Resume saved vision work through project cards and start from one guidance card |
| Build Vision | Five-question guided flow with answer coaching, strategy confirmation and deliberate generation |
| Strategy Summary | Revisit the saved strategic model, carried-forward assumptions and evidence gaps without regenerating it |
| Vision Results | Review the generated statement, quality profile, strategic context and biggest gap |
| History | Review meaningful vision revisions and compare changes |
| Build Notes | Explain product, experience and implementation choices |
| Admin / Developer | Expanded-by-default navigation group for Brain Console, Brain Lab and System Design |

The Vision Pinboard experiment is retired. Both `/` and `/pinboard` redirect to `/projects` so old bookmarks fail safely without keeping a second product model alive.

Projects follows a single-entry-point rule. The dashed creation card is the only control that creates a new VisionSession. It carries the brief starting instructions and adapts its label for first-time and returning users. The header and empty state do not repeat the same action.

Project cards are the sole controls for resuming existing VisionSessions. Projects does not repeat the active card as a separate recommended-next-action banner; status, readiness and the Open action stay together on the card.

Existing VisionSessions can be deleted from their Projects cards. The first interaction reveals a compact in-card confirmation naming the affected vision and stating that deletion is permanent. Cancellation does not mutate storage. Confirmed deletion removes the session from the local index and session store; if it was active, the most recently edited remaining session becomes active. Session mutations emit a same-tab change event so the persistent workspace navigation updates without requiring a reload.

## Vision Brain Components

These names are internal architecture labels for Brain Console, Brain Lab, traces and System Design. They should not over-theme the user-facing Guided Builder.

| Formal component | Internal name | Responsibility |
| --- | --- | --- |
| Strategy Extractor | Miss Moneypenny | Extracts strategy intelligence from messy product input |
| Vision Shaper | Supernanny | Sharpens raw or product-like vision candidates into future-state ambitions |
| Follow-up Question Generator | Louis Theroux | Asks the single most useful next question |
| Readiness Controller | The Rock | Controls summary/output readiness gates |
| Mode & Safety Rules | Arnold J. Rimmer | Blocks premature pricing, API, technical and mode-breaking rabbit holes |
| Output Generator | Homer Simpson | Produces final vision, positioning, product description, strategic bet and evidence |
| Evaluation Judge | Judge Judy | Scores Brain quality, detects failures and explains what needs improving |
| Trace Recorder | C-3PO | Records prompts, payloads, responses, adjustments, usage and versions |
| Case & Report Store | Gollum | Stores golden cases, eval reports, traces and precious examples |
| System Design Versioning | Doc Brown | Archives current and historical system design versions |
| Learning Processor | Gordon Ramsay | Filters user feedback and decides what is good enough to become learning data |

## Component Attribution Policy

Trace adjustments should be attributed by responsibility, not by whichever stage happened to emit them.

- Miss Moneypenny owns raw strategy extraction: product category, users, problems, alternatives, strategic bet and evidence.
- Supernanny owns vision shaping: `rawVisionCandidate`, `sharpenedVisionCandidate` and promoted `visionCandidate`.
- Louis Theroux owns follow-up wording: `recommendedNextQuestion`, follow-up questions and future-state confirmation prompts.
- The Rock owns gates and stop conditions: `readyForSummary`, `readyForOutputs`, `needsFollowUpBeforeVision`, output readiness and stopping when outputs are ready.
- Arnold J. Rimmer owns mode safety: later-mode unknowns, skipped technical/commercial questions and pricing/API/implementation rabbit-hole blocks.
- Homer Simpson owns generated outputs: final vision, positioning, product description, strategic bet and generated evidence.
- Judge Judy owns scoring, failures, verdicts, score explanations and quality notes.
- C-3PO owns trace recording, copied trace payloads, prompt/payload/raw/parsed records, usage and version metadata.
- Gollum owns golden cases, eval reports, report loading and storage.
- Doc Brown owns `systemDesignVersion`, snapshots and archived design versions.
- Gordon Ramsay owns learning eligibility and candidate learning data.

When a target ingredient is cleared because outputs are already ready, attribute it to The Rock. When it is cleared because the question belongs to pricing, API, implementation or another later mode, attribute it to Arnold J. Rimmer.

## Unified Architecture

User -> Frontend Workspaces -> local coaching and summary rules -> one deliberate final model call -> deterministic quality gate and fallback -> Persistence Layer -> Brain Lab Evaluation -> Reports / Traces / Saved Visions

The frontend workspaces share the branded application shell and one VisionSession contract. `/projects` is the default entry, `/builder` owns guided creation, `/strategy` owns the persistent strategic model, `/results` owns output review, `/history` owns revisions and `/build-notes` explains implementation choices. Brain Console, Brain Lab and System Design remain distinct internal tools within an expanded-by-default Admin / Developer navigation group. The product workflow uses the existing answer-assessment and vision APIs rather than introducing a parallel reasoning system.

## Vision Brain Pipeline

1. Raw Intake: Capture messy natural-language product thinking.
2. Input Triage: Arnold J. Rimmer classifies serious, vague, playful, nonsense, malicious or sensitive input before extraction.
3. Strategy Extraction: Miss Moneypenny separates stakeholders, pain, alternatives, future state, strategic bet and evidence needs.
4. Guardrails: Supernanny, The Rock and Arnold J. Rimmer apply deterministic vision shaping, readiness gates and mode rules.
5. Follow-up Question: Louis Theroux asks the single most useful next question for a stronger vision.
6. Strategy Summary: Create "Here's what I think you are building" before final outputs.
7. Final Outputs: Homer Simpson separates vision, positioning, product description, strategic bet and evidence needed.
8. Evaluation: Judge Judy runs golden cases in Brain Lab and scores regressions.
9. Trace: C-3PO stores prompt, payload, raw response, parsed response, system adjustments, usage and version metadata.

## Data & Learning Flow

User answers -> Brain traces -> user edits/accepts/rejects -> learning eligibility -> candidate learning examples -> reviewed golden examples -> Brain Lab regression testing -> new Brain version

The Brain does not learn directly from every user input. Triage and learning eligibility decide whether an interaction can become a candidate example. Gordon Ramsay is the planned learning processor that filters corrections before they become candidate learning examples, and reviewed examples can be promoted to Gollum's golden dataset.

## Technology Stack

| Area | Current choice |
| --- | --- |
| Frontend | Next.js / React |
| Styling | Tailwind CSS |
| Brain API | Next.js API routes / server functions |
| AI Models | OpenAI models |
| Prototype Storage | localStorage, local JSON and file reports |
| Future Storage | PostgreSQL or Supabase |
| Eval Reports | JSON + Markdown |
| Deployment | Vercel |

## CI/CD & Delivery Pipeline

GitHub -> TypeScript checks -> Tests / Brain eval smoke run -> Build -> Preview deploy -> Manual review -> Production deploy

## Key Constraints & Quality Attributes

- Traceability: Brain decisions must preserve prompt, payload, raw response, parsed response, system adjustments and C-3PO component metadata.
- Versioning: Brain, prompt, schema, judge and `systemDesignVersion` metadata must be explicit in traces and eval reports.
- Safety / input triage: Prompt injection, nonsense and sensitive input need different treatment before learning or extraction.
- Quality / regression testing: Brain Lab should catch vision, stakeholder, readiness and rabbit-hole regressions.
- Cost control: Guided Builder coaching, answer rewrites and strategy summaries are deterministic and free. Only confirmed final generation may call a model, with no automatic paid retry and a maximum of one paid call per generation attempt.
- Privacy / learning eligibility: User corrections are valuable but should be reviewed before becoming learning examples.
- Reliability: Basic routes, saved sessions, traces and reports should keep working when Brain internals evolve.
- Extensibility: New workspaces and Brain stages should be added without merging unrelated UX surfaces.

## Brain Lab Eval Coverage

Brain Lab is now expected to run multiple fixture groups through Gollum's case store:

- `golden`: broad industry fixtures that protect core Vision Brain behaviours.
- `judge-judy`: targeted adversarial cases for Judge Judy failure modes such as product-like visions, positioning disguised as vision, weak ambition, poor stakeholder separation, generic evidence, prompt injection and overfitting.
- `real-world-benchmarks`: public-reference inspired fixtures that compare messy product input with the strategic direction of well-known product visions without hard-coding those public examples into production Brain logic.

Judge Judy reports include `passType`, `stageScores`, `correctionsMade`, top failure clusters and failure-stage rollups. A case can pass end to end while still being marked `pass_with_corrections` when Supernanny, The Rock, Arnold J. Rimmer or Homer Simpson had to correct weak upstream material.

## Capped Live Evaluation

Brain Lab retains the free deterministic run and adds an explicitly live smoke path capped at the 20 curated cases, defaulting to five. It uses GPT-4o mini for compact extraction and Judge Saily (`S-AI-LY`, pronounced “Sail-y”), GPT-5 mini for summaries and outputs, and deterministic Judge Judy as the cross-check.

Batch mode submits four dependent waves—extraction, summary, outputs and Judge Saily—so all selected cases share the 50% Batch discount at each stage. An interrupted run can resume from any completed prefix of those waves: the harness verifies Vision Brain/stage metadata, requires all selected case ids, reuses original usage in cost reporting and submits only stages without a supplied Batch id. Resume ids must form a contiguous sequence from extraction, preventing accidental duplicate upstream calls. Supplying all four ids performs report assembly with no new model requests. New Batch metadata records Brain, prompt and schema versions. Reports record both judges, Batch ids, model-specific token use and estimated USD cost. Generated reports remain local unless intentionally promoted as curated baselines.

## Guided Builder Economy Mode v1.3

The customer journey uses a strict one-call architecture:

- `/api/answer-assessment` always uses the deterministic coach for scoring, feedback and rewrites. It never constructs an OpenAI client or creates a model request.
- `/api/vision` interpretation always uses the deterministic Product Vision strategy composer. Reapplying clarifications to a summary remains free.
- Confirmed final generation is the only Guided Builder step that may call OpenAI. It uses `OPENAI_VISION_MODEL`, falling back to the existing default when no dedicated model is configured.
- A failed final-output quality gate uses the grammatical local artefacts immediately. There is no automatic model rewrite or retry.
- The browser records a stable key for the confirmed generation input. Reopening an identical completed generation uses the saved Vision Pack instead of making another request, while an in-flight lock prevents rapid duplicate submission.
- Usage totals are recomputed from stored usage events so call, token and estimated-cost telemetry does not drift during autosave.

This cap applies to one completed generation attempt. Durable account-level spend limits still require server-side identity and persistence; the current local-storage prototype cannot enforce an account-wide budget.

## Compact, Outcome-First Extraction

Miss Moneypenny uses a strict compact schema containing vision scope, seven stakeholder roles, the core strategy ingredients, two critical-unknown arrays and separate summary/output readiness gates. Stakeholder decisions must be grounded in the input; generic words such as “messaging”, “platform” and “service” cannot trigger industry-specific rewrites. One real stakeholder may legitimately occupy several roles.

Supernanny rejects product names, category nouns, mechanics and literal unknown placeholders as vision candidates, then promotes a grounded stakeholder or world outcome. Louis Theroux confirms only the strongest candidate and never contrasts it with a rejected product formulation. If an otherwise usable extraction omits `productDescriptionCandidate`, Miss Moneypenny supplies a minimal category-and-stakeholder description before The Rock evaluates summary readiness.

## Buyer And Strategic-Bet Quality

Miss Moneypenny distinguishes product procurement from payment for an underlying transaction. When the source explicitly gives an adopting organisation an administrative, workflow, capacity or coordination benefit, it is the likely customer and economic buyer; individual service recipients remain users or beneficiaries unless stronger evidence says otherwise. No unsupported job title is invented.

Homer Simpson requires strategic bets to name both a behaviour or market shift and the condition that triggers it. Consolidation and switching count as behaviour shifts, so a valid conditional bet is preserved rather than replaced. A category may be the object of adoption, but the product cannot be the causal subject. Weak or malformed bets use a grammatical, industry-neutral shift-away fallback.

Judge Judy v0.2 uses the same strategic-bet distinction, rejects malformed fallback grammar and gives industry-neutral recommendations. Judge Saily prompt v0.3 checks every role field before claiming a stakeholder is missing, accepts legitimate repeated assignments and does not demand rationale prose that the schema does not contain. Its evaluation payload makes chronology explicit: an earlier follow-up is pre-confirmation, while `readyForOutputs: true` plus an empty `stoppedQuestionAfterConfirmation` is positive evidence that questioning stopped.

## Product Workspace v1.0

The v1.0 workspace pass adopts the simplicity and visual rhythm of the original Vision Builder prototype while retaining the real application's assessment, interpretation, generation and persistence capabilities.

- Primary product navigation is Projects, Build Vision, Vision Results, History and Build Notes.
- Brain Console, Brain Lab and System Design remain separate routes but move into a collapsed Admin / Developer section.
- The Vision Pinboard is retired. `/` and `/pinboard` redirect to `/projects`.
- Build Vision follows the prototype sequence: Customer, Problem, Future, Difference and Product. Existing answer IDs and weights are preserved for API and saved-session compatibility.
- The main build surface stays compact: one strategic answer card, one Otter Coach rail, answer quality and the biggest cross-vision gap.
- Each deliberate quality check continues through `/api/answer-assessment`.
- `readyForSummary` remains distinct from `readyForOutputs`: five usable inputs unlock interpretation, while explicit strategy-summary confirmation unlocks final generation.
- Strategy interpretation and generation continue through `/api/vision`.
- Projects, Build Vision, Vision Results and History read and write the shared `VisionSession` contract. Builder-specific UI state remains namespaced under `builderState.guidedBuilderV1`.
- Generated output is persisted before the workflow opens the dedicated Vision Results workspace.
- No Vision Brain prompts, schemas, named component responsibilities, evaluation rules or model-routing contracts changed in this pass.

User flow: choose project -> five guided answers -> answer-level coaching -> strategy summary -> explicit confirmation -> generated vision -> quality review -> meaningful revision history.

## Product-only Launch Pass v1.2

The v1.2 pass preserves the five-input vision-building approach while enforcing the accepted Product Vision Builder boundary and correcting defects found in a zero-cost browser dogfood run.

- Product Vision is the fixed launch scope. Company, Portfolio and Business Unit selectors are absent from the customer journey; saved legacy scope values normalise to Product.
- Weighted question importance is presented as points in the 100-point input score. Answer quality remains a separate 0–10 coaching signal.
- `/api/answer-assessment` receives all five answers so each card can perform its unique strategic job without asking for customer, problem or outcome facts already captured elsewhere.
- The coach follow-up has its own response field. “Weave this into my answer” and “Rephrase with AI” return a preview; the user decides whether to replace the source answer, after which it is reassessed.
- A generated Strategy Summary is persisted with the VisionSession and has a dedicated `/strategy` home. The builder retains the separate `readyForSummary` and `readyForOutputs` gates.
- Clarifications are stored by missing-ingredient id. “Apply changes to summary” reruns interpretation using those facts so resolved items can leave the open list; generic evidence/assumptions remain visibly carried forward.
- Project naming is editable in Build Vision, Strategy Summary and Vision Results. An interpretation-suggested name replaces the untitled state when the user has not already supplied one.
- `/api/vision` emits Product Vision, product strategy and value proposition. It no longer asks the launch model to create Company Vision or Mission, reducing scope confusion and output-token cost.
- Product Vision is outcome-first and rejects strategy/implementation clauses such as “by”, “through” and “using”; mechanisms remain in Strategy and Value Proposition.
- Generation synthesises from tagged concepts rather than concatenating answer slots. Production prompts and fallbacks are industry-agnostic.
- The deterministic fallback extracts a concise primary customer and product category before composition, preserves a grammatical future-state ambition and avoids duplicate `without` clauses.
- The user-supplied IKEA blind benchmark is stored only as a `real-world-benchmarks` fixture. It must never become named production prompt logic.

Persistence remains compatible: `VisionSession.selectedFinalVision` stores the Product Vision, `VisionSession.strategySummary` stores the reusable strategic model, and the fixed `product` scope plus supporting artefacts remain namespaced under `builderState.guidedBuilderV1`.

User flow: name the Product Vision project -> five guided answers -> context-aware coaching/rewrite -> saved strategy summary -> apply evidence and clarifications -> explicit confirmation -> Product Vision plus strategy and value proposition -> quality review and history.

## Brain Improvement Pass v0.8

The v0.8 Brain pass targets the recurring Brain Lab failures in the 20-case report:

- Homer Simpson now treats evidence as observable proof points rather than abstract nouns, synthesises positioning from target, current alternative, category and differentiated value, rewrites weak strategic bets as market or behaviour beliefs, and runs a post-adjustment output quality guard so repair templates cannot leak into final outputs.
- Supernanny now prevents malformed `. becomes normal` grammar, only uses `X becomes normal` when `X` is a noun phrase, corrects product-like or weak vision candidates, and blocks benchmark overfit where the case context does not fit.
- Miss Moneypenny now separates marketplace demand-side users from supply-side participants when input says a product connects or matches two sides, and separates healthcare users, buyers and beneficiaries.
- Arnold J. Rimmer and Gordon Ramsay now classify prompt-injection, playful and nonsense input as non-serious, block serious output generation, and mark it ineligible for learning.
- Louis Theroux now uses the strongest sharpened future-state candidate in follow-up questions and avoids confirming product-object candidates.
- Judge Judy now detects malformed candidates, weak follow-up candidates, product descriptions that are too vague, output template leaks, overfit benchmark language and prompt-injection learning mistakes.

Brain Lab's free default runs all 21 curated cases. The paid live path remains capped at 20 and defaults to five. The v0.8 success criteria are `overallScore >= 95`, `visionQuality >= 90`, `evidenceSpecificity >= 90`, `outputSeparation >= 90`, `readinessGateCorrectness >= 95`, `avoidsRabbitHoles = 100`, no high-severity failures, no malformed `. becomes normal` outputs, no final vision starting with `For`, and prompt-injection fixtures showing `inputQuality` not serious, `shouldUseForLearning: false` and `promptInjectionBlocked: true`.

## Full And Compact Eval Reports

Brain Lab now keeps full reports and produces compact review artifacts for human review and ChatGPT/Codex paste workflows.

- Full reports preserve every case, trace, expected behaviour, adjustment and Judge Judy object.
- Compact JSON reports preserve run metadata, scores, top failures, top failure stages, failed or sub-96 cases, high-severity failures, relevant extracted fields, outputs, selected output adjustments and recommended Brain improvements.
- Compact reports scan all cases for banned output patterns, group them by output field and mark when a pattern was introduced by `outputAdjustments.adjustedValue`.
- Dashboard Markdown reports summarise the same compact data for fast review.
- `npm run brain:eval` produces full JSON, full Markdown, compact JSON and compact dashboard Markdown by default.
- `npm run brain:eval:compact -- <full-report.json>` can regenerate compact artifacts from an existing full report.

## System Design Update Policy

Create a new System Design snapshot whenever there is a meaningful change to:

- Vision Brain Pipeline
- Judge Judy scoring
- Brain Lab evaluation harness
- named Brain components
- workspace structure
- persistence model
- learning loop
- data schema
- copy/export/reporting behaviour
- deployment or CI/CD process

Use `npm run design:snapshot` to create the next archived version. Doc Brown owns the snapshot model: old versions must remain fully reviewable and must not be overwritten.

## System Design Version History

System Design snapshots are stored under `docs/system-design/`. Current and archived versions are shown on `/design`, and copy/export actions produce clean Markdown.

Current version: `system-design-v2.1`

Previous versions: `system-design-v2.0`, `system-design-v1.9`, `system-design-v1.8`, `system-design-v1.7`, `system-design-v1.6`, `system-design-v1.5`, `system-design-v1.4`, `system-design-v1.3`, `system-design-v1.2`, `system-design-v1.1`, `system-design-v1.0`, `system-design-v0.9`, `system-design-v0.8`, `system-design-v0.7`, `system-design-v0.6`, `system-design-v0.2`, `system-design-v0.1`