solution.md is the technical blueprint of a spec bundle: the technology stack, high-level architecture with Mermaid and C4 diagrams, system modules with interfaces and data models, the entity-relationship model, API design, security, deployment, success criteria tied to NFRs, and key decisions with alternatives. It uses only technologies the constitution approves and provides a design for every requirement.
The brief said "a three-bedroom house with a home office". The drawing set says where the load-bearing walls go, how the plumbing runs, and which wire feeds which socket - on separate sheets (site plan, floor plan, electrical, plumbing) that all describe one building. solution.md is that set: the architecture flowchart is the site plan, the ER diagram the floor plan, the sequence diagram the plumbing. Different sheets, one consistent structure, so no two builders (or agents) improvise a different house.
Why the HOW gets its own file
Without a written design, a coding agent invents the schema on task 1 and a different one on task 7. solution.md pins the shape of the system - modules, entities, endpoints, error codes - before any task exists, so every task implements the same design. It also records why: each significant decision lists its rationale and the alternatives rejected, which is what reviewers ask about six months later.
- Constrained by the constitution - only approved technologies; the reviewer checks the stack table against it.
- Complete over the requirements - every FR maps to a module or decision; every measurable NFR becomes a Success Criteria row.
- Sized to the project - optional sections are omitted, never padded with placeholders.
Where it lives and when it is written
In the MySpec greenfield workflow it is stage 4, written to specs/<bundle>/solution.md after the requirements are approved: a collect substage asks about the choices the constitution left open (hosting, data store, integration style), generate drafts the document, and review checks coverage and constitution compliance. Older bundles named the file design.md; it carries the same solution file type and the MCP server matches on type, not name.
The other methodologies split this job differently: Spec Kit's plan.md is a solution-style plan with constitution gates, and OpenSpec's design.md is a short, optional decisions record for a single change.
The sections
# System Solution: [Project Name]
## Overview
### Description 1–3 paragraphs: what, architectural style, which FRs
### Technology Stack | Component | Technology | Rationale | (≤ 8 rows)
### Design Decisions Summary | Decision | Choice | Rationale | (≤ 6 rows)
## High-Level Architecture Design
### Architecture Description ≤ 6 bullets: subsystems + request flow
### Architecture Diagram Mermaid flowchart
### C4 Context / Container diagrams the system in its environment; its deployable units
### Module Interactions [optional] Mermaid sequenceDiagram (required with 3+ modules)
## System Modules per module: Responsibilities, Key Components,
Key Interfaces, Data Models, Dependencies, Error Handling
## Data Model
### Entity-Relationship Diagram Mermaid erDiagram
### Entities purpose, key fields, relationships, indexes / constraints
## API / Protocol Design REST / Messaging / WebSocket / Schemas / Error Codes - only what applies
## Security Architecture Authn & Authz · Input Validation · Data Protection
## Deployment & Operations Infrastructure Layout · Scaling Strategy · Configuration
## Observability [optional] Tracing · Structured Logging · Metrics & Alerts
## Testing Strategy [optional]
## Success Criteria | Criterion | Target | Measurement | one row per measurable NFR
## Key Solution Decisions | Decision | Rationale | Alternatives Considered |
Per-module sections repeat as ### Module N: [Name] and never nest deeper than ####. Code blocks are language-neutral pseudocode in text fences - the solution describes interfaces and shapes, not implementation.
### Module 2: Billing
**Responsibilities**
- Meter usage events idempotently; compute invoices in integer cents.
**Key Interfaces**
```text
recordUsage(tenantId, idempotencyKey, units) -> UsageEvent | DuplicateAck
closePeriod(tenantId, period) -> Invoice
```
**Data Models**
```text
UsageEvent { id, tenantId, idempotencyKey (unique per tenant), units > 0, recordedAt }
```
**Dependencies** - Identity (tenant lookup), Persistence (Postgres)
**Error Handling** - duplicate key → cached 200; missing tenant → 404 problem+jsonThe diagrams it must contain
Diagrams are not decoration here; the reviewer fails a solution without them. Every Mermaid block renders live in the MySpec editor, and labels with spaces, parentheses, or non-ASCII characters are quoted so they render everywhere.
| Diagram | Mermaid type | Required? | Shows |
|---|---|---|---|
| Architecture | flowchart | Always | Subsystems and the request flow between them |
| C4 Context + Container | C4Context / C4Container | When your org enables C4 diagrams | The system among its users and neighbours; its deployable units and data stores, named exactly as the modules and infrastructure sections name them |
| Data model | erDiagram | Always | Entities, cardinalities, relationships |
| Module interactions | sequenceDiagram | With 3+ modules | The happy path across internal modules |
| Lifecycle | stateDiagram-v2 | Optional | Workflow or entity state transitions |
```mermaid
flowchart TB
subgraph Client
Web[Web App]
end
subgraph Backend
API[API Gateway]
Service[Service Layer]
DB[(Database)]
end
Web --> API --> Service --> DB
```
```mermaid
erDiagram
User ||--o{ Order : places
Order ||--|{ OrderItem : contains
Product ||--o{ OrderItem : includes
```
```mermaid
sequenceDiagram
Client->>+API: Request
API->>+Service: Process
Service->>+DB: Query
DB-->>-Service: Result
Service-->>-API: Response
API-->>-Client: Response
```Authoring and review rules
- Uses only technologies approved in the constitution; the stack table has at most eight rows.
- Every functional requirement has a corresponding solution; every measurable NFR maps to a Success Criteria row.
- Decisions carry rationale and alternatives considered; the design follows SOLID and accounts for operations.
- Contains the required Mermaid and C4 diagrams, with names consistent between diagrams and prose.
- Reflects the user's explicit choices from the collect substage - the generator does not override them.
- Placeholder-padded optional sections, or a document scaled for an enterprise when the project is a CLI.
- Real code instead of pseudocode; module sections nested beyond four heading levels.
- A schema or API that contradicts an acceptance criterion, or a stack choice the constitution forbids.
- Metadata footers (version, date, status).
How coding agents use it
- Schema and contract source. An agent implementing a task reads the entity definitions, interfaces, and error codes here instead of inventing column names - the single biggest source of silent bugs in prompt-driven builds.
- Module vocabulary. tasks.md is required to use the modules, APIs, and data models named here, so a task title tells the agent exactly which sheet to open.
- Review anchor. "Architecture matches solution.md diagram" is a checkable PR statement; via the MCP server a reviewer bot can
read_spec_fileand compare.
Related spec files
Project vision, core principles, and the MUST / MUST NOT constraints every later file has to obey.
User roles, FR-/NFR- requirements with EARS+ acceptance criteria; a coded AR-/BR-/CR- delta for brownfield changes.
Architecture, modules, data model, and API design with Mermaid flowchart, ER and sequence diagrams - plus C4 diagrams when your organisation enables them.
Ordered, sized implementation tasks grouped into milestones, traced back to requirement IDs.
Why a brownfield change is needed, what changes, the technical solution, and its impact on existing code.
Spec Kit's prioritised user stories and success criteria, or OpenSpec's ADDED / MODIFIED / REMOVED / RENAMED requirement deltas.
Spec Kit's technical plan: technical context, constitution gates, architecture, data model, and key decisions.
OpenSpec's optional context, goals / non-goals, decisions, and risks for a change.
Workflows that write it
The default four-file bundle: interview → constitution → requirements → solution → tasks.
GitHub Spec Kit's feature-scoped flow: interview → constitution → specify → plan → tasks.
OpenSpec's change-proposal flow: explore → proposal → delta specs → design → tasks.
Let the AI Architect write it for you
MySpec interviews you, then drafts every spec file with collect → generate → review gates. Free during Open Beta.