/design - Architecture Design

Create architecture documentation and Architecture Decision Records from requirements.

Purpose

Transform PRD requirements into:

• System architecture with components and interfaces
• Data flow and interaction patterns
• Constraints and risk analysis
• ADRs for significant decisions

Inputs

• $ARGUMENTS

  : PRD path or specific focus area (optional)
• Default PRD location:

  docs/architecture/PRD.md

• Existing architecture:

  docs/architecture/ARCHITECTURE.md

• ${PROJECT_NAME}

  : Current project context

Outputs

• Architecture:

  docs/architecture/ARCHITECTURE.md

• ADRs:

  docs/architecture/adr/NNN-decision-name.md

Workflow

1. Read Requirements

Load and understand the PRD:

• Functional requirements define WHAT to build
• Non-functional requirements define HOW it must perform
• User stories provide context for design decisions

2. Research Patterns

• Search for established patterns matching requirements
• Look up framework/library documentation
• Review prior art and alternatives

3. Identify Components

For each major functional area:

• Define component name and responsibility
• Specify interface/API contract
• List dependencies (internal and external)

4. Design Data Flow

• Map request/response flows
• Identify data transformations
• Document async/sync boundaries

5. Analyze Constraints

• Technical limitations
• Platform requirements
• Integration dependencies
• Performance bounds

6. Assess Risks

Risk	Likelihood	Impact	Mitigation
[Risk description]	Low/Medium/High	Low/Medium/High	[Strategy]

7. Document Trade-offs

For significant design choices:

• What alternatives were considered?
• Why was this option chosen?
• What are the consequences?

8. Create ADRs

For each significant decision, create an ADR:

# ADR-NNN: [Decision Title]

**Status**: Proposed | Accepted | Deprecated
**Date**: [date]

## Context
[What is the issue/situation requiring a decision?]

## Decision
[What is the change/decision being made?]

## Rationale
[Why was this decision made?]

## Alternatives Considered
1. [Alternative 1]: [Why rejected]
2. [Alternative 2]: [Why rejected]

## Consequences
- [Positive consequence 1]
- [Positive consequence 2]
- [Negative consequence / trade-off]

## Related
- [Link to related ADRs]
- [Link to relevant requirements]

Architecture Template

# [Project Name] Architecture

**Version**: 0.1.0
**Date**: [date]
**Source**: [PRD.md](PRD.md)

---

## Overview
[High-level system diagram or description]

## Components

### [Component Name]
- **Responsibility**: [Single responsibility description]
- **Interface**: [API/contract definition]
- **Dependencies**: [What it requires]
- **Artifacts**: [What it produces]

## Data Flow
[Sequence or flow diagrams]

## Constraints
- [Technical constraint 1]
- [Platform constraint 2]

## Risks
[Risk table]

## Trade-offs
[Design decision rationale]

## Design Decisions
- [ADR-001](adr/001-decision.md): [Summary]
- [ADR-002](adr/002-decision.md): [Summary]

Validation Checklist

• All FRs have corresponding components
• All components have clear responsibilities
• Interfaces are defined between components
• NFRs are addressed in design
• Risks are identified with mitigations
• Significant decisions have ADRs