Architecture
Transform a PRD into an implementation-ready architecture document. Read docs/PRD.md, analyze requirements, and produce docs/ARCHITECTURE.md with enough technical clarity to start coding.
Workflow
START
│
▼
┌─────────────────────────┐
│ Read docs/PRD.md │ ◄── Load the PRD into context
└──────────┬──────────────┘
│
▼
┌─────────────────────────┐
│ Analyze & Clarify │ ◄── Ask questions if PRD has gaps
└──────────┬──────────────┘
│
▼
┌─────────────────────────┐
│ Confirm with user │ ◄── Summarize approach, get approval
└──────────┬──────────────┘
│
▼
┌─────────────────────────┐
│ Generate Architecture │ ◄── Write to docs/ARCHITECTURE.md
└─────────────────────────┘Step 1: Read the PRD
Read docs/PRD.md to understand:
- What the product does and who uses it
- User scenarios and flows
- Tech stack specified (or constraints)
- Scope boundaries (MVP vs future)
If docs/PRD.md doesn't exist, ask the user to provide requirements or suggest using the product-design skill first.
Step 2: Analyze & Clarify
Identify gaps that would block architecture decisions:
- Ambiguous scaling requirements?
- Missing auth/authorization details?
- Unclear data relationships?
- Integration specifics missing?
Ask targeted questions. Don't over-ask—only what's needed to make architecture decisions.
Step 3: Confirm with User
Before generating, summarize:
- The high-level approach (e.g., "monolith with clear module boundaries" vs "microservices")
- Key technical choices and why
- Any tradeoffs being made
Ask if they're ready to proceed or want to adjust the approach.
Step 4: Generate Architecture Document
Write to docs/ARCHITECTURE.md (create directory if needed) using the template below.
Architecture Document Template
# [Product Name] - Architecture
## Overview
[2-3 sentences: architectural style, key patterns, deployment model]
## High-Level Architecture
[ASCII diagram showing major components and relationships]┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Client │────▶│ Server │────▶│ Database │ └─────────────┘ └─────────────┘ └─────────────┘
### Components
| Component | Responsibility | Technology |
|-----------|---------------|------------|
| [Name] | [What it does] | [Stack] |
## Tech Stack Decisions
| Decision | Choice | Rationale |
|----------|--------|-----------|
| Frontend | [e.g., Next.js] | [Why this fits the requirements] |
| Backend | [e.g., Node + Express] | [Why] |
| Database | [e.g., PostgreSQL] | [Why] |
| Auth | [e.g., Supabase Auth] | [Why] |
| Hosting | [e.g., Vercel + Railway] | [Why] |
## Directory Structureproject/ ├── src/ │ ├── app/ # [Purpose] │ ├── components/ # [Purpose] │ ├── lib/ # [Purpose] │ └──... ├── public/ ├── tests/ └──...
### Key Directories Explained
- `src/app/` - [What goes here and why]
- `src/lib/` - [What goes here and why]
## Key Abstractions
### [Abstraction 1 Name]
**Purpose:** [What problem it solves]
**Interface:** [Key methods/properties]
**Used by:** [Which parts of the system]
## Data Flow
[Describe data flow for key scenarios]
1. **[Scenario]**: [Step-by-step flow]
## What NOT to Over-Engineer
Keep these simple for MVP:
| Area | Keep Simple | Avoid |
|------|-------------|-------|
| Auth | Use built-in auth provider | Custom JWT infrastructure |
| State | React state/context | Redux unless proven necessary |
| API | Simple REST endpoints | GraphQL unless you need it |
| Database | Single database | Read replicas, sharding |
| Caching | None initially | Redis until you measure need |
| Validation | Validate at boundaries | Defensive checks everywhere |
## Future Considerations
[Things deliberately deferred that may influence future architecture]
- [Future need] → [How current architecture accommodates it]Guidelines
Keep it buildable: Every section should reduce ambiguity. A developer reading this should know where to start.
Match complexity to scope: MVP architecture should be simple. Don't design for scale you don't have.
Be specific: "Use React" is less useful than "Next.js App Router with server components for data fetching."
Justify decisions: Every tech choice needs a reason tied to requirements, not preference.
Name anti-patterns: Explicitly calling out what NOT to build prevents scope creep.