---
name: design-architecture
description: "Design system architecture based on PRD requirements and analysis. This is the Architect pipeline's core step, comparable to write-a-prd in the PM pipeline. Produces the complete architecture document."
---

This skill produces the complete architecture document for a feature.

**Announce at start:** "I'm using the design-architecture skill to design the system architecture."

## Primary Inputs

- `docs/prd/{feature}.md` (required)
- `docs/architecture/{date}-{feature}-analysis.md` (from analyze-prd, optional)
- `docs/research/{date}-{topic}-architecture.md` (from architecture-research, optional)

## Primary Output

- `docs/architecture/{feature}.md`

**Save architecture to:** `docs/architecture/{feature}.md`
- (User preferences for architecture location override this default)

## Hard Gate

Do NOT start this skill if the PRD has unresolved ambiguities that block architectural decisions. Resolve them with the PM first.

## Process

You MUST complete these steps in order:

1. **Read the PRD** end-to-end to understand all requirements
2. **Read the analysis document** if available, to understand which knowledge domains are relevant
3. **Read the research brief** if available, to inform technology and pattern selections
4. **Design each architecture section** based on PRD requirements and relevant knowledge domains
5. **Apply knowledge domains** as needed - reference relevant knowledge contracts during design:
   - `system-decomposition` when designing service boundaries
   - `api-contract-design` when defining API contracts
   - `data-modeling` when designing database schema
   - `distributed-system-basics` when dealing with distributed concerns
   - `architecture-patterns` when selecting architectural patterns
   - `storage-knowledge` when making storage technology decisions
   - `async-queue-design` when designing asynchronous workflows
   - `error-model-design` when defining error handling
   - `idempotency-design` when designing idempotent operations
6. **Ensure traceability** - every architectural decision must trace back to at least one PRD requirement
7. **Write completeness check** - verify all required sections are present and substantive
8. **Write the architecture document** to `docs/architecture/{feature}.md`

## Architecture Document Template

```markdown
# Architecture: {Feature Name}

## System Overview

High-level description of the system architecture. Map every major PRD requirement to an architectural component. Show component relationships and data flow direction. Identify external system integrations. Document deployment topology when relevant.

Use text or ASCII diagrams for component relationships.

### Requirement Traceability

| PRD Requirement | Architectural Component |
|----------------|------------------------|
| ... | ... |

## Frontend Architecture

Define frontend architecture including component structure, state management, and rendering strategy. If the feature has no frontend component, write `N/A` with a brief reason.

### Component Hierarchy
### State Management
### Routing Structure
### Client-Side Caching

## Backend Architecture

Define backend architecture including service layers, module boundaries, and dependency flow. This section MUST be present for all features with backend implications.

### Service/Module Boundaries
### Layer Separation
### Dependency Flow
### Shared Utilities

## API Definitions

Define all API endpoints with full specifications.

For each endpoint:
- Method and path
- Request schema (headers, path params, query params, body)
- Response schema (success and error responses)
- Status codes
- Authentication requirements
- Idempotency requirements (when applicable)
- Rate limiting expectations (when applicable)
- PRD functional requirement it satisfies

### Endpoint Catalog

| Method | Path | Description | PRD Requirement |
|--------|------|-------------|-----------------|
| ... | ... | ... | ... |

### Endpoint Details

(Define each endpoint in detail)

## DB Schema

Define all database tables, columns, indexes, constraints, and relationships. If the feature requires no database changes, write `N/A` with a brief reason.

### Table Definitions

For each table:
- Table name and purpose
- Column definitions (name, type, constraints, defaults)
- Indexes and their justification
- Foreign key relationships
- Data volume estimates (when relevant)

### Entity Relationships

Describe relationships between tables.

### Migration Strategy

Notes on migration approach if schema changes affect existing data.

## Service Boundaries

Define service boundaries with clear responsibilities.

For each service or module:
- Name and single responsibility
- Owned data
- Communication patterns with other services (sync, async, event-driven)
- Potential coupling points and mitigation

### Communication Matrix

| From | To | Pattern | Protocol | Purpose |
|------|----|---------|----------|---------|
| ... | ... | ... | ... | ... |

## Async Model

Define asynchronous operations and their behavior. If the feature has no asynchronous requirements, write `N/A` with a brief reason.

### Async Operations

For each async operation:
- Operation name and trigger
- Queue or event topic
- Producer and consumer
- Retry policy (max retries, backoff, DLQ)
- Ordering guarantees
- Timeout and cancellation behavior

## Error Model

Define error handling strategy across the system.

### Error Categories
- Client errors (4xx)
- Server errors (5xx)
- Business rule violations
- Timeout errors
- Cascading failure modes

### Error Propagation Strategy
- Fail-fast vs graceful degradation vs circuit breaker
- Fallback behavior

### Error Response Format

Consistent error response schema across the system.

### Observability Hooks
- Logging strategy
- Metrics to track
- Alerting thresholds

### PRD Edge Case Mapping

| Error Category | PRD Edge Case | Handling Strategy |
|---------------|---------------|-------------------|
| ... | ... | ... |

## Idempotency Design

Define idempotent operations and their behavior. If the feature has no idempotency requirements, write `N/A` with a brief reason.

For each idempotent operation:
- Operation name
- Idempotency key source and format
- Key TTL and storage location
- Duplicate request behavior
- Collision handling

## Architectural Decision Records

For each significant architectural decision:

### ADR-{N}: {Decision Title}

- **Decision**: What was decided
- **Context**: Why this decision was needed, including which PRD requirements drove it
- **Alternatives**: What other options were considered
- **Rationale**: Why this option was chosen
- **Consequences**: What trade-offs or implications result
```

## Completeness Check

Before finalizing the architecture document, verify:

1. Every PRD functional requirement is traced to at least one architectural component
2. Every PRD NFR is traced to at least one architectural decision
3. All 9 required sections are present (or explicitly marked N/A with reason)
4. Every architecture section that is not N/A has substantive content
5. All API endpoints map to PRD functional requirements
6. All DB tables map to data requirements from functional requirements or NFRs
7. All async flows map to PRD requirements
8. All error handling strategies map to PRD edge cases
9. ADRs exist for all significant decisions
10. No architectural element exists without traceability to a PRD requirement

Add explicit detail for these when relevant:
- Security boundaries and authentication
- Scalability considerations
- Performance-critical paths
- Data consistency requirements

## Guardrails

This is a pure Architecture skill.

Do:
- Design system structure and boundaries
- Define API contracts and data models
- Define error handling, retry, and idempotency strategies
- Make architectural decisions with clear rationale and alternatives
- Ensure traceability to PRD requirements

Do not:
- Change PRD requirements or scope
- Create task breakdowns, milestones, or deliverables
- Write test cases or test plans
- Write implementation code or pseudocode
- Choose specific libraries or frameworks at the implementation level
- Prescribe code patterns, class structures, or function-level logic

The Architect defines HOW the system is structured.
The Engineering defines HOW the code is written.

## Transition

After completing the architecture document, invoke `challenge-architecture` to validate and stress-test the architecture.