Create Architecture

Purpose

Generate comprehensive, production-ready system architecture documents from requirements. Supports Frontend, Backend, and Fullstack projects with scale-adaptive depth, proven architectural patterns, and Architecture Decision Records (ADRs).

Core Principles:

• Multi-domain support: Frontend, Backend, Fullstack architectures

• Scale-adaptive: Adjusts detail based on project complexity

• Pattern-driven: Leverages proven architectural patterns catalog

• Decision-focused: Documents key decisions as ADRs

• Technology-agnostic: Considers multiple options, recommends best fit

Prerequisites

• Requirements document exists (PRD, epic, or user stories)

• Non-functional requirements (NFRs) defined or inferable

• Target user scale and data volume known or estimable

• Project constraints documented (team, timeline, budget)

Workflow

1. Load and Analyze Requirements

Action: Read requirements document using bmad-commands

Execute:

python .claude/skills/bmad-commands/scripts/read_file.py
--path {requirements_file}
--output json

Extract from requirements:

• Functional requirements (features, capabilities)

• Non-functional requirements (performance, security, scalability)

• Business goals and constraints

• Technical constraints (technologies, platforms)

• User scale estimates

• Data volume estimates

• Integration requirements

If brownfield: Also load existing architecture for context.

See: references/requirements-analysis-guide.md for extraction techniques

2. Detect Project Type

Analyze requirements to determine domain:

Frontend-only indicators:

• UI/UX requirements are dominant

• No backend/API requirements mentioned

• Focus on components, state, routing, styling

• Technologies: React, Vue, Angular, Svelte

Backend-only indicators:

• API/service requirements dominant

• No UI requirements mentioned

• Focus on business logic, data processing, integrations

• Technologies: Node.js, Python, Java, Go, Rust

Fullstack indicators:

• Both frontend and backend requirements

• End-to-end user journeys described

• Integration between UI and services

• Technologies span both domains

Default: If unclear, select Fullstack (most comprehensive)

See: references/project-type-patterns.md for detailed detection criteria

3. Assess Complexity

Calculate complexity score based on weighted factors:

Factor Weight Scoring

User scale 25% <1K=10, 1K-10K=30, 10K-100K=60, >100K=90

Data volume 20% <10GB=10, 10GB-1TB=40, >1TB=80

Integration points 20% 0-2=10, 3-5=40, 6-10=70, >10=90

Performance reqs 15% None=0, Standard=30, Strict=70

Security reqs 10% Basic=10, Standard=40, Advanced=80

Deployment 10% Single=10, Multi-region=50, Global=80

Complexity Formula:

Score = (scale × 0.25) + (data × 0.20) + (integrations × 0.20) + (perf × 0.15) + (security × 0.10) + (deploy × 0.10)

Categories:

• 0-30: Simple (single-tier, standard patterns)

• 31-60: Medium (multi-tier, moderate patterns)

• 61-100: Complex (distributed, advanced patterns)

This determines: Architecture depth, pattern selection, ADR count

See: references/complexity-assessment.md for detailed scoring guide

4. Select Architectural Patterns

Based on project type and complexity, select patterns:

Frontend Patterns:

• Component architecture (atomic design, compound components)

• State management (Redux, Zustand, Context, Recoil)

• Routing strategies (file-based, declarative, nested)

• Styling approach (CSS-in-JS, Tailwind, CSS Modules)

• Data fetching (React Query, SWR, Apollo)

Backend Patterns:

• API design (REST, GraphQL, tRPC, gRPC)

• Service architecture (monolith, microservices, modular monolith)

• Data modeling (relational, document, event-sourced)

• Integration patterns (message queues, event buses, webhooks)

• Caching strategies (Redis, Memcached, CDN)

Fullstack Patterns:

• Framework selection (Next.js, Remix, SvelteKit, Nuxt)

• Monorepo structure (Turborepo, Nx, Lerna)

• API layers (BFF, API Gateway, tRPC)

• Deployment (Vercel, Netlify, AWS, Docker/K8s)

• Authentication (NextAuth, Passport, Auth0, Clerk)

See: references/patterns-catalog.md for complete pattern library

5. Evaluate Technology Stack

For each architectural component, evaluate options:

Evaluation Criteria:

• Requirements fit (does it meet functional/NFRs?)

• Team expertise (can team use this effectively?)

• Community support (strong ecosystem?)

• Performance (meets requirements?)

• Scalability (scales with growth?)

• Cost (licensing/infrastructure costs?)

