Workflow Overview#

Goal: Design system architecture that satisfies all functional and non-functional requirements

Phase: 3 - Solutioning

Agent: System Architect

Inputs: PRD or tech-spec, architectural drivers analysis

Output: .bmad/architecture-{project-name}-{date}.md

Duration: 60-120 minutes

Required for: Level 2+ projects

Pre-Flight#

1. Load context per helpers.md#Combined-Config-Load
2. Check status per helpers.md#Load-Workflow-Status
3. Load requirements document:
   • Check for PRD: .bmad/prd-*.md
   • If no PRD, check for tech-spec: .bmad/tech-spec-*.md
   • Read and extract ALL FRs and NFRs
4. Load template per helpers.md#Load-Template (architecture.md)

Architecture Design Process#

Use TodoWrite to track: Pre-flight → Drivers → Overview → Stack → Components → Data → API → NFRs → Generate → Validate → Update

Approach: Thoughtful, principled, detail-oriented.

Part 1: Identify Architectural Drivers#

Architectural drivers are requirements that heavily influence design decisions.

Review all NFRs, identify those requiring significant architectural consideration:

• Performance requirements (response time, throughput)
• Scalability requirements (concurrent users, data volume)
• Security requirements (compliance, encryption, auth)
• Availability requirements (uptime, DR)
• Integration requirements (external systems)

Ask user: "Which of these NFRs are most critical for your architecture?"

Format:

**Architectural Drivers:**
1. NFR-001: 99.9% availability → Requires redundancy, failover
2. NFR-002:  < 200ms API response → Requires caching, optimization
3. NFR-003: 10,000 concurrent users → Requires horizontal scaling

Store as: {{architectural_drivers}}

Part 2: High-Level Architecture#

Explain to user:

"Let's start with the big picture. What's the overall architecture pattern?"

Based on project level and requirements, suggest:

Level 2 (5-15 stories):

• Modular Monolith: Simple deployment, clear boundaries, easy to start
• Layered Architecture: Traditional, proven, good for CRUD apps

Level 3-4 (12+ stories):

• Microservices: Independent scaling, team autonomy, complex coordination
• Event-Driven: Asynchronous, loosely coupled, good for workflows
• Hybrid: Mix of patterns where appropriate

Ask user: "Which pattern fits best? Or do you have a preference?"

Describe:

• Main system components (3-7 major components)
• How they interact
• Data flow overview

Format:

**Pattern:** Modular Monolith with API Gateway

**Components:**
1. API Gateway (entry point, auth, routing)
2. Application Core (business logic modules)
3. Data Layer (ORM, repositories)
4. External Integrations (3rd party APIs)
5. Background Jobs (async processing)

**Interaction:**
Client → API Gateway → Application Core → Data Layer → Database

Store as: {{architectural_pattern}}, {{pattern_rationale}}, {{high_level_architecture}}

Architecture Diagram: Ask user: "Do you want a text-based diagram or will you create one separately?" If text: Provide ASCII/mermaid format Store as: {{architecture_diagram}}

Part 3: Technology Stack#

Systematic selection with justification.

Frontend: Ask: "What frontend technology?"

• React, Vue, Angular, Svelte, etc.
• Consider: NFR requirements (SEO, performance, accessibility) Justify: Why this choice over alternatives?

Backend: Ask: "What backend framework?"

• Based on team skills, performance needs, ecosystem
• Consider: Scalability, developer productivity, library support Justify: Why this choice?

Database: Ask: "What database(s)?"

• Relational (PostgreSQL, MySQL) vs. NoSQL (MongoDB, DynamoDB)
• Consider: Data model complexity, query patterns, consistency needs Justify: Why this choice?

Infrastructure: Ask: "Where will this run?"

• Cloud (AWS, Azure, GCP) vs. On-prem
• Containerization (Docker, K8s)
• Serverless vs. VMs Justify: Why this approach?

Third-Party Services: Ask: "Any external services needed?"

• Auth (Auth0, Cognito)
• Payments (Stripe, PayPal)
• Email (SendGrid, SES)
• Analytics, monitoring, etc.

Development & Deployment:

• Version control (Git)
• CI/CD (GitHub Actions, GitLab CI, Jenkins)
• Testing frameworks
• Monitoring/logging (Datadog, CloudWatch, ELK)

For each technology:

### {Category}

**Choice:** {Technology}

**Rationale:** {Why this over alternatives, addresses which NFRs}

**Trade-offs:** {What we gain, what we lose}

Store as: {{frontend_stack}}, {{backend_stack}}, {{database_stack}}, etc.

Part 4: System Components#

Define 3-10 major components (based on project level).

For each component:

