mini-starter/.bmad-core/templates/brownfield-architecture-tmpl.yaml

# <!-- Powered by BMAD™ Core -->
template:
  id: brownfield-architecture-template-v2
  name: Brownfield Enhancement Architecture
  version: 2.0
  output:
    format: markdown
    filename: docs/architecture.md
    title: "{{project_name}} Brownfield Enhancement Architecture"

workflow:
  mode: interactive
  elicitation: advanced-elicitation

sections:
  - id: introduction
    title: Introduction
    instruction: |
      IMPORTANT - SCOPE AND ASSESSMENT REQUIRED:

      This architecture document is for SIGNIFICANT enhancements to existing projects that require comprehensive architectural planning. Before proceeding:

      1. **Verify Complexity**: Confirm this enhancement requires architectural planning. For simple additions, recommend: "For simpler changes that don't require architectural planning, consider using the brownfield-create-epic or brownfield-create-story task with the Product Owner instead."

      2. **REQUIRED INPUTS**:
         - Completed brownfield-prd.md
         - Existing project technical documentation (from docs folder or user-provided)
         - Access to existing project structure (IDE or uploaded files)

      3. **DEEP ANALYSIS MANDATE**: You MUST conduct thorough analysis of the existing codebase, architecture patterns, and technical constraints before making ANY architectural recommendations. Every suggestion must be based on actual project analysis, not assumptions.

      4. **CONTINUOUS VALIDATION**: Throughout this process, explicitly validate your understanding with the user. For every architectural decision, confirm: "Based on my analysis of your existing system, I recommend [decision] because [evidence from actual project]. Does this align with your system's reality?"

      If any required inputs are missing, request them before proceeding.
    elicit: true
    sections:
      - id: intro-content
        content: |
          This document outlines the architectural approach for enhancing {{project_name}} with {{enhancement_description}}. Its primary goal is to serve as the guiding architectural blueprint for AI-driven development of new features while ensuring seamless integration with the existing system.

          **Relationship to Existing Architecture:**
          This document supplements existing project architecture by defining how new components will integrate with current systems. Where conflicts arise between new and existing patterns, this document provides guidance on maintaining consistency while implementing enhancements.
      - id: existing-project-analysis
        title: Existing Project Analysis
        instruction: |
          Analyze the existing project structure and architecture:

          1. Review existing documentation in docs folder
          2. Examine current technology stack and versions
          3. Identify existing architectural patterns and conventions
          4. Note current deployment and infrastructure setup
          5. Document any constraints or limitations

          CRITICAL: After your analysis, explicitly validate your findings: "Based on my analysis of your project, I've identified the following about your existing system: [key findings]. Please confirm these observations are accurate before I proceed with architectural recommendations."
        elicit: true
        sections:
          - id: current-state
            title: Current Project State
            template: |
              - **Primary Purpose:** {{existing_project_purpose}}
              - **Current Tech Stack:** {{existing_tech_summary}}
              - **Architecture Style:** {{existing_architecture_style}}
              - **Deployment Method:** {{existing_deployment_approach}}
          - id: available-docs
            title: Available Documentation
            type: bullet-list
            template: "- {{existing_docs_summary}}"
          - id: constraints
            title: Identified Constraints
            type: bullet-list
            template: "- {{constraint}}"
      - id: changelog
        title: Change Log
        type: table
        columns: [Change, Date, Version, Description, Author]
        instruction: Track document versions and changes

  - id: enhancement-scope
    title: Enhancement Scope and Integration Strategy
    instruction: |
      Define how the enhancement will integrate with the existing system:

      1. Review the brownfield PRD enhancement scope
      2. Identify integration points with existing code
      3. Define boundaries between new and existing functionality
      4. Establish compatibility requirements

      VALIDATION CHECKPOINT: Before presenting the integration strategy, confirm: "Based on my analysis, the integration approach I'm proposing takes into account [specific existing system characteristics]. These integration points and boundaries respect your current architecture patterns. Is this assessment accurate?"
    elicit: true
    sections:
      - id: enhancement-overview
        title: Enhancement Overview
        template: |
          **Enhancement Type:** {{enhancement_type}}
          **Scope:** {{enhancement_scope}}
          **Integration Impact:** {{integration_impact_level}}
      - id: integration-approach
        title: Integration Approach
        template: |
          **Code Integration Strategy:** {{code_integration_approach}}
          **Database Integration:** {{database_integration_approach}}
          **API Integration:** {{api_integration_approach}}
          **UI Integration:** {{ui_integration_approach}}
      - id: compatibility-requirements
        title: Compatibility Requirements
        template: |
          - **Existing API Compatibility:** {{api_compatibility}}
          - **Database Schema Compatibility:** {{db_compatibility}}
          - **UI/UX Consistency:** {{ui_compatibility}}
          - **Performance Impact:** {{performance_constraints}}

  - id: tech-stack
    title: Tech Stack
    instruction: |
      Ensure new components align with existing technology choices:

      1. Use existing technology stack as the foundation
      2. Only introduce new technologies if absolutely necessary
      3. Justify any new additions with clear rationale
      4. Ensure version compatibility with existing dependencies
    elicit: true
    sections:
      - id: existing-stack
        title: Existing Technology Stack
        type: table
        columns: [Category, Current Technology, Version, Usage in Enhancement, Notes]
        instruction: Document the current stack that must be maintained or integrated with
      - id: new-tech-additions
        title: New Technology Additions
        condition: Enhancement requires new technologies
        type: table
        columns: [Technology, Version, Purpose, Rationale, Integration Method]
        instruction: Only include if new technologies are required for the enhancement

  - id: data-models
    title: Data Models and Schema Changes
    instruction: |
      Define new data models and how they integrate with existing schema:

      1. Identify new entities required for the enhancement
      2. Define relationships with existing data models
      3. Plan database schema changes (additions, modifications)
      4. Ensure backward compatibility
    elicit: true
    sections:
      - id: new-models
        title: New Data Models
        repeatable: true
        sections:
          - id: model
            title: "{{model_name}}"
            template: |
              **Purpose:** {{model_purpose}}
              **Integration:** {{integration_with_existing}}

              **Key Attributes:**
              - {{attribute_1}}: {{type_1}} - {{description_1}}
              - {{attribute_2}}: {{type_2}} - {{description_2}}

              **Relationships:**
              - **With Existing:** {{existing_relationships}}
              - **With New:** {{new_relationships}}
      - id: schema-integration
        title: Schema Integration Strategy
        template: |
          **Database Changes Required:**
          - **New Tables:** {{new_tables_list}}
          - **Modified Tables:** {{modified_tables_list}}
          - **New Indexes:** {{new_indexes_list}}
          - **Migration Strategy:** {{migration_approach}}

          **Backward Compatibility:**
          - {{compatibility_measure_1}}
          - {{compatibility_measure_2}}

  - id: component-architecture
    title: Component Architecture
    instruction: |
      Define new components and their integration with existing architecture:

      1. Identify new components required for the enhancement
      2. Define interfaces with existing components
      3. Establish clear boundaries and responsibilities
      4. Plan integration points and data flow

      MANDATORY VALIDATION: Before presenting component architecture, confirm: "The new components I'm proposing follow the existing architectural patterns I identified in your codebase: [specific patterns]. The integration interfaces respect your current component structure and communication patterns. Does this match your project's reality?"
    elicit: true
    sections:
      - id: new-components
        title: New Components
        repeatable: true
        sections:
          - id: component
            title: "{{component_name}}"
            template: |
              **Responsibility:** {{component_description}}
              **Integration Points:** {{integration_points}}

              **Key Interfaces:**
              - {{interface_1}}
              - {{interface_2}}

              **Dependencies:**
              - **Existing Components:** {{existing_dependencies}}
              - **New Components:** {{new_dependencies}}

              **Technology Stack:** {{component_tech_details}}
      - id: interaction-diagram
        title: Component Interaction Diagram
        type: mermaid
        mermaid_type: graph
        instruction: Create Mermaid diagram showing how new components interact with existing ones

  - id: api-design
    title: API Design and Integration
    condition: Enhancement requires API changes
    instruction: |
      Define new API endpoints and integration with existing APIs:

      1. Plan new API endpoints required for the enhancement
      2. Ensure consistency with existing API patterns
      3. Define authentication and authorization integration
      4. Plan versioning strategy if needed
    elicit: true
    sections:
      - id: api-strategy
        title: API Integration Strategy
        template: |
          **API Integration Strategy:** {{api_integration_strategy}}
          **Authentication:** {{auth_integration}}
          **Versioning:** {{versioning_approach}}
      - id: new-endpoints
        title: New API Endpoints
        repeatable: true
        sections:
          - id: endpoint
            title: "{{endpoint_name}}"
            template: |
              - **Method:** {{http_method}}
              - **Endpoint:** {{endpoint_path}}
              - **Purpose:** {{endpoint_purpose}}
              - **Integration:** {{integration_with_existing}}
            sections:
              - id: request
                title: Request
                type: code
                language: json
                template: "{{request_schema}}"
              - id: response
                title: Response
                type: code
                language: json
                template: "{{response_schema}}"

  - id: external-api-integration
    title: External API Integration
    condition: Enhancement requires new external APIs
    instruction: Document new external API integrations required for the enhancement
    repeatable: true
    sections:
      - id: external-api
        title: "{{api_name}} API"
        template: |
          - **Purpose:** {{api_purpose}}
          - **Documentation:** {{api_docs_url}}
          - **Base URL:** {{api_base_url}}
          - **Authentication:** {{auth_method}}
          - **Integration Method:** {{integration_approach}}

          **Key Endpoints Used:**
          - `{{method}} {{endpoint_path}}` - {{endpoint_purpose}}

          **Error Handling:** {{error_handling_strategy}}

  - id: source-tree
    title: Source Tree
    instruction: |
      Define how new code will integrate with existing project structure:

      1. Follow existing project organization patterns
      2. Identify where new files/folders will be placed
      3. Ensure consistency with existing naming conventions
      4. Plan for minimal disruption to existing structure
    elicit: true
    sections:
      - id: existing-structure
        title: Existing Project Structure
        type: code
        language: plaintext
        instruction: Document relevant parts of current structure
        template: "{{existing_structure_relevant_parts}}"
      - id: new-file-organization
        title: New File Organization
        type: code
        language: plaintext
        instruction: Show only new additions to existing structure
        template: |
          {{project-root}}/
          ├── {{existing_structure_context}}
          │   ├── {{new_folder_1}}/           # {{purpose_1}}
          │   │   ├── {{new_file_1}}
          │   │   └── {{new_file_2}}
          │   ├── {{existing_folder}}/        # Existing folder with additions
          │   │   ├── {{existing_file}}       # Existing file
          │   │   └── {{new_file_3}}          # New addition
          │   └── {{new_folder_2}}/           # {{purpose_2}}
      - id: integration-guidelines
        title: Integration Guidelines
        template: |
          - **File Naming:** {{file_naming_consistency}}
          - **Folder Organization:** {{folder_organization_approach}}
          - **Import/Export Patterns:** {{import_export_consistency}}

  - id: infrastructure-deployment
    title: Infrastructure and Deployment Integration
    instruction: |
      Define how the enhancement will be deployed alongside existing infrastructure:

      1. Use existing deployment pipeline and infrastructure
      2. Identify any infrastructure changes needed
      3. Plan deployment strategy to minimize risk
      4. Define rollback procedures
    elicit: true
    sections:
      - id: existing-infrastructure
        title: Existing Infrastructure
        template: |
          **Current Deployment:** {{existing_deployment_summary}}
          **Infrastructure Tools:** {{existing_infrastructure_tools}}
          **Environments:** {{existing_environments}}
      - id: enhancement-deployment
        title: Enhancement Deployment Strategy
        template: |
          **Deployment Approach:** {{deployment_approach}}
          **Infrastructure Changes:** {{infrastructure_changes}}
          **Pipeline Integration:** {{pipeline_integration}}
      - id: rollback-strategy
        title: Rollback Strategy
        template: |
          **Rollback Method:** {{rollback_method}}
          **Risk Mitigation:** {{risk_mitigation}}
          **Monitoring:** {{monitoring_approach}}

  - id: coding-standards
    title: Coding Standards
    instruction: |
      Ensure new code follows existing project conventions:

      1. Document existing coding standards from project analysis
      2. Identify any enhancement-specific requirements
      3. Ensure consistency with existing codebase patterns
      4. Define standards for new code organization
    elicit: true
    sections:
      - id: existing-standards
        title: Existing Standards Compliance
        template: |
          **Code Style:** {{existing_code_style}}
          **Linting Rules:** {{existing_linting}}
          **Testing Patterns:** {{existing_test_patterns}}
          **Documentation Style:** {{existing_doc_style}}
      - id: enhancement-standards
        title: Enhancement-Specific Standards
        condition: New patterns needed for enhancement
        repeatable: true
        template: "- **{{standard_name}}:** {{standard_description}}"
      - id: integration-rules
        title: Critical Integration Rules
        template: |
          - **Existing API Compatibility:** {{api_compatibility_rule}}
          - **Database Integration:** {{db_integration_rule}}
          - **Error Handling:** {{error_handling_integration}}
          - **Logging Consistency:** {{logging_consistency}}

  - id: testing-strategy
    title: Testing Strategy
    instruction: |
      Define testing approach for the enhancement:

      1. Integrate with existing test suite
      2. Ensure existing functionality remains intact
      3. Plan for testing new features
      4. Define integration testing approach
    elicit: true
    sections:
      - id: existing-test-integration
        title: Integration with Existing Tests
        template: |
          **Existing Test Framework:** {{existing_test_framework}}
          **Test Organization:** {{existing_test_organization}}
          **Coverage Requirements:** {{existing_coverage_requirements}}
      - id: new-testing
        title: New Testing Requirements
        sections:
          - id: unit-tests
            title: Unit Tests for New Components
            template: |
              - **Framework:** {{test_framework}}
              - **Location:** {{test_location}}
              - **Coverage Target:** {{coverage_target}}
              - **Integration with Existing:** {{test_integration}}
          - id: integration-tests
            title: Integration Tests
            template: |
              - **Scope:** {{integration_test_scope}}
              - **Existing System Verification:** {{existing_system_verification}}
              - **New Feature Testing:** {{new_feature_testing}}
          - id: regression-tests
            title: Regression Testing
            template: |
              - **Existing Feature Verification:** {{regression_test_approach}}
              - **Automated Regression Suite:** {{automated_regression}}
              - **Manual Testing Requirements:** {{manual_testing_requirements}}

  - id: security-integration
    title: Security Integration
    instruction: |
      Ensure security consistency with existing system:

      1. Follow existing security patterns and tools
      2. Ensure new features don't introduce vulnerabilities
      3. Maintain existing security posture
      4. Define security testing for new components
    elicit: true
    sections:
      - id: existing-security
        title: Existing Security Measures
        template: |
          **Authentication:** {{existing_auth}}
          **Authorization:** {{existing_authz}}
          **Data Protection:** {{existing_data_protection}}
          **Security Tools:** {{existing_security_tools}}
      - id: enhancement-security
        title: Enhancement Security Requirements
        template: |
          **New Security Measures:** {{new_security_measures}}
          **Integration Points:** {{security_integration_points}}
          **Compliance Requirements:** {{compliance_requirements}}
      - id: security-testing
        title: Security Testing
        template: |
          **Existing Security Tests:** {{existing_security_tests}}
          **New Security Test Requirements:** {{new_security_tests}}
          **Penetration Testing:** {{pentest_requirements}}

  - id: checklist-results
    title: Checklist Results Report
    instruction: Execute the architect-checklist and populate results here, focusing on brownfield-specific validation

  - id: next-steps
    title: Next Steps
    instruction: |
      After completing the brownfield architecture:

      1. Review integration points with existing system
      2. Begin story implementation with Dev agent
      3. Set up deployment pipeline integration
      4. Plan rollback and monitoring procedures
    sections:
      - id: story-manager-handoff
        title: Story Manager Handoff
        instruction: |
          Create a brief prompt for Story Manager to work with this brownfield enhancement. Include:
          - Reference to this architecture document
          - Key integration requirements validated with user
          - Existing system constraints based on actual project analysis
          - First story to implement with clear integration checkpoints
          - Emphasis on maintaining existing system integrity throughout implementation
      - id: developer-handoff
        title: Developer Handoff
        instruction: |
          Create a brief prompt for developers starting implementation. Include:
          - Reference to this architecture and existing coding standards analyzed from actual project
          - Integration requirements with existing codebase validated with user
          - Key technical decisions based on real project constraints
          - Existing system compatibility requirements with specific verification steps
          - Clear sequencing of implementation to minimize risk to existing functionality