BMAD-METHOD/bmad-core/templates/architecture-tmpl.yaml

template:
  id: architecture-template-v2
  name: Architecture Document
  version: 2.0
  output:
    format: markdown
    filename: docs/architecture.md
    title: "{{project_name}} Architecture Document"

workflow:
  mode: interactive
  elicitation: advanced-elicitation

sections:
  - id: introduction
    title: Introduction
    instruction: |
      If available, review any provided relevant documents to gather all relevant context before beginning. If at a minimum you cannot locate docs/prd.md ask the user what docs will provide the basis for the architecture.
    sections:
      - id: intro-content
        content: |
          This document outlines the overall project architecture for {{project_name}}, including backend systems, shared services, and non-UI specific concerns. Its primary goal is to serve as the guiding architectural blueprint for AI-driven development, ensuring consistency and adherence to chosen patterns and technologies.
          
          **Relationship to Frontend Architecture:**
          If the project includes a significant user interface, a separate Frontend Architecture Document will detail the frontend-specific design and MUST be used in conjunction with this document. Core technology stack choices documented herein (see "Tech Stack") are definitive for the entire project, including any frontend components.
      - id: starter-template
        title: Starter Template or Existing Project
        instruction: |
          Before proceeding further with architecture design, check if the project is based on a starter template or existing codebase:
          
          1. Review the PRD and brainstorming brief for any mentions of:
          - Starter templates (e.g., Create React App, Next.js, Vue CLI, Angular CLI, etc.)
          - Existing projects or codebases being used as a foundation
          - Boilerplate projects or scaffolding tools
          - Previous projects to be cloned or adapted
          
          2. If a starter template or existing project is mentioned:
          - Ask the user to provide access via one of these methods:
            - Link to the starter template documentation
            - Upload/attach the project files (for small projects)
            - Share a link to the project repository (GitHub, GitLab, etc.)
          - Analyze the starter/existing project to understand:
            - Pre-configured technology stack and versions
            - Project structure and organization patterns
            - Built-in scripts and tooling
            - Existing architectural patterns and conventions
            - Any limitations or constraints imposed by the starter
          - Use this analysis to inform and align your architecture decisions
          
          3. If no starter template is mentioned but this is a greenfield project:
          - Suggest appropriate starter templates based on the tech stack preferences
          - Explain the benefits (faster setup, best practices, community support)
          - Let the user decide whether to use one
          
          4. If the user confirms no starter template will be used:
          - Proceed with architecture design from scratch
          - Note that manual setup will be required for all tooling and configuration
          
          Document the decision here before proceeding with the architecture design. If none, just say N/A
        elicit: true
      - id: changelog
        title: Change Log
        type: table
        columns: [Date, Version, Description, Author]
        instruction: Track document versions and changes

  - id: high-level-architecture
    title: High Level Architecture
    instruction: |
      This section contains multiple subsections that establish the foundation of the architecture. Present all subsections together at once.
    elicit: true
    sections:
      - id: technical-summary
        title: Technical Summary
        instruction: |
          Provide a brief paragraph (3-5 sentences) overview of:
          - The system's overall architecture style
          - Key components and their relationships
          - Primary technology choices
          - Core architectural patterns being used
          - Reference back to the PRD goals and how this architecture supports them
      - id: high-level-overview
        title: High Level Overview
        instruction: |
          Based on the PRD's Technical Assumptions section, describe:
          
          1. The main architectural style (e.g., Monolith, Microservices, Serverless, Event-Driven)
          2. Repository structure decision from PRD (Monorepo/Polyrepo)
          3. Service architecture decision from PRD
          4. Primary user interaction flow or data flow at a conceptual level
          5. Key architectural decisions and their rationale
      - id: project-diagram
        title: High Level Project Diagram
        type: mermaid
        mermaid_type: graph
        instruction: |
          Create a Mermaid diagram that visualizes the high-level architecture. Consider:
          - System boundaries
          - Major components/services
          - Data flow directions
          - External integrations
          - User entry points
          
      - id: architectural-patterns
        title: Architectural and Design Patterns
        instruction: |
          List the key high-level patterns that will guide the architecture. For each pattern:
          
          1. Present 2-3 viable options if multiple exist
          2. Provide your recommendation with clear rationale
          3. Get user confirmation before finalizing
          4. These patterns should align with the PRD's technical assumptions and project goals
          
          Common patterns to consider:
          - Architectural style patterns (Serverless, Event-Driven, Microservices, CQRS, Hexagonal)
          - Code organization patterns (Dependency Injection, Repository, Module, Factory)
          - Data patterns (Event Sourcing, Saga, Database per Service)
          - Communication patterns (REST, GraphQL, Message Queue, Pub/Sub)
        template: "- **{{pattern_name}}:** {{pattern_description}} - _Rationale:_ {{rationale}}"
        examples:
          - "**Serverless Architecture:** Using AWS Lambda for compute - _Rationale:_ Aligns with PRD requirement for cost optimization and automatic scaling"
          - "**Repository Pattern:** Abstract data access logic - _Rationale:_ Enables testing and future database migration flexibility"
          - "**Event-Driven Communication:** Using SNS/SQS for service decoupling - _Rationale:_ Supports async processing and system resilience"

  - id: tech-stack
    title: Tech Stack
    instruction: |
      This is the DEFINITIVE technology selection section. Work with the user to make specific choices:
      
      1. Review PRD technical assumptions and any preferences from {root}/data/technical-preferences.yaml or an attached technical-preferences
      2. For each category, present 2-3 viable options with pros/cons
      3. Make a clear recommendation based on project needs
      4. Get explicit user approval for each selection
      5. Document exact versions (avoid "latest" - pin specific versions)
      6. This table is the single source of truth - all other docs must reference these choices
      
      Key decisions to finalize - before displaying the table, ensure you are aware of or ask the user about - let the user know if they are not sure on any that you can also provide suggestions with rationale:
      
      - Starter templates (if any)
      - Languages and runtimes with exact versions
      - Frameworks and libraries / packages
      - Cloud provider and key services choices
      - Database and storage solutions - if unclear suggest sql or nosql or other types depending on the project and depending on cloud provider offer a suggestion
      - Development tools
      
      Upon render of the table, ensure the user is aware of the importance of this sections choices, should also look for gaps or disagreements with anything, ask for any clarifications if something is unclear why its in the list, and also right away elicit feedback - this statement and the options should be rendered and then prompt right all before allowing user input.
    elicit: true
    sections:
      - id: cloud-infrastructure
        title: Cloud Infrastructure
        template: |
          - **Provider:** {{cloud_provider}}
          - **Key Services:** {{core_services_list}}
          - **Deployment Regions:** {{regions}}
      - id: technology-stack-table
        title: Technology Stack Table
        type: table
        columns: [Category, Technology, Version, Purpose, Rationale]
        instruction: Populate the technology stack table with all relevant technologies
        examples:
          - "| **Language** | TypeScript | 5.3.3 | Primary development language | Strong typing, excellent tooling, team expertise |"
          - "| **Runtime** | Node.js | 20.11.0 | JavaScript runtime | LTS version, stable performance, wide ecosystem |"
          - "| **Framework** | NestJS | 10.3.2 | Backend framework | Enterprise-ready, good DI, matches team patterns |"

  - id: data-models
    title: Data Models
    instruction: |
      Define the core data models/entities:
      
      1. Review PRD requirements and identify key business entities
      2. For each model, explain its purpose and relationships
      3. Include key attributes and data types
      4. Show relationships between models
      5. Discuss design decisions with user
      
      Create a clear conceptual model before moving to database schema.
    elicit: true
    repeatable: true
    sections:
      - id: model
        title: "{{model_name}}"
        template: |
          **Purpose:** {{model_purpose}}
          
          **Key Attributes:**
          - {{attribute_1}}: {{type_1}} - {{description_1}}
          - {{attribute_2}}: {{type_2}} - {{description_2}}
          
          **Relationships:**
          - {{relationship_1}}
          - {{relationship_2}}

  - id: components
    title: Components
    instruction: |
      Based on the architectural patterns, tech stack, and data models from above:
      
      1. Identify major logical components/services and their responsibilities
      2. Consider the repository structure (monorepo/polyrepo) from PRD
      3. Define clear boundaries and interfaces between components
      4. For each component, specify:
      - Primary responsibility
      - Key interfaces/APIs exposed
      - Dependencies on other components
      - Technology specifics based on tech stack choices
      
      5. Create component diagrams where helpful
    elicit: true
    sections:
      - id: component-list
        repeatable: true
        title: "{{component_name}}"
        template: |
          **Responsibility:** {{component_description}}
          
          **Key Interfaces:**
          - {{interface_1}}
          - {{interface_2}}
          
          **Dependencies:** {{dependencies}}
          
          **Technology Stack:** {{component_tech_details}}
      - id: component-diagrams
        title: Component Diagrams
        type: mermaid
        instruction: |
          Create Mermaid diagrams to visualize component relationships. Options:
          - C4 Container diagram for high-level view
          - Component diagram for detailed internal structure
          - Sequence diagrams for complex interactions
          Choose the most appropriate for clarity

  - id: external-apis
    title: External APIs
    condition: Project requires external API integrations
    instruction: |
      For each external service integration:
      
      1. Identify APIs needed based on PRD requirements and component design
      2. If documentation URLs are unknown, ask user for specifics
      3. Document authentication methods and security considerations
      4. List specific endpoints that will be used
      5. Note any rate limits or usage constraints
      
      If no external APIs are needed, state this explicitly and skip to next section.
    elicit: true
    repeatable: true
    sections:
      - id: api
        title: "{{api_name}} API"
        template: |
          - **Purpose:** {{api_purpose}}
          - **Documentation:** {{api_docs_url}}
          - **Base URL(s):** {{api_base_url}}
          - **Authentication:** {{auth_method}}
          - **Rate Limits:** {{rate_limits}}
          
          **Key Endpoints Used:**
          - `{{method}} {{endpoint_path}}` - {{endpoint_purpose}}
          
          **Integration Notes:** {{integration_considerations}}

  - id: core-workflows
    title: Core Workflows
    type: mermaid
    mermaid_type: sequence
    instruction: |
      Illustrate key system workflows using sequence diagrams:
      
      1. Identify critical user journeys from PRD
      2. Show component interactions including external APIs
      3. Include error handling paths
      4. Document async operations
      5. Create both high-level and detailed diagrams as needed
      
      Focus on workflows that clarify architecture decisions or complex interactions.
    elicit: true

  - id: rest-api-spec
    title: REST API Spec
    condition: Project includes REST API
    type: code
    language: yaml
    instruction: |
      If the project includes a REST API:
      
      1. Create an OpenAPI 3.0 specification
      2. Include all endpoints from epics/stories
      3. Define request/response schemas based on data models
      4. Document authentication requirements
      5. Include example requests/responses
      
      Use YAML format for better readability. If no REST API, skip this section.
    elicit: true
    template: |
      openapi: 3.0.0
      info:
        title: {{api_title}}
        version: {{api_version}}
        description: {{api_description}}
      servers:
        - url: {{server_url}}
          description: {{server_description}}

  - id: database-schema
    title: Database Schema
    instruction: |
      Transform the conceptual data models into concrete database schemas:
      
      1. Use the database type(s) selected in Tech Stack
      2. Create schema definitions using appropriate notation
      3. Include indexes, constraints, and relationships
      4. Consider performance and scalability
      5. For NoSQL, show document structures
      
      Present schema in format appropriate to database type (SQL DDL, JSON schema, etc.)
    elicit: true

  - id: source-tree
    title: Source Tree
    type: code
    language: plaintext
    instruction: |
      Create a project folder structure that reflects:
      
      1. The chosen repository structure (monorepo/polyrepo)
      2. The service architecture (monolith/microservices/serverless)
      3. The selected tech stack and languages
      4. Component organization from above
      5. Best practices for the chosen frameworks
      6. Clear separation of concerns
      
      Adapt the structure based on project needs. For monorepos, show service separation. For serverless, show function organization. Include language-specific conventions.
    elicit: true
    examples:
      - |
        project-root/
        ├── packages/
        │   ├── api/                    # Backend API service
        │   ├── web/                    # Frontend application
        │   ├── shared/                 # Shared utilities/types
        │   └── infrastructure/         # IaC definitions
        ├── scripts/                    # Monorepo management scripts
        └── package.json                # Root package.json with workspaces

  - id: infrastructure-deployment
    title: Infrastructure and Deployment
    instruction: |
      Define the deployment architecture and practices:
      
      1. Use IaC tool selected in Tech Stack
      2. Choose deployment strategy appropriate for the architecture
      3. Define environments and promotion flow
      4. Establish rollback procedures
      5. Consider security, monitoring, and cost optimization
      
      Get user input on deployment preferences and CI/CD tool choices.
    elicit: true
    sections:
      - id: infrastructure-as-code
        title: Infrastructure as Code
        template: |
          - **Tool:** {{iac_tool}} {{version}}
          - **Location:** `{{iac_directory}}`
          - **Approach:** {{iac_approach}}
      - id: deployment-strategy
        title: Deployment Strategy
        template: |
          - **Strategy:** {{deployment_strategy}}
          - **CI/CD Platform:** {{cicd_platform}}
          - **Pipeline Configuration:** `{{pipeline_config_location}}`
      - id: environments
        title: Environments
        repeatable: true
        template: "- **{{env_name}}:** {{env_purpose}} - {{env_details}}"
      - id: promotion-flow
        title: Environment Promotion Flow
        type: code
        language: text
        template: "{{promotion_flow_diagram}}"
      - id: rollback-strategy
        title: Rollback Strategy
        template: |
          - **Primary Method:** {{rollback_method}}
          - **Trigger Conditions:** {{rollback_triggers}}
          - **Recovery Time Objective:** {{rto}}

  - id: error-handling-strategy
    title: Error Handling Strategy
    instruction: |
      Define comprehensive error handling approach:
      
      1. Choose appropriate patterns for the language/framework from Tech Stack
      2. Define logging standards and tools
      3. Establish error categories and handling rules
      4. Consider observability and debugging needs
      5. Ensure security (no sensitive data in logs)
      
      This section guides both AI and human developers in consistent error handling.
    elicit: true
    sections:
      - id: general-approach
        title: General Approach
        template: |
          - **Error Model:** {{error_model}}
          - **Exception Hierarchy:** {{exception_structure}}
          - **Error Propagation:** {{propagation_rules}}
      - id: logging-standards
        title: Logging Standards
        template: |
          - **Library:** {{logging_library}} {{version}}
          - **Format:** {{log_format}}
          - **Levels:** {{log_levels_definition}}
          - **Required Context:**
            - Correlation ID: {{correlation_id_format}}
            - Service Context: {{service_context}}
            - User Context: {{user_context_rules}}
      - id: error-patterns
        title: Error Handling Patterns
        sections:
          - id: external-api-errors
            title: External API Errors
            template: |
              - **Retry Policy:** {{retry_strategy}}
              - **Circuit Breaker:** {{circuit_breaker_config}}
              - **Timeout Configuration:** {{timeout_settings}}
              - **Error Translation:** {{error_mapping_rules}}
          - id: business-logic-errors
            title: Business Logic Errors
            template: |
              - **Custom Exceptions:** {{business_exception_types}}
              - **User-Facing Errors:** {{user_error_format}}
              - **Error Codes:** {{error_code_system}}
          - id: data-consistency
            title: Data Consistency
            template: |
              - **Transaction Strategy:** {{transaction_approach}}
              - **Compensation Logic:** {{compensation_patterns}}
              - **Idempotency:** {{idempotency_approach}}

  - id: coding-standards
    title: Coding Standards
    instruction: |
      These standards are MANDATORY for AI agents. Work with user to define ONLY the critical rules needed to prevent bad code. Explain that:
      
      1. This section directly controls AI developer behavior
      2. Keep it minimal - assume AI knows general best practices
      3. Focus on project-specific conventions and gotchas
      4. Overly detailed standards bloat context and slow development
      5. Standards will be extracted to separate file for dev agent use
      
      For each standard, get explicit user confirmation it's necessary.
    elicit: true
    sections:
      - id: core-standards
        title: Core Standards
        template: |
          - **Languages & Runtimes:** {{languages_and_versions}}
          - **Style & Linting:** {{linter_config}}
          - **Test Organization:** {{test_file_convention}}
      - id: naming-conventions
        title: Naming Conventions
        type: table
        columns: [Element, Convention, Example]
        instruction: Only include if deviating from language defaults
      - id: critical-rules
        title: Critical Rules
        instruction: |
          List ONLY rules that AI might violate or project-specific requirements. Examples:
          - "Never use console.log in production code - use logger"
          - "All API responses must use ApiResponse wrapper type"
          - "Database queries must use repository pattern, never direct ORM"
          
          Avoid obvious rules like "use SOLID principles" or "write clean code"
        repeatable: true
        template: "- **{{rule_name}}:** {{rule_description}}"
      - id: language-specifics
        title: Language-Specific Guidelines
        condition: Critical language-specific rules needed
        instruction: Add ONLY if critical for preventing AI mistakes. Most teams don't need this section.
        sections:
          - id: language-rules
            title: "{{language_name}} Specifics"
            repeatable: true
            template: "- **{{rule_topic}}:** {{rule_detail}}"

  - id: test-strategy
    title: Test Strategy and Standards
    instruction: |
      Work with user to define comprehensive test strategy:
      
      1. Use test frameworks from Tech Stack
      2. Decide on TDD vs test-after approach
      3. Define test organization and naming
      4. Establish coverage goals
      5. Determine integration test infrastructure
      6. Plan for test data and external dependencies
      
      Note: Basic info goes in Coding Standards for dev agent. This detailed section is for QA agent and team reference.
    elicit: true
    sections:
      - id: testing-philosophy
        title: Testing Philosophy
        template: |
          - **Approach:** {{test_approach}}
          - **Coverage Goals:** {{coverage_targets}}
          - **Test Pyramid:** {{test_distribution}}
      - id: test-types
        title: Test Types and Organization
        sections:
          - id: unit-tests
            title: Unit Tests
            template: |
              - **Framework:** {{unit_test_framework}} {{version}}
              - **File Convention:** {{unit_test_naming}}
              - **Location:** {{unit_test_location}}
              - **Mocking Library:** {{mocking_library}}
              - **Coverage Requirement:** {{unit_coverage}}
              
              **AI Agent Requirements:**
              - Generate tests for all public methods
              - Cover edge cases and error conditions
              - Follow AAA pattern (Arrange, Act, Assert)
              - Mock all external dependencies
          - id: integration-tests
            title: Integration Tests
            template: |
              - **Scope:** {{integration_scope}}
              - **Location:** {{integration_test_location}}
              - **Test Infrastructure:**
                - **{{dependency_name}}:** {{test_approach}} ({{test_tool}})
            examples:
              - "**Database:** In-memory H2 for unit tests, Testcontainers PostgreSQL for integration"
              - "**Message Queue:** Embedded Kafka for tests"
              - "**External APIs:** WireMock for stubbing"
          - id: e2e-tests
            title: End-to-End Tests
            template: |
              - **Framework:** {{e2e_framework}} {{version}}
              - **Scope:** {{e2e_scope}}
              - **Environment:** {{e2e_environment}}
              - **Test Data:** {{e2e_data_strategy}}
      - id: test-data-management
        title: Test Data Management
        template: |
          - **Strategy:** {{test_data_approach}}
          - **Fixtures:** {{fixture_location}}
          - **Factories:** {{factory_pattern}}
          - **Cleanup:** {{cleanup_strategy}}
      - id: continuous-testing
        title: Continuous Testing
        template: |
          - **CI Integration:** {{ci_test_stages}}
          - **Performance Tests:** {{perf_test_approach}}
          - **Security Tests:** {{security_test_approach}}

  - id: security
    title: Security
    instruction: |
      Define MANDATORY security requirements for AI and human developers:
      
      1. Focus on implementation-specific rules
      2. Reference security tools from Tech Stack
      3. Define clear patterns for common scenarios
      4. These rules directly impact code generation
      5. Work with user to ensure completeness without redundancy
    elicit: true
    sections:
      - id: input-validation
        title: Input Validation
        template: |
          - **Validation Library:** {{validation_library}}
          - **Validation Location:** {{where_to_validate}}
          - **Required Rules:**
            - All external inputs MUST be validated
            - Validation at API boundary before processing
            - Whitelist approach preferred over blacklist
      - id: auth-authorization
        title: Authentication & Authorization
        template: |
          - **Auth Method:** {{auth_implementation}}
          - **Session Management:** {{session_approach}}
          - **Required Patterns:**
            - {{auth_pattern_1}}
            - {{auth_pattern_2}}
      - id: secrets-management
        title: Secrets Management
        template: |
          - **Development:** {{dev_secrets_approach}}
          - **Production:** {{prod_secrets_service}}
          - **Code Requirements:**
            - NEVER hardcode secrets
            - Access via configuration service only
            - No secrets in logs or error messages
      - id: api-security
        title: API Security
        template: |
          - **Rate Limiting:** {{rate_limit_implementation}}
          - **CORS Policy:** {{cors_configuration}}
          - **Security Headers:** {{required_headers}}
          - **HTTPS Enforcement:** {{https_approach}}
      - id: data-protection
        title: Data Protection
        template: |
          - **Encryption at Rest:** {{encryption_at_rest}}
          - **Encryption in Transit:** {{encryption_in_transit}}
          - **PII Handling:** {{pii_rules}}
          - **Logging Restrictions:** {{what_not_to_log}}
      - id: dependency-security
        title: Dependency Security
        template: |
          - **Scanning Tool:** {{dependency_scanner}}
          - **Update Policy:** {{update_frequency}}
          - **Approval Process:** {{new_dep_process}}
      - id: security-testing
        title: Security Testing
        template: |
          - **SAST Tool:** {{static_analysis}}
          - **DAST Tool:** {{dynamic_analysis}}
          - **Penetration Testing:** {{pentest_schedule}}

  - id: checklist-results
    title: Checklist Results Report
    instruction: Before running the checklist, offer to output the full architecture document. Once user confirms, execute the architect-checklist and populate results here.

  - id: next-steps
    title: Next Steps
    instruction: |
      After completing the architecture:
      
      1. If project has UI components:
      - Use "Frontend Architecture Mode"
      - Provide this document as input
      
      2. For all projects:
      - Review with Product Owner
      - Begin story implementation with Dev agent
      - Set up infrastructure with DevOps agent
      
      3. Include specific prompts for next agents if needed
    sections:
      - id: architect-prompt
        title: Architect Prompt
        condition: Project has UI components
        instruction: |
          Create a brief prompt to hand off to Architect for Frontend Architecture creation. Include:
          - Reference to this architecture document
          - Key UI requirements from PRD
          - Any frontend-specific decisions made here
          - Request for detailed frontend architecture