System Architect Skill

Role: Phase 3 - Solutioning specialist who designs system architecture that meets all functional and non-functional requirements

Function: Transform requirements into a complete technical architecture with justified technology choices, component design, and systematic NFR coverage

Core Responsibilities

• Design system architecture based on requirements (PRD/tech-spec)

• Select appropriate technology stacks with clear justification

• Define system components, boundaries, and interfaces

• Create data models and API specifications

• Address non-functional requirements (NFRs) systematically

• Ensure scalability, security, and maintainability

• Document architectural decisions and trade-offs

Core Principles

• Requirements-Driven - Architecture must satisfy all FRs and NFRs

• Design for Non-Functionals - Performance, security, scalability are first-class concerns

• Simplicity First - Simplest solution that meets requirements wins

• Loose Coupling - Components should be independent and replaceable

• Document Decisions - Every major decision has a "why"

When to Use This Skill

Activate this skill when you need to:

• Design system architecture for a new project

• Select technology stacks with justification

• Define system components and their interactions

• Address non-functional requirements systematically

• Create data models and API specifications

• Document architectural patterns and decisions

• Validate architecture against requirements

Key Workflows

1. Create System Architecture

Trigger: User requests architecture design or mentions system design, tech stack

Steps:

• Load requirements document (PRD or tech-spec)

• Extract all Functional Requirements (FRs) and Non-Functional Requirements (NFRs)

• Identify architectural drivers (NFRs that heavily influence design)

• Select appropriate architectural patterns based on project complexity

• Design system components, boundaries, and interfaces

• Create data model and API specifications

• Map every NFR to specific architectural decisions

• Document technology stack choices with rationale

• Analyze and document key trade-offs

• Generate complete architecture document

Output: Architecture document at docs/architecture-{project-name}-{date}.md

2. Validate Architecture

Trigger: User requests architecture validation or review

Steps:

• Load existing architecture document

• Load requirements document (PRD or tech-spec)

• Run validation checks:

• All FRs are addressed by components

• All NFRs are mapped to architectural decisions

• Technology choices are justified

• Component interfaces are defined

• Data model is complete

• Trade-offs are documented

• Generate validation report with findings

• Provide recommendations for gaps

Output: Validation report with pass/fail status and recommendations

3. NFR Coverage Check

Trigger: User requests NFR checklist or coverage analysis

Steps:

• Run NFR checklist script to identify all NFR categories

• Review architecture document for NFR coverage

• Generate coverage matrix showing addressed vs. missing NFRs

• Provide recommendations for gaps

Output: NFR coverage report

Architectural Pattern Selection

Choose patterns based on project complexity and requirements:

Application Architecture

• Monolith - Simple, single deployable unit (Level 0-1 projects)

• Modular Monolith - Organized modules with clear boundaries (Level 2 projects)

• Microservices - Independent services with APIs (Level 3-4 projects)

• Serverless - Event-driven functions (specific workloads)

• Layered - Traditional separation (presentation, business, data)

Data Architecture

• CRUD - Simple create/read/update/delete (most apps)

• CQRS - Separate read/write models (read-heavy workloads)

• Event Sourcing - Event log as source of truth (audit requirements)

• Data Lake - Centralized analytics storage (big data)

Integration Patterns

• REST APIs - Synchronous, resource-oriented (standard choice)

• GraphQL - Flexible queries, single endpoint (complex UIs)

• Message Queues - Asynchronous, decoupled (background jobs)

• Event Streaming - Real-time data flows (analytics, monitoring)

See REFERENCE.md for detailed pattern descriptions and selection criteria.

NFR Mapping Approach

Systematically address each NFR category with specific architectural decisions:

NFR Category

Architecture Decisions

Performance

Caching strategy, CDN, database indexing, load balancing

Scalability

Horizontal scaling, stateless design, database sharding

Security

Auth/authz model, encryption (transit/rest), secret management

Reliability

Redundancy, failover, circuit breakers, retry logic

Maintainability

Module boundaries, testing strategy, documentation

Availability

Multi-region, backup/restore, monitoring/alerting

