Architecture

Architecture Master - Complete System Architecture Design Workflow

Overview

This skill provides end-to-end architecture design and implementation guidance by orchestrating multiple expert systems and tools available in this repository. It bridges business requirements with technical implementation, ensuring robust, scalable, and maintainable system architectures.

Key Capabilities:

• 🏗️ Multi-Expert Architecture Analysis - Coordinates system, backend, frontend, DevOps, and security architects
• 🎯 Intelligent Pattern Selection - Automatically selects appropriate architectural patterns based on requirements
• 📊 Scalability Planning - Designs for 10x growth with bottleneck analysis
• 🔒 Security-First Design - Integrates security considerations at every layer
• 📋 Implementation Guidance - Provides detailed implementation roadmaps and best practices

When to Use This Skill

Perfect for:

• New system architecture design and planning
• Legacy system modernization and migration strategies
• Microservices decomposition and service boundary definition
• API design and integration architecture
• Performance optimization and scalability planning
• DevOps and infrastructure architecture design
• Security architecture and compliance requirements

Triggers:

• "Help me design the architecture for..."
• "I need to refactor/upgrade our system architecture"
• "Design a microservices architecture for..."
• "Create an API architecture for..."
• "Plan the DevOps infrastructure for..."
• "Design a scalable system architecture..."

Architecture Expert Panel

The skill orchestrates multiple architectural perspectives:

System Architect (Holistic Design)

• Focus: System boundaries, scalability, long-term maintainability
• Patterns: Microservices, DDD, Event Sourcing, CQRS
• Considerations: 10x growth, component coupling, technology evolution

Backend Architect (Data & Services)

• Focus: API design, data integrity, fault tolerance
• Patterns: RESTful APIs, GraphQL, Database Architecture
• Considerations: ACID compliance, security, performance

Frontend Architect (User Experience)

• Focus: Component architecture, state management, performance
• Patterns: SPA, Micro-Frontends, Progressive Web Apps
• Considerations: User experience, performance optimization

DevOps Architect (Infrastructure & Reliability)

• Focus: CI/CD, observability, deployment strategies
• Patterns: IaC, Container Orchestration, Cloud Native
• Considerations: Reliability, monitoring, disaster recovery

Security Architect (Protection & Compliance)

• Focus: Security by design, threat modeling, compliance
• Patterns: Zero Trust, Defense in Depth, Security Controls
• Considerations: Data protection, regulatory compliance

Architecture Design Workflow

Phase 1: Requirements Analysis & Context Understanding

Use when: Starting any architecture project

Tools Used:

/sc:analyze existing-system/requirements
/speckit.specify architecture-requirements
BMAD Architect Agent: *research {domain}

Activities:

• Analyze business requirements and technical constraints
• Evaluate existing system landscape and integration points
• Identify scalability and performance requirements
• Assess security and compliance requirements
• Map stakeholder concerns and success criteria

Phase 2: System Analysis & Architecture Strategy

Use when: Understanding current state and defining approach

Tools Used:

/sc:analyze system-landscape
/sc:business-panel "system-analysis-and-approach"
System Architect Agent: holistic analysis

Activities:

• Map current system dependencies and interactions
• Identify architectural debt and technical constraints
• Evaluate technology stack and infrastructure capabilities
• Assess team skills and development processes
• Define architectural principles and constraints

Phase 3: Pattern Selection & Design Decisions

Use when: Making key architectural choices

Tools Used:

/sc:spec-panel --experts "martin-fowler,sam-newman,michael-nygard" --focus architecture
/sc:design --type architecture system-components
OpenSpec: Architecture change proposal

Activities:

• Select appropriate architectural patterns (microservices, monolith, serverless)
• Define service boundaries and interaction patterns
• Design data architecture and persistence strategies
• Choose integration patterns and communication protocols
• Document architectural decisions with trade-off analysis

Phase 4: Detailed Architecture Design

Use when: Creating comprehensive specifications

Tools Used:

/sc:design --type api --format spec rest-api-design
/sc:design --type database --format diagram data-architecture
BMAD Architect Agent: create-architecture-document

Activities:

• Design system components and their interfaces
• Define API specifications and data contracts
• Design database schemas and data models
• Plan caching, messaging, and integration strategies
• Create deployment and infrastructure architecture

Phase 5: Security & Compliance Architecture

Use when: Ensuring robust security posture

Tools Used:

Security Architect Agent: comprehensive security analysis
/sc:troubleshoot "security-vulnerability-assessment"
Compliance Checklist validation

Activities:

• Conduct threat modeling and security assessment
• Design authentication, authorization, and encryption strategies
• Implement logging, monitoring, and audit capabilities
• Ensure compliance with relevant regulations (GDPR, SOC2, etc.)
• Define security controls and incident response procedures

Phase 6: Implementation Planning & Roadmap

Use when: Creating implementation strategy

Tools Used:

/speckit.tasks architecture-implementation
/sc:spawn "architecture-implementation-coordination"
BMAD DevOps Agent: deployment-strategy

Activities:

• Create phased implementation roadmap
• Define migration strategies and rollback procedures
• Plan testing strategies and quality gates
• Design monitoring and observability architecture
• Generate team training and documentation plans

Integration Patterns

SuperClaude Command Integration

BMAD Agent Orchestration

Specialized MCP Agents

Usage Examples

Example 1: New Microservices System

User: "Help me design the architecture for an e-commerce platform with microservices"

Workflow:
1. Phase 1: Analyze e-commerce requirements and patterns
2. Phase 2: Evaluate monolith vs microservices approach
3. Phase 3: Service boundary definition and API contracts
4. Phase 4: Detailed service architecture and data flow
5. Phase 5: Payment processing security architecture
6. Phase 6: Implementation roadmap with migration strategy