• Maintenance (long-term burden?)

• Migration path (can we change later?)

Decision Process:

• Identify requirements for component

• Generate 3-5 alternatives

• Evaluate against criteria

• Select best fit

• Document in ADR

See: references/technology-decision-framework.md for evaluation matrices

6. Generate Architecture Document

Create comprehensive architecture at docs/architecture.md:

Structure (adapt based on project type):

[Project Name] Architecture

1. System Overview

[High-level description, context, goals]

2. Architecture Diagrams

[C4 context, container, component diagrams]

3. Frontend Architecture (if applicable)

[Component design, state management, routing, styling, build]

4. Backend Architecture (if applicable)

[API design, services, data layer, business logic, integrations]

5. Fullstack Integration (if applicable)

[End-to-end flows, API contracts, auth, deployment]

6. Data Architecture

[Data models, relationships, migrations, caching]

7. Technology Stack

[All technologies with justifications]

8. Deployment Architecture

[Infrastructure, environments, CI/CD, monitoring]

9. Security Architecture

[Authentication, authorization, data protection, compliance]

10. Performance Architecture

[Caching, optimization, CDN, load balancing]

11. Scalability Plan

[Horizontal/vertical scaling, bottlenecks, growth plan]

12. Architecture Decision Records (ADRs)

[Key decisions with context, options considered, rationale]

13. Migration Strategy (brownfield only)

[Current state, target state, migration path, risks]

14. Open Questions & Risks

[Unknowns, risks, mitigation strategies]

Scale adaptation:

• Simple: Focus on sections 1, 3-7, 12 (10-15 pages)

• Medium: Include sections 1-12 (15-25 pages)

• Complex: All sections with deep analysis (25-40 pages)

See: references/templates.md for section templates

7. Create Architecture Decision Records (ADRs)

For each significant decision, create ADR:

ADR Template:

ADR-XXX: [Decision Title]

Date: YYYY-MM-DD Status: Proposed | Accepted | Deprecated | Superseded

Context

[Problem and constraints]

Decision

[What we decided]

Alternatives Considered

1. Option A: [pros/cons]
2. Option B: [pros/cons]
3. Option C: [pros/cons]

Rationale

[Why this option]

Consequences

[Positive and negative impacts]

Related Decisions

[Links to other ADRs]

Minimum ADRs:

• Simple architecture: 3-5 ADRs

• Medium architecture: 5-10 ADRs

• Complex architecture: 10-15 ADRs

Common ADR topics:

• Primary technology stack selection

• Database choice

• API design approach

• State management strategy

• Authentication mechanism

• Deployment platform

• Monitoring and observability approach

See: references/adr-examples.md for ADR examples

8. Address Non-Functional Requirements

Ensure architecture addresses all NFRs:

Performance:

• Response time targets (p50, p95, p99)

• Throughput requirements (req/sec)

• Optimization strategies (caching, CDN, lazy loading)

Scalability:

• User growth projections

• Data growth projections

• Horizontal scaling strategy

• Bottleneck identification

Security:

• Authentication and authorization

• Data encryption (at rest, in transit)

• Input validation and sanitization

• Compliance requirements (GDPR, HIPAA, etc.)

Reliability:

• Availability targets (99%, 99.9%, 99.99%)

• Fault tolerance strategies

• Disaster recovery plan

• Backup and restore procedures

Maintainability:

• Code organization principles

• Testing strategy

• Documentation standards

• Technical debt management

See: references/nfr-architecture-mapping.md for NFR checklist

9. Generate Supplementary Artifacts (Optional)

If requested or beneficial:

Architecture Diagrams:

python .claude/skills/bmad-commands/scripts/generate_architecture_diagram.py
--architecture docs/architecture.md
--type c4-context
--output docs/diagrams/

Technology Analysis Report:

python .claude/skills/bmad-commands/scripts/analyze_tech_stack.py
--architecture docs/architecture.md
--output json

Extract ADRs to separate files:

python .claude/skills/bmad-commands/scripts/extract_adrs.py
--architecture docs/architecture.md
--output docs/adrs/

10. Validate Completeness

Self-validate before marking complete:

Check all required sections present:

• ✅ System Overview

• ✅ Architecture appropriate for project type

• ✅ Technology Stack documented

• ✅ NFRs addressed

• ✅ At least 3 ADRs created

• ✅ Security considerations included

• ✅ Scalability plan defined

Quality check:

• ✅ All technology choices justified

