System Design Specification
On this page
System Design Specification
An AI-synthesised architecture document — components, data flows, security model, and decision records — built from your project's own spec. · Optional · Pro plan
Read this if you want a full engineering architecture document to hand a developer or your coding agent — how the system is structured, not just what it should do. If you only want your existing spec rendered as a readable document at no cost, use the Dev Spec tab on your project Overview instead; the two are easy to confuse, so there's a comparison below.
Open System Design from the project sidebar — it sits in the Prepare group, between Prepare for Dev and Sprint planning.
What it produces
System Design runs an AI "architect" over everything you've already generated — your project description, summary, personas, features, schema, and the API endpoints implied by your pages — and writes a single, navigable specification with a sticky table of contents. It always covers these twelve sections, in order:
| # | Section | What it gives a builder |
|---|---|---|
| 1 | System Overview & Context | The system boundary and the actors around it. |
| 2 | Architecture Overview | The high-level shape — layers, services, and how they fit. |
| 3 | Component Design | Each component and its responsibilities, derived from your features. |
| 4 | Data Architecture | How your schema tables relate and where data lives. |
| 5 | API & Integration Design | The endpoints and external services the app talks to. |
| 6 | Key Workflows & Sequence Diagrams | The important paths through the system, step by step. |
| 7 | Non-Functional Requirements | Performance, scale, availability, and other quality targets. |
| 8 | Security & Access Control | The auth model and who can reach what. |
| 9 | Deployment & Infrastructure | How and where the app runs. |
| 10 | Architecture Decision Records | The choices made, with the reasoning behind each. |
| 11 | Technical Risks & Mitigations | What could go wrong and how to handle it. |
| 12 | Open Questions & Assumptions | What the architect assumed, and what still needs a human answer. |
The design is grounded only in your own artifacts — it does no live web research, so it stays anchored to the product you've actually specified rather than inventing outside facts.
Generating it
- Open the System Design page. Before your first run it shows an empty state with a Generate control.
- (Optional) Add notes for the architect — constraints or preferences like "must run on Cloudflare Workers" or "no third-party auth." These act as high-priority overrides: the architect applies them throughout and tags the choices they affect as [USER OVERRIDE].
- Click Generate. The run happens in the background and its progress streams into the agent panel — you can leave the page and come back.
- When it finishes, the spec renders in place with its table of contents. Regenerate at any time to rebuild it from your latest spec; notes are remembered between runs.
Prerequisites. The architect needs enough to work from, so generation is blocked until you have: a project description with real detail (a one-line prompt isn't enough), a generated project summary, and at least one feature — the architecture is designed around your features. If any are missing, the page tells you which to do first.
💡 Tip: Generate this after Prepare for Dev, not before. The richer your spec — pages, schema, resolved coverage — the more concrete and accurate the architecture, because the architect has more to reason from.
⚠️ Watch out: Generating a system design is a Pro-plan step and spends premium tokens. The page itself is visible on any plan, but the Generate button hands Free and Starter users to the upgrade screen. See Account and billing.
How this differs from the Dev Spec tab and Prepare for Dev
Three surfaces sound alike but do different jobs:
| Where | What it is | Cost / plan | |
|---|---|---|---|
| System Design Specification (this page) | System Design in the sidebar | A fresh architecture document the AI writes — ADRs, component design, risks | Generates on demand · Pro |
| Dev Spec tab | Your project Overview strip | Your existing spec rendered as an engineering doc — no generation, always current | Free, any plan |
| Prepare for Dev | Prepare for Dev in the sidebar | The coverage-and-readiness check (interactions, state machines, permissions, data contracts) that makes the spec buildable | See Prepare for Dev |
In short: the Dev Spec tab shows what you already have, Prepare for Dev closes the gaps, and System Design adds an architectural layer of reasoning on top.
⚡ Power-user hints
- Notes are the steering wheel. One line — "target Postgres 16 and Supabase RLS," "keep it a single Next.js app, no microservices" — reshapes the whole document. Regenerate after changing them.
- Pick the model on Pro. The Generate button's model picker lets you run the architect on a stronger reasoning model for a complex system; the default is a solid middle ground.
- Hand the whole thing to your agent. The spec is Markdown — copy it into your IDE agent's context alongside the handoff so it builds against a real architecture, not just a feature list.
- Read section 12 first after a run. Open Questions & Assumptions is where the architect flags what it had to guess — those are the decisions worth making yourself before you build.
↔ The traditional way
A software architect normally spends days turning a PRD into a design doc — drawing component and sequence diagrams, writing ADRs, and enumerating non-functional requirements and risks — then keeps it in sync with the spec by hand. System Design synthesises the same document from your connected spec in one pass, so it's grounded in the exact features, schema, and pages you've already defined rather than a separate artifact that drifts from them.
What's next
- Make the spec buildable first → Prepare for Dev
- Sequence the work into sprints → Sprint planning
- Hand the architecture to your coding agent → Handoff overview
- See the lighter, always-on Dev Spec → The project Overview