tpl-superclaude/.claude/commands/design/1-system-architecture/1-create-architecture-framework.md

allowed-tools, description

allowed-tools	description
Read Write Glob TodoWrite	Creates a comprehensive system architecture framework including domain separation, layered architecture, and component responsibility definitions.

Create Architecture Framework

Context

• User Request: $ARGUMENTS
• PRD Source: Identified by --prd argument (PRD session name or index).
• Source PRD: Final PRD document from the specified PRD session directory.
• Architecture Directory: .taskmaster/docs/design/architecture/

Goal

To transform product requirements from a completed PRD into a comprehensive system architecture framework that defines domain boundaries, architectural layers, component responsibilities, and foundational patterns necessary for scalable and maintainable software development.

Process

1. Identify Source PRD Session:

   • Use the --prd argument to locate the correct PRD session directory (e.g., .taskmaster/docs/prd/001-enterprise-expansion/).
   • Find the final PRD document (product-requirements-document_*.md) within the session directory.

2. Extract Architecture Requirements from PRD:

   • Functional Requirements: Core features and business capabilities
   • Non-Functional Requirements: Performance, scalability, security, reliability
   • Technical Constraints: Platform requirements, integration needs, compliance
   • User Experience Requirements: Response time, availability, user load
   • Business Requirements: Growth projections, market constraints, budget limitations

3. Determine Architecture Session Index:

   • Scan the .taskmaster/docs/design/architecture/ directory to find the highest existing session index.
   • Assign the next sequential number for the new architecture session.

4. Create Architecture Session Directory:

   • Create a new directory named [index]-[prd_session_name] inside .taskmaster/docs/design/architecture/.
   • Example: .taskmaster/docs/design/architecture/001-enterprise-expansion/

5. Initialize Architecture Session State:

   • Create a _session-state.json file in the new architecture session directory.
   • Initialize it with architecture session details:

   {
     "index": 1,
     "name": "prd-session-name",
     "type": "architecture",
     "status": "initialized",
     "created": "ISO datetime",
     "lastUpdated": "ISO datetime",
     "currentStep": "architecture_framework_creation",
     "completedSteps": [],
     "nextAction": "Generate comprehensive architecture framework",
     "sourceType": "prd",
     "sourceName": "prd-session-name",
     "architectureScope": "system-wide|domain-specific|service-specific",
     "architectureStyle": "layered|microservices|event-driven|hybrid",
     "architectureResults": {}
   }
   

6. Perform Domain Analysis:

   • Domain Identification: Identify business domains and bounded contexts from PRD features
   • Domain Modeling: Create domain models and understand domain relationships
   • Bounded Context Mapping: Define context boundaries and integration patterns
   • Domain Events: Identify key domain events and workflows
   • Subdomain Classification: Classify subdomains as core, supporting, or generic

7. Design Layered Architecture:

   • Presentation Layer: User interface, API endpoints, controllers
   • Application Layer: Application services, use cases, workflow orchestration
   • Domain Layer: Domain entities, value objects, domain services, aggregates
   • Infrastructure Layer: Data access, external services, technical concerns
   • Cross-Cutting Concerns: Logging, security, monitoring, configuration

8. Define Component Responsibilities:

   • Component Identification: Identify major system components and modules
   • Responsibility Assignment: Define clear responsibilities for each component
   • Interface Design: Design component interfaces and contracts
   • Dependency Management: Establish dependency rules and patterns
   • Component Interaction: Define communication patterns between components

9. Generate Architecture Framework Document:

   • Create the primary architecture document named architecture-framework_[prd_session_name].md.
   • Structure content according to the architecture framework template.
   • Include:
     • Architecture Overview: High-level architecture vision and principles
     • Domain Architecture: Domain boundaries and context mapping
     • Layered Architecture: Layer definitions and responsibilities
     • Component Architecture: Component design and interfaces
     • Architecture Patterns: Key architectural patterns and decisions
     • Quality Attributes: Architecture support for quality requirements

