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

---
allowed-tools: [Read, Write, Glob, TodoWrite]
description: 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:
   ```json
   {
     "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
```markdown
# 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
```json
{
  "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"`