architecture

Architecture Skill

When to Trigger

After docs/specs/<feature>/prd.md is approved. This is Phase 3.

Workflow

Step 1: Read all inputs

• docs/specs/<feature>/brief.md
• docs/specs/<feature>/prd.md
• docs/specs/<feature>/glossary.md (if exists)
• All ADRs in docs/architecture/adr/ (review prior decisions to avoid contradictions)

Step 2: Use Context7 MCP for current library docs

Before recommending any library, fetch its current docs via Context7. Do not rely on training-data knowledge for libraries that change fast.

Step 3: Apply DDD if domain has complexity

If the brief mentions multiple bounded contexts or complex business rules, run the ddd-modeling skill first to identify aggregates, entities, value objects, and bounded contexts.

Step 4: Generate the design doc

Write docs/architecture/<feature>/design.md:

# <Feature> - Architecture Design

## 1. Context (C4 Level 1)
What this system does, who uses it, what external systems it talks to.

## 2. Containers (C4 Level 2)
Each deployable unit: web app, API, worker, DB, cache, queue.

| Container | Tech | Responsibility | Dependencies |
|---|---|---|---|
| ... | ... | ... | ... |

## 3. Components (C4 Level 3, for the most complex container)
Internal modules of the main service.

## 4. Data Architecture
- Primary store: <DB and why>
- Schema overview: <key tables/collections, relationships>
- Migration strategy: <how schema evolves>
- Data lifecycle: <retention, archival, deletion>

## 5. API Contracts
- External APIs exposed: <list with versioning approach>
- External APIs consumed: <list with fallback strategies>
- Internal contracts: <message formats, RPC schemas>

## 6. Cross-Cutting Concerns

### Authentication
<method, libraries, session handling>

### Authorization
<RBAC/ABAC model, enforcement points>

### Observability
- Logs: <structured format, fields, destination>
- Metrics: <names, labels, alerts>
- Traces: <propagation strategy>

### Error Handling
<global strategy: retries, circuit breakers, fallbacks>

### Configuration & Secrets
<source: env vars, vault, k8s secrets>

## 7. Deployment Architecture
- Environment topology
- CI/CD pipeline outline
- Rollback strategy

## 8. Performance & Scale
Map each NFR-Performance target to specific design choice that delivers it.

## 9. Security Threat Model
- Top 3-5 threats
- Mitigations per threat
- Residual risk acknowledged

## 10. Architecture Decision Records (ADRs)
List ADRs created for this design. Each ADR is a separate file:
`docs/architecture/adr/NNNN-decision-name.md`

## 11. Open Risks & Recommendations

(MANDATORY)
- Choices made under uncertainty
- Things that should be load-tested before launch
- Patterns that may not scale to 10x current targets
- Library choices that may be wrong but are fastest now

Step 5: Generate ADRs for major decisions

For every meaningful technical choice, create an ADR using adr-writer skill. Examples of decisions worth an ADR:

• Choosing PostgreSQL over MongoDB
• Using REST over GraphQL
• Adopting a specific framework
• Picking sync vs event-driven communication
• Authentication strategy

Step 6: Run Solutioning Gate Check

Score 0-100:

Criterion	Points
Every FR maps to one or more design components	20
Every NFR has a specific technical solution	20
External dependencies all have fallback strategies	15
Security threat model is concrete	15
Performance design matches targets with sizing math	15
ADRs exist for all major choices	10
Open risks are <5 and acknowledged	5

< 80 = revise before proceeding to implementation.

Step 7: Hand off

Tell user: design ready, gate score X/100. Next phase: implementation, starting with the first slice in the user stories.

Quality Bar

Bad architecture doc: "We will use microservices and Kubernetes for scalability."

Good architecture doc:

The order processing path runs as a single Go service with Kafka for async work. We chose Kafka over RabbitMQ for ADR-0008 reasons. Order events are partitioned by customer ID to preserve order within customer. Expected throughput: 1k orders/sec, partitioned across 16 partitions = 60 orders/sec/partition, well under our measured 500 orders/sec/partition single-consumer baseline.

Recommendations

After publishing the design, always include:

• Things you would do differently if budget were 2x
• Things you would do differently if scale were 10x
• The single biggest risk and how to validate it cheaply before full build