• ✅ Alternatives considered

• ✅ Risks identified

• ✅ No critical gaps

If validation fails: Address gaps before completion.

Common Scenarios

Scenario 1: Greenfield Frontend Application

Input: React dashboard requirements Output: Frontend-only architecture with component design, state (Zustand), routing (React Router), styling (Tailwind), build (Vite)

Scenario 2: Backend API Service

Input: REST API requirements for mobile app Output: Backend-only architecture with Express.js, PostgreSQL, Prisma, Redis caching, JWT auth

Scenario 3: Fullstack E-commerce Platform

Input: Comprehensive e-commerce requirements Output: Fullstack architecture with Next.js, tRPC, PostgreSQL, Stripe integration, Vercel deployment

Scenario 4: Brownfield System Modernization

Input: Legacy monolith + modernization requirements Output: Migration architecture with incremental microservices extraction, API gateway, strangler fig pattern

See: references/example-architectures.md for complete examples

Success Criteria

An architecture is complete and ready for implementation when:

Documentation Completeness

• ✅ Architecture document created at docs/architecture.md

• ✅ All required sections present for project type:

• System Overview & Context

• Technology Stack (complete and justified)

• Deployment Architecture

• Security Architecture

• Architecture Decision Records (ADRs)

• Project-specific sections (Frontend/Backend/Fullstack)

• ✅ Architecture diagrams included (minimum 1, recommended 2-3)

• ✅ Technology stack fully documented with versions

Decision Quality

• ✅ Minimum ADR count met:

• Simple (0-30): ≥3 ADRs

• Medium (31-60): ≥5 ADRs

• Complex (61-100): ≥10 ADRs

• ✅ Each ADR includes:

• Context and problem statement

• Decision made

• Alternatives considered (minimum 2)

• Rationale with data/benchmarks

• Consequences (positive and negative)

• ✅ Technology choices justified with alternatives

NFR Coverage

• ✅ All Non-Functional Requirements addressed:

• Performance: Targets specified (e.g., p95 <500ms)

• Scalability: Growth projections and scaling plan

• Security: Auth, authorization, encryption, compliance

• Reliability: Availability target, redundancy, failover

• Maintainability: Testing strategy, code organization

• ✅ NFRs mapped to concrete architecture decisions

Quality Gates

• ✅ No critical gaps or missing sections

• ✅ No contradictory decisions

• ✅ Security considerations documented

• ✅ Scalability approach defined

• ✅ Deployment strategy clear

• ✅ Cost implications considered

Validation Ready

• ✅ Architecture can be validated with validate-architecture skill

• ✅ Expected validation score ≥70

• ✅ Ready for team review

• ✅ Implementation-ready (developers can start coding)

Checklist:

[ ] Architecture document created [ ] All required sections present [ ] Minimum ADR count met [ ] Technologies justified [ ] NFRs addressed [ ] Diagrams included [ ] Security documented [ ] Deployment defined [ ] No critical gaps [ ] Validation score ≥70

Best Practices

• Start with requirements - Architecture follows requirements, not the reverse

• Consider alternatives - Evaluate 3-5 options for major decisions

• Document decisions - Every significant choice becomes an ADR

• Think long-term - Consider maintenance, scaling, team growth

• Be pragmatic - Choose appropriate tools, not trendy ones

• Address NFRs explicitly - Don't assume performance/security

• Plan for failure - Include error handling, monitoring, resilience

• Keep it readable - Architecture doc is for humans, not just completeness

Reference Files

• references/requirements-analysis-guide.md

• Requirement extraction techniques

• references/project-type-patterns.md

• Project type detection criteria

• references/complexity-assessment.md

• Detailed complexity scoring

• references/patterns-catalog.md

• Complete architectural patterns library

• references/technology-decision-framework.md

• Tech evaluation matrices

• references/templates.md

• Architecture document templates

• references/adr-examples.md

• ADR examples by domain

• references/nfr-architecture-mapping.md

• NFR to architecture mapping

• references/example-architectures.md

• Complete architecture examples

When to Escalate

Escalate to user when:

• Requirements are insufficient or contradictory

• Conflicting NFRs (e.g., cost vs. performance)

• Missing critical information (user scale, data volume unknown)

• Highly complex system (score >80) requires expert input

• Compliance requirements (HIPAA, PCI-DSS, SOC2) need legal review

• Technology choices have significant business impact

• Budget constraints eliminate viable options

Part of BMAD Enhanced Planning Suite