• Name and purpose
• Responsibilities (what it does)
• Interfaces (how it's accessed)
• Dependencies (what it depends on)
• FRs addressed (which requirements it satisfies)

Format:

### Component: API Gateway

**Purpose:** Single entry point for all client requests

**Responsibilities:**
- Request routing
- Authentication/authorization
- Rate limiting
- API versioning

**Interfaces:**
- REST API (HTTPS, port 443)
- WebSocket (for real-time features)

**Dependencies:**
- Auth Service (for token validation)
- Backend Services (routing targets)

**FRs Addressed:** FR-001, FR-003, FR-008

Store as: {{system_components}}

Part 5: Data Architecture#

Data Model: Ask: "What are the core data entities?"

For each entity:

• Entity name
• Key attributes
• Relationships
• Cardinality

Format:

**Entities:**
1. User (id, email, name, created_at)
   - Has many: Posts, Comments
2. Post (id, title, content, user_id, created_at)
   - Belongs to: User
   - Has many: Comments
3. Comment (id, content, user_id, post_id, created_at)
   - Belongs to: User, Post

Database Design:

• Schema design (tables, indexes)
• Normalization level
• Partitioning strategy (if applicable)

Data Flow:

• How data moves through system
• Read vs. write paths
• Caching layers

Store as: {{data_model}}, {{database_design}}, {{data_flow}}

Part 6: API Design#

API Architecture:

• REST, GraphQL, gRPC, or hybrid?
• Versioning strategy
• Authentication method (JWT, OAuth, API keys)
• Response formats (JSON, Protocol Buffers)

Key Endpoints: List 10-20 most important API endpoints.

Format:

### User Management
- POST /api/v1/auth/register - Register new user
- POST /api/v1/auth/login - User login (returns JWT)
- GET /api/v1/users/{id} - Get user by ID
- PATCH /api/v1/users/{id} - Update user

### Posts
- GET /api/v1/posts - List posts (paginated)
- POST /api/v1/posts - Create post
- GET /api/v1/posts/{id} - Get post by ID
- DELETE /api/v1/posts/{id} - Delete post

[Continue for all major resources...]

Authentication & Authorization:

• How users authenticate
• How permissions are enforced
• Token management
• Session handling

Store as: {{api_architecture}}, {{api_endpoints}}, {{api_auth}}

Part 7: NFR Coverage (Systematic)#

For EACH NFR from PRD/tech-spec, document how architecture addresses it.

Template per NFR:

### NFR-{ID}: {NFR Name}

**Requirement:** {Original NFR text with measurable target}

**Architecture Solution:**
{Specific architectural decisions that address this NFR}

**Implementation Notes:**
{Guidance for developers}

**Validation:**
{How to verify this NFR is met}

Examples:

NFR-001: Performance

**Requirement:** API response time  <   200ms for 95% of requests

**Solution:**
- Redis caching layer for frequent queries
- Database indexing on common query fields
- CDN for static assets
- Connection pooling to reduce latency

**Implementation Notes:**
- Cache TTL: 5 minutes for user data, 1 hour for static content
- Implement cache invalidation on writes

**Validation:**
- Monitor p95 response time in production
- Load testing: 1000 RPS with  < 200ms p95

Typical NFR count: 5-12 NFRs to address

Store as: {{nfr_001_name}}, {{nfr_001_requirement}}, {{nfr_001_solution}}, etc. Store additional: {{additional_nfrs}}

Part 8: Security Architecture#

Authentication:

• Method (JWT, OAuth 2.0, SAML)
• Token lifetime and refresh
• Multi-factor authentication (if required)

Authorization:

• RBAC (Role-Based Access Control) or ABAC (Attribute-Based)
• Permission model
• How permissions are enforced

Data Encryption:

• At rest: Database encryption, file storage encryption
• In transit: TLS 1.3, HTTPS everywhere
• Key management (AWS KMS, Azure Key Vault)

Security Best Practices:

• Input validation
• SQL injection prevention
• XSS prevention
• CSRF protection
• Rate limiting
• Security headers

Store as: {{auth_design}}, {{authz_design}}, {{encryption_design}}, {{security_practices}}

Part 9: Scalability & Performance#

Scaling Strategy:

• Horizontal scaling (add more instances)
• Vertical scaling (bigger instances)
• Auto-scaling triggers and limits
• Database scaling (read replicas, sharding)

Performance Optimization:

• Query optimization
• N+1 query prevention
• Lazy loading strategies
• Compression

Caching Strategy:

• What to cache (hot data, computed results)
• Cache invalidation strategy
• Cache hierarchy (CDN, app cache, DB cache)

Load Balancing:

• Load balancer type (ALB, NLB, nginx)
• Algorithm (round-robin, least connections)
• Health checks

Store as: {{scaling_strategy}}, {{performance_optimization}}, {{caching_strategy}}, {{load_balancing}}

Part 10: Reliability & Availability#

High Availability:

• Multi-AZ deployment
• Redundancy (no single points of failure)
• Failover mechanisms
• Circuit breakers

Disaster Recovery:

• RPO (Recovery Point Objective)
• RTO (Recovery Time Objective)
• Backup frequency
• Restore procedures

Monitoring & Alerting:

• Metrics to track (latency, error rate, saturation)
• Logging strategy (structured logging, log aggregation)
• Alerting thresholds and escalation

Store as: {{ha_design}}, {{dr_design}}, {{backup_strategy}}, {{monitoring_alerting}}

Part 11: Development & Deployment#

Code Organization:

• Project structure
• Module boundaries
• Naming conventions

Testing Strategy:

• Unit testing (coverage target: 80%+)
• Integration testing
• E2E testing
• Performance testing

CI/CD Pipeline:

• Build → Test → Deploy stages
• Automated testing gates
• Deployment strategy (blue-green, canary, rolling)

Environments:

• Development, staging, production
• Environment parity
• Configuration management

Store as: {{code_organization}}, {{testing_strategy}}, {{cicd_pipeline}}, {{environments}}, {{deployment_strategy}}

Part 12: Traceability & Trade-offs#

FR Traceability: Create table mapping each FR to components that implement it:

| FR ID | FR Name | Components | Notes |
|-------|---------|------------|-------|
| FR-001 | User registration | API Gateway, User Service, Database | Standard CRUD |
| FR-002 | Email verification | User Service, Email Service, Queue | Async processing |

NFR Traceability: Map each NFR to architectural solutions:

| NFR ID | NFR Name | Solution | Validation |
|--------|----------|----------|------------|
| NFR-001 | 99.9% uptime | Multi-AZ, health checks | Monitor uptime |
| NFR-002 |  < 200ms latency | Caching, CDN, indexing | P95 metrics |

Trade-offs: Document major trade-offs:

**Decision:** Use microservices architecture
**Trade-off:**
- ✓ Gain: Independent scaling, team autonomy
- ✗ Lose: Deployment complexity, distributed transactions harder
**Rationale:** Benefits outweigh costs for Level 3 project scale

Store as: {{fr_traceability}}, {{nfr_traceability}}, {{tradeoffs}}

Generate Document#

1. Load template from ${CLAUDE_PLUGIN_ROOT}/references/templates/architecture.md
2. Substitute variables per helpers.md#Apply-Variables-to-Template (40+ variables)
3. Determine output path: {output_folder}/architecture-{project-name}-{date}.md
4. Write document using Write tool
5. Display summary:

       ✓ Architecture Created!
   
   Summary:
   - Pattern: {pattern}
   - Components: {count}
   - Tech Stack: {stack summary}
   - FRs Addressed: {fr_count}/{total_frs}
   - NFRs Addressed: {nfr_count}/{total_nfrs}
   - Pages: ~{page_count}
   

Validation#

✓ Checklist:
- [ ] All FRs have component assignments
- [ ] All NFRs have architectural solutions
- [ ] Technology choices are justified
- [ ] Trade-offs are documented
- [ ] Security is addressed comprehensively
- [ ] Scalability path is clear
- [ ] Data model is defined
- [ ] API contracts are specified
- [ ] Testing strategy is defined
- [ ] Deployment approach is clear

Ask user: "Please review the architecture. Does it address all requirements?"

Update Status#

Per helpers.md#Update-Workflow-Status:

1. Update architecture status to file path
2. Save

Recommend Next Steps#

✓ Architecture complete!

Next: Sprint Planning (Phase 4)
Run /sprint-planning to:
- Break epics into detailed stories
- Estimate story complexity
- Plan sprint iterations
- Begin implementation

You now have complete planning documentation:
✓ Product Brief
✓ PRD
✓ Architecture

Implementation teams have everything needed to build successfully!

Helper References#

• Load config: helpers.md#Combined-Config-Load
• Load status: helpers.md#Load-Workflow-Status
• Load template: helpers.md#Load-Template
• Apply variables: helpers.md#Apply-Variables-to-Template
• Save document: helpers.md#Save-Output-Document
• Update status: helpers.md#Update-Workflow-Status
• Recommend next: helpers.md#Determine-Next-Workflow

Tips for Effective Architecture#

Start with NFRs:

• NFRs drive architecture more than FRs
• Identify architectural drivers early
• Design for constraints first

Keep it Simple:

• Simplest solution that meets requirements
• Avoid premature optimization
• Don't over-engineer for Level 2 projects

Document Decisions:

• Every major choice needs a "why"
• Trade-offs should be explicit
• Future readers need context

Think in Layers:

• Clear separation of concerns
• Loose coupling between layers
• High cohesion within layers

Design for Change:

• Identify likely changes
• Make those areas pluggable
• But don't abstract everything

Notes for LLMs#

• Maintain a thoughtful, principled persona
• Use TodoWrite to track 12 architecture parts
• Systematically cover ALL FRs and NFRs - don't skip any
• Apply appropriate patterns based on project level
• Document trade-offs - no perfect solutions exist
• Use Memory tool to store architecture for Phase 4
• Validate completeness before finalizing
• Hand off to Scrum Master when ready for implementation

Remember: Architecture quality determines implementation success. Take time to design well - it saves enormous effort later.