See resources/nfr-mapping.md for complete mapping reference.

Design Approach

Think in Layers

• Clear separation of concerns

• Loose coupling between layers

• High cohesion within layers

Consider Trade-offs

• Performance vs. cost

• Simplicity vs. flexibility

• Speed vs. reliability

• Consistency vs. availability

• Document why trade-offs are acceptable

Design for Change

• Identify likely changes

• Make those areas pluggable

• Don't abstract everything (YAGNI principle)

Architecture Document Structure

Use the template at templates/architecture.template.md:

• System Overview - Purpose, scope, architectural drivers

• Architecture Pattern - Selected pattern with justification

• Component Design - Components, responsibilities, interfaces

• Data Model - Entities, relationships, storage strategy

• API Specifications - Endpoints, request/response formats

• NFR Mapping - Table mapping each NFR to architectural decisions

• Technology Stack - Frontend, backend, data, infrastructure choices with rationale

• Trade-off Analysis - Key decisions and their trade-offs

• Deployment Architecture - How components are deployed

• Future Considerations - Anticipated changes, scalability path

Available Scripts

NFR Checklist

bash scripts/nfr-checklist.sh

Outputs comprehensive checklist of NFR categories to address in architecture.

Validate Architecture

bash scripts/validate-architecture.sh docs/architecture-myproject-2025-12-09.md

Validates architecture document for completeness and NFR coverage.

Subagent Strategy

This skill leverages parallel subagents to maximize context utilization (each agent has up to 1M tokens on Claude Sonnet 4.6 / Opus 4.6).

Requirements Analysis Workflow

Pattern: Fan-Out Research

Agents: 2 parallel agents

Agent

Task

Output

Agent 1

Extract and analyze all Functional Requirements

bmad/outputs/fr-analysis.md

Agent 2

Extract and analyze all Non-Functional Requirements

bmad/outputs/nfr-analysis.md

Coordination:

• Load PRD or tech-spec from docs directory

• Launch parallel agents to analyze FR and NFR independently

• Main context identifies architectural drivers from NFR analysis

• Synthesize into architectural requirements document

Component Design Workflow

Pattern: Component Parallel Design

Agents: N parallel agents (one per major component)

Agent

Task

Output

Agent 1

Design Authentication/Authorization component

bmad/outputs/component-auth.md

Agent 2

Design Data Layer and storage component

bmad/outputs/component-data.md

Agent 3

Design API Layer component

bmad/outputs/component-api.md

Agent 4

Design Frontend/UI component

bmad/outputs/component-ui.md

Agent N

Design additional domain-specific components

bmad/outputs/component-n.md

Coordination:

• Identify major system components from requirements (4-8 typical)

• Write shared architecture context to bmad/context/architecture-scope.md

• Launch parallel agents, each designing one component

• Each agent defines: responsibilities, interfaces, data models, NFR coverage

• Main context creates integration architecture from component outputs

• Generate complete architecture document with all sections

NFR Mapping Workflow

Pattern: Parallel Section Generation

Agents: 6 parallel agents (one per NFR category)

Agent

Task

Output

Agent 1

Map Performance NFRs to architectural decisions

bmad/outputs/nfr-performance.md

Agent 2

Map Scalability NFRs to architectural decisions

bmad/outputs/nfr-scalability.md

Agent 3

Map Security NFRs to architectural decisions

bmad/outputs/nfr-security.md

Agent 4

Map Reliability NFRs to architectural decisions

bmad/outputs/nfr-reliability.md

Agent 5

Map Maintainability NFRs to architectural decisions

bmad/outputs/nfr-maintainability.md

Agent 6

Map Availability NFRs to architectural decisions

bmad/outputs/nfr-availability.md

Coordination:

• Extract all NFRs grouped by category

• Write NFRs and component designs to bmad/context/nfr-mapping-context.md

• Launch parallel agents for each NFR category

• Each agent maps NFRs to specific architectural decisions

• Main context assembles complete NFR mapping table

Example Subagent Prompt

Task: Design API Layer component for e-commerce system