10. Update Session State:

    • Set status to framework_complete.
    • Update architectureResults with architecture metrics and components.
    • Record completion timestamp.

11. Notify User with Architecture Insights:

    • Inform the user that the architecture framework has been successfully generated.
    • Provide the file path and key architectural highlights.
    • Suggest logical next steps based on framework outcomes:
      • "Your architecture framework is complete. Consider designing detailed components using /design/system-architecture/2-design-components --name=[session_name]"
      • "Review the domain boundaries with your team to validate business alignment."
      • "Use the layered architecture to guide development team organization and responsibilities."

Templates & Structures

Architecture Framework Template

# System Architecture Framework: [PRD Session Name]

**Created:** [Date]  
**Source:** PRD Session: [PRD Session Name]  
**Architecture Style:** [Layered/Microservices/Event-Driven/Hybrid]  
**Target Scale:** [Small/Medium/Large/Enterprise]  
**Last Updated:** [Date]

---

## Architecture Overview

### Architecture Vision
- **Vision Statement:** [Clear architectural vision aligned with business goals]
- **Architecture Principles:** [Fundamental principles guiding architectural decisions]
- **Design Philosophy:** [Overall approach to system design and evolution]
- **Success Criteria:** [How architectural success will be measured]

### Architecture Drivers
- **Business Drivers:** [Key business requirements driving architecture]
- **Technical Drivers:** [Technical requirements and constraints]
- **Quality Drivers:** [Quality attributes and non-functional requirements]
- **Constraint Drivers:** [Platform, budget, time, and regulatory constraints]

### Architecture Characteristics
- **Scalability:** [Horizontal and vertical scaling approach]
- **Reliability:** [Fault tolerance and resilience patterns]
- **Performance:** [Performance targets and optimization strategies]
- **Security:** [Security architecture and protection mechanisms]
- **Maintainability:** [Code organization and maintenance strategies]

---

## Domain Architecture

### Domain Identification
#### Core Domain: [Primary Business Domain]
- **Description:** [What this domain represents in the business]
- **Key Entities:** [Main business entities and concepts]
- **Business Rules:** [Critical business rules and constraints]
- **Value Proposition:** [How this domain creates business value]

#### Supporting Domain: [Secondary Business Domain]
- **Description:** [What this domain represents in the business]
- **Key Entities:** [Main business entities and concepts]
- **Business Rules:** [Critical business rules and constraints]
- **Value Proposition:** [How this domain supports core business]

#### Generic Domain: [Utility Domain]
- **Description:** [What this domain represents in the business]
- **Key Entities:** [Main business entities and concepts]
- **Business Rules:** [Critical business rules and constraints]
- **Value Proposition:** [How this domain provides utility]

