BMAD-METHOD/bmad-core/templates/infrastructure-architecture-tmpl.md

{{Project Name}} Infrastructure Architecture

[[LLM: Initial Setup

1. Replace {{Project Name}} with the actual project name throughout the document
2. Gather and review required inputs:
   • Product Requirements Document (PRD) - Required for business needs and scale requirements
   • Main System Architecture - Required for infrastructure dependencies
   • Technical Preferences/Tech Stack Document - Required for technology choices
   • PRD Technical Assumptions - Required for cross-referencing repository and service architecture

If any required documents are missing, ask user: "I need the following documents to create a comprehensive infrastructure architecture: [list missing]. Would you like to proceed with available information or provide the missing documents first?"

3. <critical_rule>Cross-reference with PRD Technical Assumptions to ensure infrastructure decisions align with repository and service architecture decisions made in the system architecture.</critical_rule>

Output file location: docs/infrastructure-architecture.md]]

Infrastructure Overview

LLM: Review the product requirements document to understand business needs and scale requirements. Analyze the main system architecture to identify infrastructure dependencies. Document non-functional requirements (performance, scalability, reliability, security). Cross-reference with PRD Technical Assumptions to ensure alignment with repository and service architecture decisions.

• Cloud Provider(s)
• Core Services & Resources
• Regional Architecture
• Multi-environment Strategy

@{example: cloud_strategy}

• Cloud Provider: AWS (primary), with multi-cloud capability for critical services
• Core Services: EKS for container orchestration, RDS for databases, S3 for storage, CloudFront for CDN
• Regional Architecture: Multi-region active-passive with primary in us-east-1, DR in us-west-2
• Multi-environment Strategy: Development, Staging, UAT, Production with identical infrastructure patterns

@{/example}