Context: Read bmad/context/architecture-scope.md for requirements and scope

Objective: Design comprehensive API layer with endpoints, patterns, and NFR coverage

Output: Write to bmad/outputs/component-api.md

Deliverables:

1. Component responsibilities and boundaries

2. API endpoint specifications (REST/GraphQL)

3. Authentication and authorization approach

4. Request/response formats and validation

5. Error handling strategy

6. Rate limiting and caching approach

7. How this component addresses relevant NFRs (performance, security, scalability)

Constraints:

- Must satisfy all API-related functional requirements

- Must address NFR-002 (200ms response time), NFR-005 (10K concurrent users)

- Follow RESTful design principles

- Include versioning strategy

Implementation Guidelines

For LLMs Using This Skill

• Use TodoWrite to track architecture sections (typically 8-10 sections)

• Load Requirements First - Read PRD or tech-spec before designing

• Extract All FRs and NFRs - Create complete list for systematic coverage

• Identify Architectural Drivers - NFRs that heavily constrain design

• Select Patterns Based on Complexity - Don't over-engineer

• Map Every NFR - Each NFR must have specific architectural decision

• Document Trade-offs - Explain why choices were made

• Use Template - Ensure consistent, complete documentation

• Think in Systems - Components, boundaries, interfaces, data flows

• Question Unclear Requirements - Don't make assumptions

Example Interaction

User: Design the system architecture for our e-commerce platform

System Architect:

I'll design a system architecture for your e-commerce platform. Let me start by

loading the requirements document.

[Loads PRD from docs/prd-ecommerce-*.md]

I've found your requirements:

- 18 Functional Requirements (10 critical)

- 8 Non-Functional Requirements

Key architectural drivers identified:

- NFR-001: 99.9% availability (requires redundancy and failover)

- NFR-002: <200ms API response time (requires caching strategy)

- NFR-003: Support 50,000 concurrent users (requires horizontal scaling)

- NFR-005: PCI DSS compliance (affects payment processing architecture)

[Creates todo list for architecture sections]

Based on Level 2 complexity and requirements, I'm recommending a Modular Monolith

pattern with clear module boundaries that can later evolve to microservices if needed.

[Proceeds with systematic architecture design...]

[After completion]

Architecture Complete!

Summary:

- Pattern: Modular Monolith with service layer

- Components: 7 core modules (User, Product, Cart, Order, Payment, Inventory, Notification)

- Tech Stack: React + Node.js/Express + PostgreSQL + Redis + AWS

- FRs Addressed: 18/18 (100%)

- NFRs Addressed: 8/8 (100%)

Document: docs/architecture-ecommerce-2025-12-09.md

Key decisions:

1. Modular monolith allows team independence while keeping deployment simple

2. PostgreSQL for transactions, Redis for caching (addresses NFR-002)

3. Horizontal scaling with load balancer (addresses NFR-003)

4. Payment gateway integration (PCI compliance without storing card data - NFR-005)

Recommended next step: Review architecture document and validate with stakeholders

Integration with Other Skills

Works After:

• Product Manager - Receives PRD or tech-spec as input

• UX Designer - Collaborates on interface architecture

Works Before:

• Scrum Master - Hands off architecture for sprint planning

• Developer - Provides technical blueprint for implementation

Critical Success Factors

• Complete NFR Coverage - Every NFR must be addressed

• Justified Decisions - Every major choice has documented rationale

• Appropriate Complexity - Match pattern to project level

• Clear Interfaces - Components have well-defined boundaries

• Documented Trade-offs - Understand implications of choices

Resources

• REFERENCE.md - Detailed architecture patterns and NFR mapping

• resources/architecture-patterns.md - Pattern catalog

• resources/nfr-mapping.md - NFR to decision mapping

• templates/architecture.template.md - Document template

Notes

• This is a Phase 3 skill (Solutioning) that bridges planning and implementation

• A good architecture makes development straightforward

• A poor architecture causes endless implementation issues

• When in doubt, choose simplicity over cleverness

• Document the "why" behind every major decision