Example 2: Legacy System Modernization

User: "I need to modernize our 10-year-old monolithic application"

Workflow:
1. Phase 1: Comprehensive system analysis and assessment
2. Phase 2: Strangler Fig pattern planning and execution
3. Phase 3: Microservice decomposition strategy
4. Phase 4: API gateway and service mesh design
5. Phase 5: Data migration and modernization planning
6. Phase 6: Phased rollout and risk mitigation

Example 3: High-Performance API System

User: "Design architecture for a high-performance API that handles millions of requests"

Workflow:
1. Phase 1: Performance requirements and load analysis
2. Phase 2: Scalability architecture and technology selection
3. Phase 3: API design with caching and optimization
4. Phase 4: Database architecture for high throughput
5. Phase 5: Monitoring and observability design
6. Phase 6: Performance testing and optimization roadmap

Quality Assurance Mechanisms

Multi-Expert Validation

• Spec Panel: Martin Fowler, Sam Newman, Michael Nygard review
• Architectural Reviews: Multiple architect perspectives and cross-validation
• Pattern Compliance: Ensure architectural patterns are correctly implemented
• Security Validation: Comprehensive security review and threat modeling

Automated Checks

• Scalability Analysis: Automated bottleneck identification
• Dependency Analysis: System dependency mapping and risk assessment
• Compliance Validation: Regulatory and industry standard compliance checks
• Performance Validation: Performance modeling and bottleneck prediction

Best Practice Integration

• Industry Standards: Adherence to architectural best practices
• Technology Alignment: Consistent with technology stack and organizational capabilities
• Maintainability: Future-proof design and evolution planning
• Documentation Standards: Comprehensive architectural documentation

Output Deliverables

Primary Deliverable: Complete Architecture Package

architecture-package/
├── docs/
│   ├── architecture-overview.md          # Executive summary
│   ├── system-architecture.md           # Detailed system design
│   ├── api-architecture.md              # API specifications
│   ├── data-architecture.md             # Data and database design
│   ├── security-architecture.md          # Security design
│   ├── deployment-architecture.md        # Infrastructure design
│   └── migration-strategy.md             # Implementation roadmap
├── diagrams/
│   ├── system-overview.png             # High-level architecture diagram
│   ├── component-diagram.png            # Component interaction diagram
│   ├── data-flow.png                    # Data flow diagram
│   └── deployment-diagram.png           # Deployment architecture
├── decisions/
│   ├── architectural-decisions.md      # Decision log with rationale
│   ├── trade-offs.md                   # Trade-off analysis
│   └── technology-selection.md         # Technology evaluation
├── checklists/
│   ├── architecture-review.md          # Quality validation checklist
│   ├── security-checklist.md           # Security validation
│   ├── performance-checklist.md        # Performance validation
│   └── scalability-checklist.md         # Scalability validation
└── implementation/
    ├── implementation-roadmap.md       # Phased implementation plan
    ├── team-guidelines.md            # Development team guidelines
    ├── testing-strategy.md            # Testing and validation plan
    └── monitoring-strategy.md          # Observability plan

Supporting Artifacts

• OpenSpec Change Files: Structured architectural change proposals
• BMAD Template Outputs: Standardized architecture documentation
• SpeckIT Task Plans: Detailed implementation task breakdowns
• Expert Panel Reports: Multi-expert validation and recommendations

Advanced Features

Intelligent Pattern Matching

• Automatically suggests appropriate architectural patterns based on requirements
• Pattern library with implementation guidance and best practices
• Pattern evolution planning and adaptation strategies

Technology Stack Analysis

• Evaluates existing technology stack against requirements
• Recommends technology upgrades and migration paths
• Considers team skills, organizational context, and budget constraints

Risk Assessment

• Identifies architectural risks and failure modes
• Provides mitigation strategies and contingency planning
• Includes business impact analysis and risk scoring

Cost Optimization

• Analyzes total cost of ownership (TCO) for architectural decisions
• Optimizes infrastructure costs and licensing strategies
• Balances technical excellence with financial reality

Troubleshooting

Common Architectural Challenges

• Monolith to Microservices Transition: Use Strangler Fig pattern with gradual migration
• Performance Bottlenecks: Comprehensive performance analysis with optimization strategies
• Security Compliance: Layered security approach with defense-in-depth principles
• Team Skills Gap: Training recommendations and hiring strategies

Architecture Decision Recovery

• Pattern Selection Issues: Re-evaluate requirements and match patterns appropriately
• Technology Trade-offs: Re-assess technical decisions with updated requirements
• Integration Challenges: Design adaptive integration patterns and APIs
• Scalability Problems: Identify scaling bottlenecks and redesign hot components

Best Practices

For System Design

• Start with clear system boundaries and interfaces
• Design for failure with fault isolation and recovery
• Implement observability from the beginning
• Plan for evolution and future changes

For Technology Selection

• Choose boring technology when possible
• Consider team expertise and learning curves
• Evaluate long-term maintenance and support
• Balance technical excellence with practical constraints

For Security

• Implement security by design, not as an afterthought
• Use multiple layers of security controls
• Regular security assessments and penetration testing
• Stay updated with security best practices and threat landscapes

For Scalability

• Design for horizontal scaling from the start
• Identify and optimize performance bottlenecks
• Use caching and data partitioning strategies
• Plan for capacity growth and load distribution

This architecture skill transforms the complex process of system architecture design into a guided, expert-supported workflow that leverages the full power of your integrated development toolset. It ensures that architectural decisions are well-reasoned, thoroughly validated, and aligned with both business requirements and long-term technical strategy.