### Bounded Context Mapping
#### Context 1: [Context Name]
- **Responsibility:** [What this context is responsible for]
- **Boundaries:** [Clear boundaries and what's included/excluded]
- **Interfaces:** [How this context exposes its capabilities]
- **Dependencies:** [Other contexts this depends on]

#### Context 2: [Context Name]
- **Responsibility:** [What this context is responsible for]
- **Boundaries:** [Clear boundaries and what's included/excluded]
- **Interfaces:** [How this context exposes its capabilities]
- **Dependencies:** [Other contexts this depends on]

### Domain Events
- **Event 1:** [Event Name] - [When it occurs and what it represents]
- **Event 2:** [Event Name] - [When it occurs and what it represents]
- **Event 3:** [Event Name] - [When it occurs and what it represents]

### Context Integration Patterns
- **Shared Kernel:** [Shared models and libraries between contexts]
- **Customer-Supplier:** [Upstream/downstream relationships]
- **Conformist:** [One context conforms to another's model]
- **Anti-Corruption Layer:** [Protection against external models]

---

## Layered Architecture

### Presentation Layer
#### Responsibility
- User interface components and user interaction handling
- API endpoints and request/response handling
- Input validation and output formatting
- User authentication and session management

#### Components
- **Web Controllers:** [REST API controllers and request handlers]
- **UI Components:** [User interface components and views]
- **API Gateways:** [API gateway and routing logic]
- **Authentication Middleware:** [Authentication and authorization components]

#### Design Patterns
- **MVC Pattern:** [Model-View-Controller for web interfaces]
- **API Gateway Pattern:** [Centralized API management]
- **Frontend-Backend Separation:** [Clear separation of concerns]

### Application Layer
#### Responsibility
- Application services and use case orchestration
- Business workflow coordination
- Transaction management
- Application-specific business logic

#### Components
- **Application Services:** [Use case implementations and workflow coordination]
- **Command Handlers:** [Command pattern implementations]
- **Query Handlers:** [Query pattern implementations]
- **Workflow Orchestrators:** [Business process coordination]

#### Design Patterns
- **Command Query Responsibility Segregation (CQRS):** [Separate read/write operations]
- **Mediator Pattern:** [Request/response handling]
- **Unit of Work Pattern:** [Transaction management]

### Domain Layer
#### Responsibility
- Core business logic and domain rules
- Domain entities and value objects
- Domain services and aggregates
- Business invariants and constraints

#### Components
- **Domain Entities:** [Core business objects with identity]
- **Value Objects:** [Immutable objects representing concepts]
- **Domain Services:** [Business logic that doesn't belong to entities]
- **Aggregates:** [Consistency boundaries and transaction scopes]
- **Domain Events:** [Business events and event handlers]

#### Design Patterns
- **Domain-Driven Design (DDD):** [Domain modeling and bounded contexts]
- **Repository Pattern:** [Data access abstraction]
- **Factory Pattern:** [Complex object creation]
- **Strategy Pattern:** [Business rule variations]

### Infrastructure Layer
#### Responsibility
- Data persistence and external service integration
- Technical infrastructure and cross-cutting concerns
- Framework and technology-specific implementations
- System integration and communication

#### Components
- **Data Access Layer:** [Database access and ORM implementations]
- **External Service Clients:** [Third-party service integrations]
- **Message Brokers:** [Asynchronous communication infrastructure]
- **Configuration Management:** [Application configuration and settings]

#### Design Patterns
- **Repository Pattern:** [Data access abstraction]
- **Adapter Pattern:** [External service integration]
- **Decorator Pattern:** [Cross-cutting concerns]

---

## Component Architecture

### Component Identification
#### Component 1: [Component Name]
- **Purpose:** [What this component does and why it exists]
- **Responsibilities:** [Specific responsibilities and capabilities]
- **Interfaces:** [Public interfaces and contracts]
- **Dependencies:** [Other components this depends on]
- **Technology:** [Technology stack and frameworks]

#### Component 2: [Component Name]
- **Purpose:** [What this component does and why it exists]
- **Responsibilities:** [Specific responsibilities and capabilities]
- **Interfaces:** [Public interfaces and contracts]
- **Dependencies:** [Other components this depends on]
- **Technology:** [Technology stack and frameworks]

### Component Interaction Patterns
- **Synchronous Communication:** [REST APIs, direct method calls]
- **Asynchronous Communication:** [Message queues, event streams]
- **Data Sharing:** [Shared databases, data stores]
- **Service Discovery:** [How components find each other]

### Component Deployment
- **Deployment Units:** [How components are packaged and deployed]
- **Scalability:** [How components scale independently]
- **Fault Isolation:** [How component failures are contained]
- **Monitoring:** [How components are monitored and observed]

---

## Architecture Patterns

### Architectural Style
- **Primary Style:** [Layered/Microservices/Event-Driven/Hybrid]
- **Style Rationale:** [Why this style was chosen]
- **Style Benefits:** [Benefits this style provides]
- **Style Trade-offs:** [Trade-offs and limitations]

### Key Patterns
#### Pattern 1: [Pattern Name]
- **Problem:** [What problem this pattern solves]
- **Solution:** [How the pattern addresses the problem]
- **Implementation:** [How this pattern is implemented]
- **Benefits:** [Benefits of using this pattern]
- **Trade-offs:** [Costs and limitations]

#### Pattern 2: [Pattern Name]
- **Problem:** [What problem this pattern solves]
- **Solution:** [How the pattern addresses the problem]
- **Implementation:** [How this pattern is implemented]
- **Benefits:** [Benefits of using this pattern]
- **Trade-offs:** [Costs and limitations]

### Integration Patterns
- **API Gateway:** [Centralized API management and routing]
- **Service Mesh:** [Service-to-service communication]
- **Event Sourcing:** [Event-driven state management]
- **CQRS:** [Command Query Responsibility Segregation]

---

## Quality Attributes

### Performance Architecture
- **Response Time:** [Target response times and performance budgets]
- **Throughput:** [Expected transaction volumes and capacity]
- **Resource Usage:** [Memory, CPU, and storage considerations]
- **Caching Strategy:** [Caching layers and invalidation policies]

### Scalability Architecture
- **Horizontal Scaling:** [Scale-out capabilities and patterns]
- **Vertical Scaling:** [Scale-up capabilities and limitations]
- **Auto-scaling:** [Automatic scaling triggers and policies]
- **Load Distribution:** [Load balancing and traffic distribution]

### Reliability Architecture
- **Fault Tolerance:** [Failure handling and recovery patterns]
- **Resilience Patterns:** [Circuit breakers, retries, timeouts]
- **Backup and Recovery:** [Data backup and disaster recovery]
- **High Availability:** [Redundancy and failover mechanisms]

### Security Architecture
- **Authentication:** [User authentication and identity management]
- **Authorization:** [Access control and permission management]
- **Data Protection:** [Encryption and data privacy]
- **Security Monitoring:** [Threat detection and response]

### Maintainability Architecture
- **Code Organization:** [Module structure and dependency management]
- **Testing Strategy:** [Testing architecture and automation]
- **Documentation:** [Architecture documentation and knowledge management]
- **Evolution:** [Architecture evolution and refactoring strategies]

---

## Architecture Decisions

### Decision 1: [Decision Topic]
- **Context:** [Situation requiring a decision]
- **Decision:** [What was decided]
- **Rationale:** [Why this decision was made]
- **Consequences:** [Impact and implications]
- **Alternatives:** [Other options considered]

### Decision 2: [Decision Topic]
- **Context:** [Situation requiring a decision]
- **Decision:** [What was decided]
- **Rationale:** [Why this decision was made]
- **Consequences:** [Impact and implications]
- **Alternatives:** [Other options considered]

---

## Implementation Guidance

### Development Approach
- **Development Methodology:** [Agile, incremental, iterative approach]
- **Team Organization:** [How teams align with architecture]
- **Technology Standards:** [Coding standards and technology guidelines]
- **Quality Practices:** [Code review, testing, and quality assurance]

### Architecture Governance
- **Architecture Review:** [Architecture review process and criteria]
- **Change Management:** [How architecture changes are managed]
- **Compliance:** [Architecture compliance and enforcement]
- **Evolution:** [Architecture evolution and improvement]

### Risk Management
- **Technical Risks:** [Key technical risks and mitigation strategies]
- **Architecture Risks:** [Architecture-specific risks and responses]
- **Integration Risks:** [Component integration and system risks]
- **Performance Risks:** [Performance and scalability risks]

---

## Next Steps

### Immediate Actions
1. **Component Design:** [Design detailed component specifications]
2. **Integration Planning:** [Plan component integration and communication]
3. **Technology Selection:** [Select specific technologies and frameworks]
4. **Prototype Development:** [Develop architecture proof-of-concept]

### Architecture Validation
- **Architecture Review:** [Conduct formal architecture review]
- **Stakeholder Alignment:** [Ensure stakeholder agreement and buy-in]
- **Technical Validation:** [Validate technical feasibility and approach]
- **Risk Assessment:** [Assess and mitigate architecture risks]

### Development Preparation
- **Team Preparation:** [Prepare development teams for implementation]
- **Environment Setup:** [Set up development and testing environments]
- **Tooling Selection:** [Select development tools and frameworks]
- **Documentation:** [Create detailed implementation documentation]

---

## Appendices

### A. PRD Requirements Analysis
[Summary of PRD requirements and their architectural implications]

### B. Architecture Diagrams
[High-level architecture diagrams and component relationships]

### C. Technology Evaluation
[Technology evaluation criteria and selection rationale]

### D. Performance Modeling
[Performance projections and capacity planning]

### E. Security Assessment
[Security requirements and threat modeling]

Session State Structure

{
  "index": 1,
  "name": "prd-session-name",
  "type": "architecture",
  "status": "framework_complete",
  "created": "ISO datetime",
  "lastUpdated": "ISO datetime",
  "currentStep": "framework_complete",
  "completedSteps": ["architecture_framework_creation", "domain_analysis", "layer_design"],
  "nextAction": "Ready for component design or integration architecture",
  "sourceType": "prd",
  "sourceName": "prd-session-name",
  "architectureScope": "system-wide",
  "architectureStyle": "layered",
  "architectureResults": {
    "domains": 3,
    "layers": 4,
    "components": 12,
    "patterns": 8,
    "qualityAttributes": 5,
    "decisions": 6,
    "createdDate": "ISO datetime"
  }
}

Best Practices

✅ DO: Requirements-Driven Architecture

• Start with PRD requirements and ensure architecture serves business needs
• Prioritize quality attributes based on business priorities and user needs
• Consider growth and evolution when designing architectural foundations
• Balance flexibility with simplicity to avoid over-engineering

Why: Requirements-driven architecture ensures that architectural decisions support business objectives and user value.

✅ DO: Domain-Driven Design

• Identify clear domain boundaries and model business concepts accurately
• Use ubiquitous language that bridges business and technical teams
• Separate core domains from supporting and generic domains
• Design for domain evolution and changing business requirements

Why: Domain-driven design creates architecture that reflects business reality and can evolve with business needs.

✅ DO: Layered Responsibility

• Maintain clear layer separation with well-defined responsibilities
• Follow dependency rules to ensure proper architectural flow
• Avoid layer violations and maintain architectural integrity
• Design clean interfaces between layers and components

Why: Layered responsibility creates maintainable, testable, and evolvable architecture.

❌ DON'T: Technology-First Architecture

• Don't start with technology choices before understanding requirements
• Don't let technology constraints drive architectural decisions
• Don't ignore business requirements in favor of technical preferences
• Don't create architecture that serves technology rather than business

Why: Technology-first architecture often results in solutions that don't meet business needs or user requirements.

❌ DON'T: Premature Optimization

• Don't optimize for performance before understanding actual requirements
• Don't add complexity for theoretical future needs
• Don't over-engineer solutions beyond current requirements
• Don't ignore simplicity in favor of sophisticated patterns

Why: Premature optimization creates unnecessary complexity and can hinder business agility and development velocity.

Output

• Format: Comprehensive architecture framework with domain and layer design
• Location: .taskmaster/docs/design/architecture/[index]-[prd_session_name]/
• Primary Files:
  • architecture-framework_[prd_session_name].md - Main architecture framework
  • _session-state.json - Session tracking and metadata

Example Usage

• Create architecture framework from PRD: /design/system-architecture/1-create-architecture-framework --prd="enterprise-expansion"
• Create by PRD index: /design/system-architecture/1-create-architecture-framework --prd="1"