--- 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"`