template: id: fullstack-architecture-template-v3-enhanced name: VC-SYS Enhanced Fullstack Architecture Document version: 3.0 output: format: markdown filename: docs/fullstack-architecture.md title: "{{project_name}} Fullstack Architecture Document" # VC-SYS Enhancement: Agent permissions and evidence requirements permissions: owner: technical-architect editors: [integration-specialist, developer, qa, devops] viewers: [scrum-master, product-owner, ux-expert] evidence-required: true anti-hallucination: enabled performance-tracking: enabled workflow: mode: interactive elicitation: advanced-elicitation facilitation: laboratory-agent validation: architect-checklist continuous-monitoring: enabled # VC-SYS Enhancement: Integration with specialized agents agent-coordination: primary: technical-architect secondary: - integration-specialist # For API and integration architecture - laboratory # For creative architectural exploration - devops # For deployment and infrastructure validation: qa approval: product-owner performance-monitor: performance-specialist sections: - id: introduction title: Introduction instruction: | If available, review any provided relevant documents to gather all relevant context before beginning. At minimum, you should have access to docs/prd.md and docs/front-end-spec.md. Ask the user for any documents you need but cannot locate. This template creates a unified architecture that covers both backend and frontend concerns to guide AI-driven fullstack development. VC-SYS Enhancement: Also check for existing architecture documents, legacy system documentation, performance baselines, and security requirements. elicit: true content: | This document outlines the complete fullstack architecture for {{project_name}}, including backend systems, frontend implementation, their integration, and comprehensive operational concerns. It serves as the single source of truth for AI-driven development, ensuring consistency across the entire technology stack with evidence-based decision making. This unified approach combines what would traditionally be separate backend and frontend architecture documents, streamlining the development process for modern fullstack applications where these concerns are increasingly intertwined. **VC-SYS Enhancements:** - Evidence-based architectural decisions with measurable outcomes - Performance benchmarking and continuous monitoring - Security-first design with threat modeling - DevOps integration from inception - Observability and monitoring built-in - Cost optimization considerations sections: - id: architectural-context title: Architectural Context Analysis instruction: | VC-SYS Enhancement: Comprehensive context analysis before architecture design: 1. **Technical Landscape Assessment:** - Existing technology ecosystem - Integration requirements - Legacy system constraints - Migration considerations 2. **Performance Requirements:** - Latency targets (p50, p95, p99) - Throughput requirements - Scalability projections - Cost constraints 3. **Security and Compliance:** - Regulatory requirements - Data classification - Threat modeling scope - Compliance frameworks 4. **Operational Requirements:** - SLA/SLO targets - Disaster recovery needs - Multi-region requirements - Support model elicit: true evidence-required: true - id: starter-template title: Starter Template or Existing Project instruction: | Before proceeding with architecture design, check if the project is based on any starter templates or existing codebases: 1. Review the PRD and other documents for mentions of: - Fullstack starter templates (e.g., T3 Stack, MEAN/MERN starters, Django + React templates) - Monorepo templates (e.g., Nx, Turborepo starters) - Platform-specific starters (e.g., Vercel templates, AWS Amplify starters) - Existing projects being extended or cloned 2. If starter templates or existing projects are mentioned: - Ask the user to provide access (links, repos, or files) - Analyze to understand pre-configured choices and constraints - Note any architectural decisions already made - Identify what can be modified vs what must be retained 3. If no starter is mentioned but this is greenfield: - Suggest appropriate fullstack starters based on tech preferences - Consider platform-specific options (Vercel, AWS, etc.) - Let user decide whether to use one 4. Document the decision and any constraints it imposes VC-SYS Enhancement: Also evaluate starter templates for: - Security vulnerabilities - Performance bottlenecks - Scalability limitations - Maintenance burden - Community support If none, state "N/A - Greenfield project" - id: changelog title: Change Log type: table columns: [Date, Version, Description, Author, Evidence] instruction: Track document versions, changes, and evidence for decisions - id: high-level-architecture title: High Level Architecture instruction: This section contains multiple subsections that establish the foundation. Present all subsections together, then elicit feedback on the complete section. elicit: true sections: - id: technical-summary title: Technical Summary instruction: | Provide a comprehensive overview (4-6 sentences) covering: - Overall architectural style and deployment approach - Frontend framework and backend technology choices - Key integration points between frontend and backend - Infrastructure platform and services - How this architecture achieves PRD goals - Performance and scalability characteristics - Security posture and compliance approach - id: platform-infrastructure title: Platform and Infrastructure Choice instruction: | Based on PRD requirements and technical assumptions, make a platform recommendation: 1. Consider common patterns (not an exhaustive list, use your own best judgement and search the web as needed for emerging trends): - **Vercel + Supabase**: For rapid development with Next.js, built-in auth/storage - **AWS Full Stack**: For enterprise scale with Lambda, API Gateway, S3, Cognito - **Azure**: For .NET ecosystems or enterprise Microsoft environments - **Google Cloud**: For ML/AI heavy applications or Google ecosystem integration - **Kubernetes-based**: For container orchestration needs - **Edge Computing**: For ultra-low latency requirements 2. Present 2-3 viable options with clear pros/cons 3. Make a recommendation with rationale and evidence 4. Include cost projections and TCO analysis 5. Get explicit user confirmation Document the choice and key services that will be used. template: | **Platform:** {{selected_platform}} **Key Services:** {{core_services_list}} **Deployment Host and Regions:** {{regions}} **Cost Projection:** {{monthly_cost_estimate}} **Scalability Path:** {{scale_strategy}} evidence-required: true - id: repository-structure title: Repository Structure instruction: | Define the repository approach based on PRD requirements and platform choice, explain your rationale or ask questions to the user if unsure: 1. For modern fullstack apps, monorepo is often preferred 2. Consider tooling (Nx, Turborepo, Lerna, npm workspaces, pnpm workspaces) 3. Define package/app boundaries 4. Plan for shared code between frontend and backend 5. Consider CI/CD implications 6. Plan for developer experience template: | **Structure:** {{repo_structure_choice}} **Monorepo Tool:** {{monorepo_tool_if_applicable}} **Package Organization:** {{package_strategy}} **Dependency Management:** {{dependency_strategy}} **Build Strategy:** {{build_approach}} - id: architecture-diagram title: High Level Architecture Diagram type: mermaid mermaid_type: graph instruction: | Create a comprehensive Mermaid diagram showing the complete system architecture including: - User entry points (web, mobile, API consumers) - Frontend application deployment - API layer (REST/GraphQL/gRPC) - Backend services and microservices - Databases and storage layers - Caching layers (CDN, Redis, etc.) - Message queues and event streams - External integrations - Monitoring and observability - Security boundaries Use appropriate diagram type for clarity. - id: architectural-patterns title: Architectural Patterns instruction: | List patterns that will guide both frontend and backend development. Include patterns for: - Overall architecture (e.g., Jamstack, Serverless, Microservices, Event-Driven) - Frontend patterns (e.g., Component-based, State management, Micro-frontends) - Backend patterns (e.g., Repository, CQRS, Event Sourcing, Saga) - Integration patterns (e.g., BFF, API Gateway, Service Mesh) - Data patterns (e.g., Database per Service, Shared Database, Event Store) - Security patterns (e.g., Zero Trust, Defense in Depth) - Resilience patterns (e.g., Circuit Breaker, Bulkhead, Retry) For each pattern, provide recommendation, rationale, and evidence. repeatable: true template: "- **{{pattern_name}}:** {{pattern_description}} - _Rationale:_ {{rationale}} - _Evidence:_ {{evidence}}" examples: - "**Jamstack Architecture:** Static site generation with serverless APIs - _Rationale:_ Optimal performance and scalability for content-heavy applications - _Evidence:_ 10x better performance metrics in similar projects" - "**Component-Based UI:** Reusable React components with TypeScript - _Rationale:_ Maintainability and type safety across large codebases - _Evidence:_ 40% reduction in bugs with TypeScript" - "**Repository Pattern:** Abstract data access logic - _Rationale:_ Enables testing and future database migration flexibility - _Evidence:_ 60% faster test execution with mocked repositories" - "**API Gateway Pattern:** Single entry point for all API calls - _Rationale:_ Centralized auth, rate limiting, and monitoring - _Evidence:_ 30% reduction in security incidents" - id: tech-stack title: Tech Stack instruction: | This is the DEFINITIVE technology selection for the entire project. Work with user to finalize all choices. This table is the single source of truth - all development must use these exact versions. VC-SYS Enhancement: Include evidence for each technology choice, performance benchmarks, and security assessments. Key areas to cover: - Frontend and backend languages/frameworks - Databases and caching - Authentication and authorization - API approach - Testing tools for both frontend and backend - Build and deployment tools - Monitoring and logging - Security tools - Performance monitoring Upon render, elicit feedback immediately. elicit: true evidence-required: true sections: - id: tech-stack-table title: Technology Stack Table type: table columns: [Category, Technology, Version, Purpose, Rationale, Evidence] rows: - ["Frontend Language", "{{fe_language}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Frontend Framework", "{{fe_framework}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["UI Component Library", "{{ui_library}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["State Management", "{{state_mgmt}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Backend Language", "{{be_language}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Backend Framework", "{{be_framework}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["API Style", "{{api_style}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Database", "{{database}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Cache", "{{cache}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Message Queue", "{{queue}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["File Storage", "{{storage}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Authentication", "{{auth}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Frontend Testing", "{{fe_test}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Backend Testing", "{{be_test}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["E2E Testing", "{{e2e_test}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Performance Testing", "{{perf_test}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Security Testing", "{{sec_test}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Build Tool", "{{build_tool}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Bundler", "{{bundler}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["IaC Tool", "{{iac_tool}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["CI/CD", "{{cicd}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Container Platform", "{{container}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Service Mesh", "{{mesh}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Monitoring", "{{monitoring}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Logging", "{{logging}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["Tracing", "{{tracing}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - ["CSS Framework", "{{css_framework}}", "{{version}}", "{{purpose}}", "{{why_chosen}}", "{{evidence}}"] - id: data-architecture title: Data Architecture instruction: | VC-SYS Enhancement: Comprehensive data architecture including governance, lineage, and quality. Define the complete data architecture: 1. Data models and relationships 2. Data flow and transformations 3. Data governance and ownership 4. Data quality measures 5. Data security and privacy 6. Data retention and archival elicit: true evidence-required: true sections: - id: data-models title: Data Models instruction: | Define the core data models/entities that will be shared between frontend and backend: 1. Review PRD requirements and identify key business entities 2. For each model, explain its purpose and relationships 3. Include key attributes and data types 4. Show relationships between models 5. Create TypeScript interfaces that can be shared 6. Include data validation rules 7. Define data ownership and governance 8. Discuss design decisions with user Create a clear conceptual model before moving to database schema. repeatable: true sections: - id: model title: "{{model_name}}" template: | **Purpose:** {{model_purpose}} **Owner:** {{data_owner}} **Classification:** {{data_classification}} **Key Attributes:** - {{attribute_1}}: {{type_1}} - {{description_1}} - {{validation_rule_1}} - {{attribute_2}}: {{type_2}} - {{description_2}} - {{validation_rule_2}} sections: - id: typescript-interface title: TypeScript Interface type: code language: typescript template: "{{model_interface}}" - id: validation-schema title: Validation Schema type: code language: typescript template: "{{validation_schema}}" - id: relationships title: Relationships type: bullet-list template: "- {{relationship}}" - id: data-quality title: Data Quality Rules type: bullet-list template: "- {{quality_rule}}" - id: data-flow-architecture title: Data Flow Architecture instruction: | Define how data flows through the system: 1. Data ingestion patterns 2. Transformation pipelines 3. Real-time vs batch processing 4. Event streaming architecture 5. Data synchronization patterns sections: - id: data-flow-diagram title: Data Flow Diagram type: mermaid mermaid_type: graph template: "{{data_flow_diagram}}" - id: streaming-architecture title: Event Streaming Architecture template: | **Event Bus:** {{event_bus_technology}} **Message Format:** {{message_format}} **Partitioning Strategy:** {{partition_strategy}} **Retention Policy:** {{retention_policy}} **Dead Letter Queue:** {{dlq_strategy}} - id: api-architecture title: API Architecture instruction: | VC-SYS Enhancement: Comprehensive API architecture with versioning, documentation, and testing strategies. Based on the chosen API style from Tech Stack, define complete API architecture: 1. API design principles and standards 2. Versioning strategy 3. Documentation approach 4. Testing strategy 5. Security measures 6. Performance optimization 7. Error handling standards 8. Rate limiting and throttling Use appropriate format for the chosen API style. elicit: true evidence-required: true sections: - id: api-design-principles title: API Design Principles template: | **Design Philosophy:** {{api_philosophy}} **Versioning Strategy:** {{versioning_approach}} **Documentation Standard:** {{doc_standard}} **Testing Coverage Target:** {{coverage_target}} **Performance SLA:** {{performance_sla}} - id: rest-api title: REST API Specification condition: API style is REST type: code language: yaml template: | openapi: 3.0.0 info: title: {{api_title}} version: {{api_version}} description: {{api_description}} contact: name: {{api_contact}} email: {{api_email}} license: name: {{license}} servers: - url: {{server_url}} description: {{server_description}} security: - bearerAuth: [] - apiKey: [] paths: {{api_paths}} components: schemas: {{api_schemas}} securitySchemes: {{security_schemes}} - id: graphql-api title: GraphQL Schema condition: API style is GraphQL type: code language: graphql template: | # GraphQL Schema with Federation Support {{graphql_schema}} - id: grpc-api title: gRPC Service Definitions condition: API style is gRPC type: code language: protobuf template: | // Protocol Buffer Definitions {{proto_definitions}} - id: api-gateway title: API Gateway Configuration template: | **Gateway Solution:** {{gateway_solution}} **Rate Limiting:** {{rate_limit_config}} **Authentication:** {{auth_config}} **CORS Policy:** {{cors_config}} **Caching Strategy:** {{cache_strategy}} **Circuit Breaker:** {{circuit_breaker_config}} **Request/Response Transform:** {{transform_config}} - id: integration-architecture title: Integration Architecture instruction: | VC-SYS Enhancement: Comprehensive integration patterns and anti-corruption layers. Define integration architecture for all external systems: 1. Integration patterns and protocols 2. Anti-corruption layers 3. Data mapping and transformation 4. Error handling and recovery 5. Monitoring and alerting elicit: true sections: - id: integration-patterns title: Integration Patterns repeatable: true template: | **Pattern:** {{pattern_name}} **Use Case:** {{use_case}} **Implementation:** {{implementation_approach}} **Error Handling:** {{error_strategy}} **Monitoring:** {{monitoring_approach}} - id: anti-corruption-layer title: Anti-Corruption Layer template: | **Purpose:** {{acl_purpose}} **Translation Strategy:** {{translation_approach}} **Validation Rules:** {{validation_rules}} **Mapping Tables:** {{mapping_configuration}} **Versioning:** {{version_strategy}} - id: security-architecture title: Security Architecture instruction: | VC-SYS Enhancement: Comprehensive security architecture with threat modeling. Define complete security architecture: 1. Threat model and risk assessment 2. Security controls and measures 3. Authentication and authorization 4. Data protection and encryption 5. Security monitoring and incident response 6. Compliance requirements elicit: true evidence-required: true sections: - id: threat-model title: Threat Model sections: - id: threat-diagram title: Threat Model Diagram type: mermaid mermaid_type: graph template: "{{threat_model_diagram}}" - id: threat-analysis title: Threat Analysis type: table columns: [Threat, Impact, Likelihood, Risk Level, Mitigation] template: "{{threat_table}}" - id: security-controls title: Security Controls template: | **Network Security:** - Firewall Rules: {{firewall_config}} - VPC/Network Segmentation: {{network_segmentation}} - DDoS Protection: {{ddos_protection}} **Application Security:** - Input Validation: {{input_validation}} - Output Encoding: {{output_encoding}} - Session Management: {{session_management}} **Data Security:** - Encryption at Rest: {{encryption_at_rest}} - Encryption in Transit: {{encryption_in_transit}} - Key Management: {{key_management}} **Identity & Access:** - Authentication: {{auth_implementation}} - Authorization: {{authz_implementation}} - MFA Requirements: {{mfa_policy}} - id: compliance-requirements title: Compliance Requirements template: | **Regulatory Compliance:** - GDPR: {{gdpr_requirements}} - CCPA: {{ccpa_requirements}} - HIPAA: {{hipaa_requirements}} - SOC2: {{soc2_requirements}} **Security Standards:** - OWASP Top 10: {{owasp_coverage}} - CIS Controls: {{cis_controls}} - NIST Framework: {{nist_alignment}} - id: performance-architecture title: Performance Architecture instruction: | VC-SYS Enhancement: Performance architecture with benchmarking and optimization strategies. Define performance requirements and optimization strategies: 1. Performance targets and SLAs 2. Caching strategies 3. Load balancing and scaling 4. Performance testing approach 5. Optimization techniques 6. Monitoring and alerting elicit: true evidence-required: true sections: - id: performance-targets title: Performance Targets template: | **Response Time SLAs:** - API Response (p50): {{p50_target}}ms - API Response (p95): {{p95_target}}ms - API Response (p99): {{p99_target}}ms - Page Load Time: {{page_load_target}}s - Time to Interactive: {{tti_target}}s **Throughput Targets:** - Requests per Second: {{rps_target}} - Concurrent Users: {{concurrent_users}} - Data Processing: {{data_throughput}} **Resource Targets:** - CPU Utilization: <{{cpu_target}}% - Memory Usage: <{{memory_target}}% - Error Rate: <{{error_rate_target}}% - id: caching-architecture title: Caching Architecture sections: - id: caching-layers title: Caching Layers type: mermaid mermaid_type: graph template: "{{caching_diagram}}" - id: cache-strategies title: Cache Strategies template: | **CDN Caching:** - Provider: {{cdn_provider}} - Cache Rules: {{cdn_rules}} - TTL Strategy: {{cdn_ttl}} **Application Caching:** - Cache Store: {{app_cache}} - Invalidation Strategy: {{cache_invalidation}} - Cache Warming: {{cache_warming}} **Database Caching:** - Query Cache: {{query_cache}} - Result Set Cache: {{result_cache}} - Connection Pooling: {{connection_pool}} - id: scaling-strategy title: Scaling Strategy template: | **Horizontal Scaling:** - Auto-scaling Triggers: {{scaling_triggers}} - Min/Max Instances: {{instance_limits}} - Scale-out Strategy: {{scaleout_approach}} **Vertical Scaling:** - Resource Limits: {{resource_limits}} - Upgrade Path: {{upgrade_strategy}} **Database Scaling:** - Read Replicas: {{read_replica_strategy}} - Sharding Strategy: {{sharding_approach}} - Connection Pooling: {{pool_configuration}} - id: observability-architecture title: Observability Architecture instruction: | VC-SYS Enhancement: Comprehensive observability with monitoring, logging, tracing, and alerting. Define observability strategy: 1. Monitoring and metrics 2. Centralized logging 3. Distributed tracing 4. Alerting and escalation 5. Dashboards and visualization 6. Incident response elicit: true sections: - id: observability-stack title: Observability Stack template: | **Metrics:** - Collection: {{metrics_collector}} - Storage: {{metrics_storage}} - Visualization: {{metrics_visualization}} **Logging:** - Aggregation: {{log_aggregator}} - Storage: {{log_storage}} - Analysis: {{log_analysis}} **Tracing:** - Implementation: {{tracing_implementation}} - Sampling Strategy: {{sampling_strategy}} - Storage: {{trace_storage}} **APM:** - Platform: {{apm_platform}} - Coverage: {{apm_coverage}} - Custom Metrics: {{custom_metrics}} - id: monitoring-architecture title: Monitoring Architecture type: mermaid mermaid_type: graph template: "{{monitoring_diagram}}" - id: alerting-strategy title: Alerting Strategy template: | **Alert Levels:** - Critical: {{critical_alerts}} - Warning: {{warning_alerts}} - Info: {{info_alerts}} **Escalation Policy:** - Level 1: {{l1_escalation}} - Level 2: {{l2_escalation}} - Level 3: {{l3_escalation}} **Alert Channels:** - Primary: {{primary_channel}} - Secondary: {{secondary_channel}} - Emergency: {{emergency_channel}} - id: frontend-architecture title: Frontend Architecture instruction: | VC-SYS Enhancement: Enhanced frontend architecture with performance optimization and accessibility. Define frontend-specific architecture details with focus on: 1. Component architecture and design system 2. State management patterns 3. Performance optimization 4. Accessibility standards 5. Progressive enhancement 6. SEO optimization elicit: true sections: - id: component-architecture title: Component Architecture instruction: Define component organization and patterns based on chosen framework. sections: - id: design-system title: Design System template: | **Design Tokens:** - Colors: {{color_system}} - Typography: {{typography_system}} - Spacing: {{spacing_system}} - Breakpoints: {{breakpoint_system}} **Component Library:** - Atomic Components: {{atomic_components}} - Composite Components: {{composite_components}} - Layout Components: {{layout_components}} **Accessibility Standards:** - WCAG Level: {{wcag_level}} - Screen Reader Support: {{sr_support}} - Keyboard Navigation: {{keyboard_nav}} - id: component-organization title: Component Organization type: code language: text template: "{{component_structure}}" - id: component-template title: Component Template type: code language: typescript template: "{{component_template}}" - id: frontend-performance title: Frontend Performance template: | **Bundle Optimization:** - Code Splitting: {{code_splitting_strategy}} - Tree Shaking: {{tree_shaking}} - Lazy Loading: {{lazy_loading}} - Bundle Size Budget: {{bundle_budget}} **Rendering Optimization:** - SSR/SSG Strategy: {{ssr_strategy}} - Hydration: {{hydration_approach}} - Virtual DOM: {{vdom_optimization}} **Asset Optimization:** - Image Optimization: {{image_strategy}} - Font Loading: {{font_strategy}} - CSS Strategy: {{css_optimization}} **Core Web Vitals:** - LCP Target: {{lcp_target}} - FID Target: {{fid_target}} - CLS Target: {{cls_target}} - id: backend-architecture title: Backend Architecture instruction: | VC-SYS Enhancement: Enhanced backend architecture with microservices patterns and event-driven architecture. Define backend-specific architecture details with focus on: 1. Service architecture and boundaries 2. Domain-driven design 3. Event-driven patterns 4. Database architecture 5. Background processing 6. API design elicit: true sections: - id: service-architecture title: Service Architecture instruction: Based on platform choice, define service organization. sections: - id: domain-boundaries title: Domain Boundaries type: mermaid mermaid_type: graph template: "{{domain_diagram}}" - id: service-communication title: Service Communication template: | **Synchronous Communication:** - Protocol: {{sync_protocol}} - Service Discovery: {{service_discovery}} - Load Balancing: {{load_balancing}} **Asynchronous Communication:** - Message Bus: {{message_bus}} - Event Store: {{event_store}} - Pub/Sub Pattern: {{pubsub_implementation}} **Service Mesh:** - Implementation: {{service_mesh}} - Traffic Management: {{traffic_management}} - Security Policies: {{mesh_security}} - id: event-driven-architecture title: Event-Driven Architecture sections: - id: event-flow title: Event Flow type: mermaid mermaid_type: sequence template: "{{event_flow_diagram}}" - id: event-schemas title: Event Schemas type: code language: typescript template: "{{event_schemas}}" - id: event-sourcing title: Event Sourcing template: | **Event Store:** {{event_store_implementation}} **Projection Strategy:** {{projection_strategy}} **Snapshot Policy:** {{snapshot_policy}} **Replay Strategy:** {{replay_strategy}} - id: devops-architecture title: DevOps Architecture instruction: | VC-SYS Enhancement: Comprehensive DevOps architecture with CI/CD, infrastructure as code, and GitOps. Define DevOps practices and automation: 1. CI/CD pipelines 2. Infrastructure as Code 3. GitOps workflows 4. Environment management 5. Release management 6. Disaster recovery elicit: true evidence-required: true sections: - id: cicd-architecture title: CI/CD Architecture sections: - id: pipeline-stages title: Pipeline Stages type: mermaid mermaid_type: graph template: "{{pipeline_diagram}}" - id: pipeline-configuration title: Pipeline Configuration type: code language: yaml template: "{{pipeline_config}}" - id: infrastructure-as-code title: Infrastructure as Code template: | **IaC Tool:** {{iac_tool}} **Repository Structure:** {{iac_structure}} **Module Strategy:** {{module_approach}} **State Management:** {{state_management}} **Secret Management:** {{secret_management}} - id: gitops-workflow title: GitOps Workflow template: | **GitOps Tool:** {{gitops_tool}} **Repository Strategy:** {{repo_strategy}} **Sync Policy:** {{sync_policy}} **Rollback Strategy:** {{rollback_approach}} **Progressive Delivery:** {{progressive_delivery}} - id: disaster-recovery title: Disaster Recovery template: | **Backup Strategy:** - Frequency: {{backup_frequency}} - Retention: {{backup_retention}} - Testing: {{backup_testing}} **Recovery Targets:** - RTO: {{rto_target}} - RPO: {{rpo_target}} - MTTR: {{mttr_target}} **Failover Strategy:** - Primary Region: {{primary_region}} - Secondary Region: {{secondary_region}} - Failover Time: {{failover_time}} - id: unified-project-structure title: Unified Project Structure instruction: | VC-SYS Enhancement: Enhanced project structure with clear separation of concerns and tooling integration. Create a monorepo structure that accommodates: - Frontend and backend applications - Shared libraries and utilities - Infrastructure as code - Testing suites - Documentation - CI/CD configuration elicit: true type: code language: plaintext template: | {{project-name}}/ ├── .github/ # CI/CD workflows │ ├── workflows/ │ │ ├── ci.yaml # Continuous Integration │ │ ├── cd.yaml # Continuous Deployment │ │ ├── security.yaml # Security scanning │ │ └── performance.yaml # Performance testing │ └── CODEOWNERS ├── .vscode/ # IDE configuration │ ├── settings.json │ ├── extensions.json │ └── launch.json ├── apps/ # Application packages │ ├── web/ # Frontend application │ │ ├── src/ │ │ │ ├── components/ # UI components │ │ │ │ ├── atoms/ # Atomic components │ │ │ │ ├── molecules/ # Composite components │ │ │ │ └── organisms/ # Complex components │ │ │ ├── pages/ # Page components/routes │ │ │ ├── hooks/ # Custom React hooks │ │ │ ├── services/ # API client services │ │ │ ├── stores/ # State management │ │ │ ├── styles/ # Global styles/themes │ │ │ ├── utils/ # Frontend utilities │ │ │ └── types/ # TypeScript types │ │ ├── public/ # Static assets │ │ ├── tests/ # Frontend tests │ │ │ ├── unit/ │ │ │ ├── integration/ │ │ │ └── e2e/ │ │ └── package.json │ ├── api/ # Backend application │ │ ├── src/ │ │ │ ├── routes/ # API routes/controllers │ │ │ ├── services/ # Business logic │ │ │ ├── models/ # Data models │ │ │ ├── repositories/ # Data access layer │ │ │ ├── middleware/ # Express/API middleware │ │ │ ├── events/ # Event handlers │ │ │ ├── jobs/ # Background jobs │ │ │ ├── utils/ # Backend utilities │ │ │ └── {{serverless_or_server_entry}} │ │ ├── tests/ # Backend tests │ │ │ ├── unit/ │ │ │ ├── integration/ │ │ │ └── contract/ │ │ └── package.json │ └── mobile/ # Mobile application (if applicable) ├── packages/ # Shared packages │ ├── shared/ # Shared types/utilities │ │ ├── src/ │ │ │ ├── types/ # TypeScript interfaces │ │ │ ├── constants/ # Shared constants │ │ │ ├── validators/ # Validation schemas │ │ │ └── utils/ # Shared utilities │ │ └── package.json │ ├── ui/ # Shared UI components │ │ ├── src/ │ │ │ └── components/ │ │ ├── stories/ # Storybook stories │ │ └── package.json │ ├── database/ # Database migrations/seeds │ │ ├── migrations/ │ │ ├── seeds/ │ │ └── package.json │ └── config/ # Shared configuration │ ├── eslint/ │ ├── typescript/ │ ├── jest/ │ └── prettier/ ├── infrastructure/ # IaC definitions │ ├── terraform/ # or CDK/Pulumi │ │ ├── modules/ │ │ ├── environments/ │ │ └── {{iac_structure}} │ └── kubernetes/ # K8s manifests (if applicable) │ ├── base/ │ └── overlays/ ├── scripts/ # Build/deploy scripts │ ├── setup.sh │ ├── build.sh │ ├── deploy.sh │ └── test.sh ├── docs/ # Documentation │ ├── architecture/ │ │ ├── decisions/ # ADRs │ │ └── diagrams/ │ ├── api/ # API documentation │ ├── guides/ # Developer guides │ ├── prd.md │ ├── front-end-spec.md │ └── fullstack-architecture.md ├── tools/ # Development tools │ ├── generators/ # Code generators │ ├── scripts/ # Utility scripts │ └── hooks/ # Git hooks ├── .env.example # Environment template ├── .gitignore ├── package.json # Root package.json ├── {{monorepo_config}} # Monorepo configuration ├── docker-compose.yml # Local development └── README.md - id: development-workflow title: Development Workflow instruction: | VC-SYS Enhancement: Enhanced development workflow with automation and quality gates. Define the development setup and workflow for the fullstack application. elicit: true sections: - id: local-setup title: Local Development Setup sections: - id: prerequisites title: Prerequisites type: code language: bash template: | # System requirements {{system_requirements}} # Tool versions {{tool_versions}} # Installation commands {{installation_commands}} - id: initial-setup title: Initial Setup type: code language: bash template: | # Clone repository {{clone_command}} # Install dependencies {{install_dependencies}} # Setup environment {{setup_environment}} # Database setup {{database_setup}} # Seed data {{seed_data}} - id: dev-commands title: Development Commands type: code language: bash template: | # Start all services {{start_all_command}} # Start frontend only {{start_frontend_command}} # Start backend only {{start_backend_command}} # Run tests {{test_commands}} # Code quality checks {{quality_commands}} # Performance tests {{perf_test_commands}} - id: development-standards title: Development Standards template: | **Code Quality Gates:** - Linting: {{linting_rules}} - Formatting: {{formatting_rules}} - Type Checking: {{type_checking}} - Test Coverage: {{coverage_requirements}} - Security Scanning: {{security_scanning}} **Commit Standards:** - Message Format: {{commit_format}} - Pre-commit Hooks: {{precommit_hooks}} - Branch Naming: {{branch_naming}} **Review Standards:** - PR Template: {{pr_template}} - Review Checklist: {{review_checklist}} - Approval Requirements: {{approval_policy}} - id: testing-strategy title: Testing Strategy instruction: | VC-SYS Enhancement: Comprehensive testing strategy with performance and security testing. Define comprehensive testing approach for fullstack application including: 1. Unit testing 2. Integration testing 3. End-to-end testing 4. Performance testing 5. Security testing 6. Accessibility testing 7. Visual regression testing elicit: true evidence-required: true sections: - id: testing-pyramid title: Testing Pyramid type: mermaid mermaid_type: graph template: | graph TB E2E[E2E Tests - 10%] INT[Integration Tests - 20%] CONTRACT[Contract Tests - 20%] UNIT[Unit Tests - 50%] UNIT --> CONTRACT CONTRACT --> INT INT --> E2E - id: test-coverage-targets title: Test Coverage Targets template: | **Coverage Requirements:** - Unit Tests: {{unit_coverage}}% - Integration Tests: {{integration_coverage}}% - E2E Critical Paths: {{e2e_coverage}}% - Overall Coverage: {{overall_coverage}}% **Performance Testing:** - Load Testing: {{load_test_target}} - Stress Testing: {{stress_test_target}} - Endurance Testing: {{endurance_test_target}} **Security Testing:** - SAST Coverage: {{sast_coverage}}% - DAST Coverage: {{dast_coverage}}% - Dependency Scanning: {{dep_scan_frequency}} - id: test-automation title: Test Automation Strategy template: | **Continuous Testing:** - On Commit: {{commit_tests}} - On PR: {{pr_tests}} - Nightly: {{nightly_tests}} - Release: {{release_tests}} **Test Data Management:** - Fixtures: {{fixture_strategy}} - Mocks: {{mock_strategy}} - Test Database: {{test_db_strategy}} - Synthetic Data: {{synthetic_data}} - id: cost-optimization title: Cost Optimization instruction: | VC-SYS Enhancement: Cost optimization strategies and monitoring. Define cost optimization approach: 1. Resource optimization 2. Cost monitoring 3. Budget alerts 4. Optimization strategies elicit: true sections: - id: cost-projections title: Cost Projections type: table columns: [Component, Monthly Cost, Annual Cost, Optimization] template: "{{cost_table}}" - id: optimization-strategies title: Optimization Strategies template: | **Compute Optimization:** - Right-sizing: {{rightsizing_approach}} - Spot/Preemptible: {{spot_strategy}} - Reserved Instances: {{reserved_strategy}} **Storage Optimization:** - Tiering: {{storage_tiering}} - Compression: {{compression_strategy}} - Archival: {{archival_policy}} **Network Optimization:** - CDN Usage: {{cdn_optimization}} - Data Transfer: {{transfer_optimization}} - Regional Strategy: {{regional_strategy}} - id: migration-strategy title: Migration and Rollout Strategy instruction: | VC-SYS Enhancement: Phased migration and rollout strategy. Define migration approach if replacing existing system: 1. Migration phases 2. Data migration 3. Rollout strategy 4. Rollback procedures 5. Success criteria elicit: true sections: - id: migration-phases title: Migration Phases type: table columns: [Phase, Description, Duration, Success Criteria] template: "{{migration_table}}" - id: rollout-strategy title: Rollout Strategy template: | **Deployment Strategy:** {{deployment_strategy}} **Feature Flags:** {{feature_flag_approach}} **Canary Releases:** {{canary_strategy}} **Blue-Green Deployment:** {{blue_green_approach}} **Rollback Triggers:** {{rollback_triggers}} - id: operational-runbook title: Operational Runbook instruction: | VC-SYS Enhancement: Comprehensive operational runbook for production support. Create operational documentation: 1. Common operations 2. Troubleshooting guides 3. Emergency procedures 4. Maintenance windows 5. Contact information elicit: true sections: - id: common-operations title: Common Operations repeatable: true template: | **Operation:** {{operation_name}} **Frequency:** {{frequency}} **Procedure:** {{procedure}} **Validation:** {{validation_steps}} **Rollback:** {{rollback_procedure}} - id: incident-response title: Incident Response template: | **Severity Levels:** - P1 (Critical): {{p1_definition}} - P2 (High): {{p2_definition}} - P3 (Medium): {{p3_definition}} - P4 (Low): {{p4_definition}} **Response Times:** - P1: {{p1_response}} - P2: {{p2_response}} - P3: {{p3_response}} - P4: {{p4_response}} **Escalation Path:** {{escalation_matrix}} - id: documentation-strategy title: Documentation Strategy instruction: | VC-SYS Enhancement: Living documentation strategy. Define documentation approach: 1. Documentation types 2. Maintenance strategy 3. Generation automation 4. Version control elicit: true sections: - id: documentation-types title: Documentation Types template: | **Technical Documentation:** - Architecture Decisions (ADRs): {{adr_approach}} - API Documentation: {{api_doc_approach}} - Code Documentation: {{code_doc_approach}} **User Documentation:** - User Guides: {{user_guide_approach}} - Admin Guides: {{admin_guide_approach}} - Troubleshooting Guides: {{troubleshooting_approach}} **Process Documentation:** - Runbooks: {{runbook_approach}} - Playbooks: {{playbook_approach}} - SOPs: {{sop_approach}} - id: success-metrics title: Success Metrics instruction: | VC-SYS Enhancement: Define measurable success criteria. Establish success metrics: 1. Technical metrics 2. Business metrics 3. User experience metrics 4. Operational metrics elicit: true evidence-required: true sections: - id: technical-metrics title: Technical Metrics template: | **Performance Metrics:** - Response Time: {{response_metric}} - Throughput: {{throughput_metric}} - Error Rate: {{error_metric}} **Quality Metrics:** - Code Coverage: {{coverage_metric}} - Bug Density: {{bug_metric}} - Technical Debt: {{debt_metric}} - id: business-metrics title: Business Metrics template: | **Adoption Metrics:** - User Growth: {{growth_metric}} - Feature Adoption: {{adoption_metric}} - Retention Rate: {{retention_metric}} **Value Metrics:** - Cost per Transaction: {{cost_metric}} - Revenue Impact: {{revenue_metric}} - ROI: {{roi_metric}} - id: checklist-results title: Checklist Results Report instruction: | Before running the checklist, offer to output the full architecture document. Once user confirms, execute the architect-checklist and populate results here. VC-SYS Enhancement: Include evidence validation and quality scores. sections: - id: validation-results title: Validation Results template: | **Architecture Completeness:** {{completeness_score}}% **Evidence Coverage:** {{evidence_score}}% **Security Assessment:** {{security_score}}% **Performance Readiness:** {{performance_score}}% **Operational Readiness:** {{operational_score}}% - id: recommendations title: Recommendations repeatable: true template: | **Area:** {{improvement_area}} **Current State:** {{current_state}} **Recommendation:** {{recommendation}} **Priority:** {{priority}} **Evidence:** {{supporting_evidence}}