[[LLM: Infrastructure Elicitation Options Present user with domain-specific elicitation options: "For the Infrastructure Overview section, I can explore:

1. Multi-Cloud Strategy Analysis - Evaluate cloud provider options and vendor lock-in considerations
2. Regional Distribution Planning - Analyze latency requirements and data residency needs
3. Environment Isolation Strategy - Design security boundaries and resource segregation
4. Scalability Patterns Review - Assess auto-scaling needs and traffic patterns
5. Compliance Requirements Analysis - Review regulatory and security compliance needs
6. Cost-Benefit Analysis - Compare infrastructure options and TCO
7. Proceed to next section

Select an option (1-7):"]]

Infrastructure as Code (IaC)

LLM: Define IaC approach based on technical preferences and existing patterns. Consider team expertise, tooling ecosystem, and maintenance requirements.

• Tools & Frameworks
• Repository Structure
• State Management
• Dependency Management

<critical_rule>All infrastructure must be defined as code. No manual resource creation in production environments.</critical_rule>

Environment Configuration

LLM: Design environment strategy that supports the development workflow while maintaining security and cost efficiency. Reference the Environment Transition Strategy section for promotion details.

• Environment Promotion Strategy
• Configuration Management
• Secret Management
• Feature Flag Integration

<<REPEAT: environment>>

{{environment_name}} Environment

• Purpose: {{environment_purpose}}
• Resources: {{environment_resources}}
• Access Control: {{environment_access}}
• Data Classification: {{environment_data_class}}

<>

Environment Transition Strategy

LLM: Detail the complete lifecycle of code and configuration changes from development to production. Include governance, testing gates, and rollback procedures.

• Development to Production Pipeline
• Deployment Stages and Gates
• Approval Workflows and Authorities
• Rollback Procedures
• Change Cadence and Release Windows
• Environment-Specific Configuration Management

Network Architecture

[[LLM: Design network topology considering security zones, traffic patterns, and compliance requirements. Reference main architecture for service communication patterns.

Create Mermaid diagram showing:

• VPC/Network structure

• Security zones and boundaries

• Traffic flow patterns

• Load balancer placement

• Service mesh topology (if applicable)]]

• VPC/VNET Design

• Subnet Strategy

• Security Groups & NACLs

• Load Balancers & API Gateways

• Service Mesh (if applicable)

graph TB
    subgraph "Production VPC"
        subgraph "Public Subnets"
            ALB[Application Load Balancer]
        end
        subgraph "Private Subnets"
            EKS[EKS Cluster]
            RDS[(RDS Database)]
        end
    end
    Internet((Internet)) --> ALB
    ALB --> EKS
    EKS --> RDS

^^CONDITION: uses_service_mesh^^

Service Mesh Architecture

• Mesh Technology: {{service_mesh_tech}}
• Traffic Management: {{traffic_policies}}
• Security Policies: {{mesh_security}}
• Observability Integration: {{mesh_observability}}

^^/CONDITION: uses_service_mesh^^

Compute Resources

LLM: Select compute strategy based on application architecture (microservices, serverless, monolithic). Consider cost, scalability, and operational complexity.

• Container Strategy
• Serverless Architecture
• VM/Instance Configuration
• Auto-scaling Approach

^^CONDITION: uses_kubernetes^^

Kubernetes Architecture

• Cluster Configuration: {{k8s_cluster_config}}
• Node Groups: {{k8s_node_groups}}
• Networking: {{k8s_networking}}
• Storage Classes: {{k8s_storage}}
• Security Policies: {{k8s_security}}

^^/CONDITION: uses_kubernetes^^

Data Resources

[[LLM: Design data infrastructure based on data architecture from main system design. Consider data volumes, access patterns, compliance, and recovery requirements.

Create data flow diagram showing:

• Database topology

• Replication patterns

• Backup flows

• Data migration paths]]

• Database Deployment Strategy

• Backup & Recovery

• Replication & Failover

• Data Migration Strategy

Security Architecture

LLM: Implement defense-in-depth strategy. Reference security requirements from PRD and compliance needs. Consider zero-trust principles where applicable.

• IAM & Authentication
• Network Security
• Data Encryption
• Compliance Controls
• Security Scanning & Monitoring

<critical_rule>Apply principle of least privilege for all access controls. Document all security exceptions with business justification.</critical_rule>

Shared Responsibility Model

LLM: Clearly define boundaries between cloud provider, platform team, development team, and security team responsibilities. This is critical for operational success.

• Cloud Provider Responsibilities
• Platform Team Responsibilities
• Development Team Responsibilities
• Security Team Responsibilities
• Operational Monitoring Ownership
• Incident Response Accountability Matrix

@{example: responsibility_matrix}

Component	Cloud Provider	Platform Team	Dev Team	Security Team
Physical Security	✓	-	-	Audit
Network Security	Partial	✓	Config	Audit
Application Security	-	Tools	✓	Review
Data Encryption	Engine	Config	Implementation	Standards

@{/example}

Monitoring & Observability

LLM: Design comprehensive observability strategy covering metrics, logs, traces, and business KPIs. Ensure alignment with SLA/SLO requirements.

• Metrics Collection
• Logging Strategy
• Tracing Implementation
• Alerting & Incident Response
• Dashboards & Visualization

CI/CD Pipeline

[[LLM: Design deployment pipeline that balances speed with safety. Include progressive deployment strategies and automated quality gates.

Create pipeline diagram showing:

• Build stages

• Test gates

• Deployment stages

• Approval points

• Rollback triggers]]

• Pipeline Architecture

• Build Process

• Deployment Strategy

• Rollback Procedures

• Approval Gates

^^CONDITION: uses_progressive_deployment^^

Progressive Deployment Strategy

• Canary Deployment: {{canary_config}}
• Blue-Green Deployment: {{blue_green_config}}
• Feature Flags: {{feature_flag_integration}}
• Traffic Splitting: {{traffic_split_rules}}

^^/CONDITION: uses_progressive_deployment^^

Disaster Recovery

LLM: Design DR strategy based on business continuity requirements. Define clear RTO/RPO targets and ensure they align with business needs.

• Backup Strategy
• Recovery Procedures
• RTO & RPO Targets
• DR Testing Approach

<critical_rule>DR procedures must be tested at least quarterly. Document test results and improvement actions.</critical_rule>

Cost Optimization

LLM: Balance cost efficiency with performance and reliability requirements. Include both immediate optimizations and long-term strategies.

• Resource Sizing Strategy
• Reserved Instances/Commitments
• Cost Monitoring & Reporting
• Optimization Recommendations

BMAD Integration Architecture

LLM: Design infrastructure to specifically support other BMAD agents and their workflows. This ensures the infrastructure enables the entire BMAD methodology.

Development Agent Support

• Container platform for development environments
• GitOps workflows for application deployment
• Service mesh integration for development testing
• Developer self-service platform capabilities

Product & Architecture Alignment

• Infrastructure implementing PRD scalability requirements
• Deployment automation supporting product iteration speed
• Service reliability meeting product SLAs
• Architecture patterns properly implemented in infrastructure

Cross-Agent Integration Points

• CI/CD pipelines supporting Frontend, Backend, and Full Stack development workflows
• Monitoring and observability data accessible to QA and DevOps agents
• Infrastructure enabling Design Architect's UI/UX performance requirements
• Platform supporting Analyst's data collection and analysis needs

DevOps/Platform Feasibility Review

[[LLM: CRITICAL STEP - Present architectural blueprint summary to DevOps/Platform Engineering Agent for feasibility review. Request specific feedback on:

• Operational Complexity: Are the proposed patterns implementable with current tooling and expertise?
• Resource Constraints: Do infrastructure requirements align with available resources and budgets?
• Security Implementation: Are security patterns achievable with current security toolchain?
• Operational Overhead: Will the proposed architecture create excessive operational burden?
• Technology Constraints: Are selected technologies compatible with existing infrastructure?

Document all feasibility feedback and concerns raised. Iterate on architectural decisions based on operational constraints and feedback.

<critical_rule>Address all critical feasibility concerns before proceeding to final architecture documentation. If critical blockers identified, revise architecture before continuing.</critical_rule>]]

Feasibility Assessment Results

• Green Light Items: {{feasible_items}}
• Yellow Light Items: {{items_needing_adjustment}}
• Red Light Items: {{items_requiring_redesign}}
• Mitigation Strategies: {{mitigation_plans}}

Infrastructure Verification

Validation Framework

This infrastructure architecture will be validated using the comprehensive infrastructure-checklist.md, with particular focus on Section 12: Architecture Documentation Validation. The checklist ensures:

• Completeness of architecture documentation
• Consistency with broader system architecture
• Appropriate level of detail for different stakeholders
• Clear implementation guidance
• Future evolution considerations

Validation Process

The architecture documentation validation should be performed:

• After initial architecture development
• After significant architecture changes
• Before major implementation phases
• During periodic architecture reviews

The Platform Engineer should use the infrastructure checklist to systematically validate all aspects of this architecture document.

Implementation Handoff

LLM: Create structured handoff documentation for implementation team. This ensures architecture decisions are properly communicated and implemented.

Architecture Decision Records (ADRs)

Create ADRs for key infrastructure decisions:

• Cloud provider selection rationale
• Container orchestration platform choice
• Networking architecture decisions
• Security implementation choices
• Cost optimization trade-offs

Implementation Validation Criteria

Define specific criteria for validating correct implementation:

• Infrastructure as Code quality gates
• Security compliance checkpoints
• Performance benchmarks
• Cost targets
• Operational readiness criteria

Knowledge Transfer Requirements

• Technical documentation for operations team
• Runbook creation requirements
• Training needs for platform team
• Handoff meeting agenda items

Infrastructure Evolution

LLM: Document the long-term vision and evolution path for the infrastructure. Consider technology trends, anticipated growth, and technical debt management.

• Technical Debt Inventory
• Planned Upgrades and Migrations
• Deprecation Schedule
• Technology Roadmap
• Capacity Planning
• Scalability Considerations

Integration with Application Architecture

LLM: Map infrastructure components to application services. Ensure infrastructure design supports application requirements and patterns defined in main architecture.

• Service-to-Infrastructure Mapping
• Application Dependency Matrix
• Performance Requirements Implementation
• Security Requirements Implementation
• Data Flow to Infrastructure Correlation
• API Gateway and Service Mesh Integration

Cross-Team Collaboration

LLM: Define clear interfaces and communication patterns between teams. This section is critical for operational success and should include specific touchpoints and escalation paths.

• Platform Engineer and Developer Touchpoints
• Frontend/Backend Integration Requirements
• Product Requirements to Infrastructure Mapping
• Architecture Decision Impact Analysis
• Design Architect UI/UX Infrastructure Requirements
• Analyst Research Integration

Infrastructure Change Management

LLM: Define structured process for infrastructure changes. Include risk assessment, testing requirements, and rollback procedures.

• Change Request Process
• Risk Assessment
• Testing Strategy
• Validation Procedures

LLM: Final Review - Ensure all sections are complete and consistent. Verify feasibility review was conducted and all concerns addressed. Apply final validation against infrastructure checklist.

---

Document Version: 1.0 Last Updated: {{current_date}} Next Review: {{review_date}}