bmad-method 5.1.3 → 6.0.0-alpha.1

package/src/modules/bmm/workflows/3-solutioning/architecture/architecture-patterns.yaml

@@ -0,0 +1,347 @@
+# Architecture Patterns - Common patterns identified from requirements
+
+requirement_patterns:
+  realtime_collaboration:
+    triggers:
+      - "real-time"
+      - "collaborative"
+      - "live updates"
+      - "multi-user"
+      - "simultaneous editing"
+    decisions_needed:
+      - websocket_solution
+      - conflict_resolution
+      - state_synchronization
+      - presence_tracking
+      - optimistic_updates
+    suggested_stack:
+      - "Socket.io or WebSocket native"
+      - "Redis for pub/sub"
+      - "Operational Transforms or CRDTs for conflict resolution"
+      - "PostgreSQL for persistence"
+
+  ecommerce:
+    triggers:
+      - "shopping cart"
+      - "checkout"
+      - "payments"
+      - "inventory"
+      - "product catalog"
+    decisions_needed:
+      - payment_processor
+      - cart_persistence
+      - inventory_management
+      - order_workflow
+      - tax_calculation
+    suggested_stack:
+      - "Stripe or PayPal for payments"
+      - "PostgreSQL for products and orders"
+      - "Redis for cart sessions"
+      - "BullMQ for order processing"
+
+  saas_platform:
+    triggers:
+      - "multi-tenant"
+      - "subscription"
+      - "billing"
+      - "team management"
+      - "roles and permissions"
+    decisions_needed:
+      - tenancy_model
+      - subscription_billing
+      - permission_system
+      - team_collaboration
+      - usage_tracking
+    suggested_stack:
+      - "PostgreSQL with Row Level Security"
+      - "Stripe Billing for subscriptions"
+      - "RBAC or ABAC for permissions"
+      - "NextAuth or Clerk for auth"
+
+  content_platform:
+    triggers:
+      - "CMS"
+      - "blog"
+      - "publishing"
+      - "content management"
+      - "editorial workflow"
+    decisions_needed:
+      - content_storage
+      - rich_text_editor
+      - media_handling
+      - version_control
+      - publishing_workflow
+    suggested_stack:
+      - "PostgreSQL for structured content"
+      - "S3 or Cloudinary for media"
+      - "Tiptap or Slate for rich text"
+      - "Algolia for search"
+
+  data_analytics:
+    triggers:
+      - "dashboards"
+      - "reporting"
+      - "metrics"
+      - "analytics"
+      - "data visualization"
+    decisions_needed:
+      - data_warehouse
+      - etl_pipeline
+      - visualization_library
+      - query_optimization
+      - caching_strategy
+    suggested_stack:
+      - "PostgreSQL or ClickHouse"
+      - "Apache Airflow or Temporal for ETL"
+      - "Chart.js or D3 for visualization"
+      - "Redis for query caching"
+
+  social_platform:
+    triggers:
+      - "social network"
+      - "feed"
+      - "following"
+      - "likes"
+      - "comments"
+    decisions_needed:
+      - graph_relationships
+      - feed_algorithm
+      - notification_system
+      - content_moderation
+      - privacy_controls
+    suggested_stack:
+      - "PostgreSQL with graph extensions or Neo4j"
+      - "Redis for feed caching"
+      - "Elasticsearch for user search"
+      - "WebSockets for notifications"
+
+  marketplace:
+    triggers:
+      - "marketplace"
+      - "vendors"
+      - "buyers and sellers"
+      - "transactions"
+      - "escrow"
+    decisions_needed:
+      - payment_splitting
+      - escrow_handling
+      - vendor_management
+      - dispute_resolution
+      - commission_model
+    suggested_stack:
+      - "Stripe Connect for payments"
+      - "PostgreSQL for transactions"
+      - "BullMQ for async processing"
+      - "S3 for vendor assets"
+
+  streaming_platform:
+    triggers:
+      - "video streaming"
+      - "live streaming"
+      - "media delivery"
+      - "broadcast"
+    decisions_needed:
+      - video_encoding
+      - cdn_strategy
+      - streaming_protocol
+      - bandwidth_optimization
+      - drm_protection
+    suggested_stack:
+      - "AWS MediaConvert or Mux"
+      - "CloudFront or Fastly CDN"
+      - "HLS or DASH protocol"
+      - "S3 for video storage"
+
+  iot_platform:
+    triggers:
+      - "IoT"
+      - "sensors"
+      - "device management"
+      - "telemetry"
+      - "edge computing"
+    decisions_needed:
+      - message_protocol
+      - time_series_database
+      - device_authentication
+      - data_ingestion
+      - edge_processing
+    suggested_stack:
+      - "MQTT or CoAP protocol"
+      - "TimescaleDB or InfluxDB"
+      - "Apache Kafka for ingestion"
+      - "Grafana for monitoring"
+
+  ai_application:
+    triggers:
+      - "machine learning"
+      - "AI features"
+      - "LLM integration"
+      - "computer vision"
+      - "NLP"
+    decisions_needed:
+      - model_serving
+      - vector_database
+      - prompt_management
+      - token_optimization
+      - fallback_strategy
+    suggested_stack:
+      - "OpenAI or Anthropic API"
+      - "Pinecone or pgvector for embeddings"
+      - "Redis for prompt caching"
+      - "Langchain or LlamaIndex"
+
+# Quality attribute patterns
+quality_attributes:
+  high_availability:
+    triggers:
+      - "99.9% uptime"
+      - "high availability"
+      - "fault tolerance"
+      - "disaster recovery"
+    architectural_needs:
+      - load_balancing
+      - database_replication
+      - health_checks
+      - circuit_breakers
+      - graceful_degradation
+
+  high_performance:
+    triggers:
+      - "millisecond response"
+      - "high throughput"
+      - "low latency"
+      - "performance critical"
+    architectural_needs:
+      - caching_layers
+      - database_optimization
+      - cdn_strategy
+      - code_splitting
+      - lazy_loading
+
+  high_security:
+    triggers:
+      - "compliance"
+      - "HIPAA"
+      - "GDPR"
+      - "financial data"
+      - "PCI DSS"
+    architectural_needs:
+      - encryption_at_rest
+      - encryption_in_transit
+      - audit_logging
+      - access_controls
+      - data_isolation
+
+  scalability:
+    triggers:
+      - "millions of users"
+      - "elastic scale"
+      - "global reach"
+      - "viral growth"
+    architectural_needs:
+      - horizontal_scaling
+      - database_sharding
+      - microservices
+      - queue_systems
+      - auto_scaling
+
+# Integration patterns
+integration_requirements:
+  payment_processing:
+    common_choices:
+      - "Stripe - most developer friendly"
+      - "PayPal - widest consumer adoption"
+      - "Square - best for in-person + online"
+    considerations:
+      - transaction_fees
+      - international_support
+      - subscription_handling
+      - marketplace_capabilities
+
+  email_service:
+    common_choices:
+      - "Resend - modern, developer friendly"
+      - "SendGrid - mature, scalable"
+      - "Amazon SES - cost effective at scale"
+      - "Postmark - transactional focus"
+    considerations:
+      - deliverability
+      - template_management
+      - analytics_needs
+      - cost_per_email
+
+  sms_notifications:
+    common_choices:
+      - "Twilio - most comprehensive"
+      - "Amazon SNS - AWS integrated"
+      - "Vonage - competitive pricing"
+    considerations:
+      - international_coverage
+      - delivery_rates
+      - two_way_messaging
+      - cost_per_message
+
+  authentication_providers:
+    social_providers:
+      - "Google - highest adoption"
+      - "GitHub - developer focused"
+      - "Microsoft - enterprise"
+      - "Apple - iOS users"
+    enterprise_providers:
+      - "SAML 2.0"
+      - "OAuth 2.0"
+      - "OpenID Connect"
+      - "Active Directory"
+
+# Decision heuristics
+decision_rules:
+  database_selection:
+    if_requirements_include:
+      - complex_relationships: "PostgreSQL"
+      - flexible_schema: "MongoDB"
+      - time_series: "TimescaleDB"
+      - graph_data: "Neo4j or PostgreSQL with extensions"
+      - key_value: "Redis"
+      - wide_column: "Cassandra"
+
+  api_pattern_selection:
+    if_requirements_include:
+      - simple_crud: "REST"
+      - complex_queries: "GraphQL"
+      - type_safety_critical: "tRPC"
+      - microservices: "gRPC"
+      - public_api: "REST with OpenAPI"
+
+  deployment_selection:
+    if_requirements_include:
+      - nextjs_only: "Vercel"
+      - complex_infrastructure: "AWS"
+      - quick_prototype: "Railway"
+      - global_edge: "Fly.io"
+      - kubernetes_needed: "GCP or AWS EKS"
+
+# Anti-patterns to avoid
+anti_patterns:
+  overengineering:
+    signs:
+      - "Microservices for < 10k users"
+      - "Kubernetes for single app"
+      - "GraphQL for 5 endpoints"
+      - "Event sourcing for CRUD app"
+    recommendation: "Start simple, evolve as needed"
+
+  underengineering:
+    signs:
+      - "No authentication strategy"
+      - "No error handling plan"
+      - "No monitoring approach"
+      - "No backup strategy"
+    recommendation: "Cover the fundamentals"
+
+  technology_soup:
+    signs:
+      - "5+ different databases"
+      - "Multiple frontend frameworks"
+      - "Inconsistent patterns"
+      - "Too many languages"
+    recommendation: "Maintain consistency"

package/src/modules/bmm/workflows/3-solutioning/architecture/architecture-template.md

@@ -0,0 +1,103 @@
+# Decision Architecture
+
+## Executive Summary
+
+{{executive_summary}}
+
+{{project_initialization_section}}
+
+## Decision Summary
+
+| Category | Decision | Version | Affects Epics | Rationale |
+| -------- | -------- | ------- | ------------- | --------- |
+
+{{decision_table_rows}}
+
+## Project Structure
+
+```
+{{project_root}}/
+{{source_tree}}
+```
+
+## Epic to Architecture Mapping
+
+{{epic_mapping_table}}
+
+## Technology Stack Details
+
+### Core Technologies
+
+{{core_stack_details}}
+
+### Integration Points
+
+{{integration_details}}
+
+{{novel_pattern_designs_section}}
+
+## Implementation Patterns
+
+These patterns ensure consistent implementation across all AI agents:
+
+{{implementation_patterns}}
+
+## Consistency Rules
+
+### Naming Conventions
+
+{{naming_conventions}}
+
+### Code Organization
+
+{{code_organization_patterns}}
+
+### Error Handling
+
+{{error_handling_approach}}
+
+### Logging Strategy
+
+{{logging_approach}}
+
+## Data Architecture
+
+{{data_models_and_relationships}}
+
+## API Contracts
+
+{{api_specifications}}
+
+## Security Architecture
+
+{{security_approach}}
+
+## Performance Considerations
+
+{{performance_strategies}}
+
+## Deployment Architecture
+
+{{deployment_approach}}
+
+## Development Environment
+
+### Prerequisites
+
+{{development_prerequisites}}
+
+### Setup Commands
+
+```bash
+{{setup_commands}}
+```
+
+## Architecture Decision Records (ADRs)
+
+{{key_architecture_decisions}}
+
+---
+
+_Generated by BMAD Decision Architecture Workflow v1.0_
+_Date: {{date}}_
+_For: {{user_name}}_

package/src/modules/bmm/workflows/3-solutioning/architecture/checklist.md

@@ -0,0 +1,244 @@
+# Architecture Document Validation Checklist
+
+**Purpose**: Validate the architecture document itself is complete, implementable, and provides clear guidance for AI agents.
+
+**Note**: This checklist validates the ARCHITECTURE DOCUMENT only. For cross-workflow validation (PRD → Architecture → Stories alignment), use the solutioning-gate-check workflow.
+
+---
+
+## 1. Decision Completeness
+
+### All Decisions Made
+
+- [ ] Every critical decision category has been resolved
+- [ ] All important decision categories addressed
+- [ ] No placeholder text like "TBD", "[choose]", or "{TODO}" remains
+- [ ] Optional decisions either resolved or explicitly deferred with rationale
+
+### Decision Coverage
+
+- [ ] Data persistence approach decided
+- [ ] API pattern chosen
+- [ ] Authentication/authorization strategy defined
+- [ ] Deployment target selected
+- [ ] All functional requirements have architectural support
+
+---
+
+## 2. Version Specificity
+
+### Technology Versions
+
+- [ ] Every technology choice includes a specific version number
+- [ ] Version numbers are current (verified via WebSearch, not hardcoded)
+- [ ] Compatible versions selected (e.g., Node.js version supports chosen packages)
+- [ ] Verification dates noted for version checks
+
+### Version Verification Process
+
+- [ ] WebSearch used during workflow to verify current versions
+- [ ] No hardcoded versions from decision catalog trusted without verification
+- [ ] LTS vs. latest versions considered and documented
+- [ ] Breaking changes between versions noted if relevant
+
+---
+
+## 3. Starter Template Integration (if applicable)
+
+### Template Selection
+
+- [ ] Starter template chosen (or "from scratch" decision documented)
+- [ ] Project initialization command documented with exact flags
+- [ ] Starter template version is current and specified
+- [ ] Command search term provided for verification
+
+### Starter-Provided Decisions
+
+- [ ] Decisions provided by starter marked as "PROVIDED BY STARTER"
+- [ ] List of what starter provides is complete
+- [ ] Remaining decisions (not covered by starter) clearly identified
+- [ ] No duplicate decisions that starter already makes
+
+---
+
+## 4. Novel Pattern Design (if applicable)
+
+### Pattern Detection
+
+- [ ] All unique/novel concepts from PRD identified
+- [ ] Patterns that don't have standard solutions documented
+- [ ] Multi-epic workflows requiring custom design captured
+
+### Pattern Documentation Quality
+
+- [ ] Pattern name and purpose clearly defined
+- [ ] Component interactions specified
+- [ ] Data flow documented (with sequence diagrams if complex)
+- [ ] Implementation guide provided for agents
+- [ ] Edge cases and failure modes considered
+- [ ] States and transitions clearly defined
+
+### Pattern Implementability
+
+- [ ] Pattern is implementable by AI agents with provided guidance
+- [ ] No ambiguous decisions that could be interpreted differently
+- [ ] Clear boundaries between components
+- [ ] Explicit integration points with standard patterns
+
+---
+
+## 5. Implementation Patterns
+
+### Pattern Categories Coverage
+
+- [ ] **Naming Patterns**: API routes, database tables, components, files
+- [ ] **Structure Patterns**: Test organization, component organization, shared utilities
+- [ ] **Format Patterns**: API responses, error formats, date handling
+- [ ] **Communication Patterns**: Events, state updates, inter-component messaging
+- [ ] **Lifecycle Patterns**: Loading states, error recovery, retry logic
+- [ ] **Location Patterns**: URL structure, asset organization, config placement
+- [ ] **Consistency Patterns**: UI date formats, logging, user-facing errors
+
+### Pattern Quality
+
+- [ ] Each pattern has concrete examples
+- [ ] Conventions are unambiguous (agents can't interpret differently)
+- [ ] Patterns cover all technologies in the stack
+- [ ] No gaps where agents would have to guess
+- [ ] Implementation patterns don't conflict with each other
+
+---
+
+## 6. Technology Compatibility
+
+### Stack Coherence
+
+- [ ] Database choice compatible with ORM choice
+- [ ] Frontend framework compatible with deployment target
+- [ ] Authentication solution works with chosen frontend/backend
+- [ ] All API patterns consistent (not mixing REST and GraphQL for same data)
+- [ ] Starter template compatible with additional choices
+
+### Integration Compatibility
+
+- [ ] Third-party services compatible with chosen stack
+- [ ] Real-time solutions (if any) work with deployment target
+- [ ] File storage solution integrates with framework
+- [ ] Background job system compatible with infrastructure
+
+---
+
+## 7. Document Structure
+
+### Required Sections Present
+
+- [ ] Executive summary exists (2-3 sentences maximum)
+- [ ] Project initialization section (if using starter template)
+- [ ] Decision summary table with ALL required columns:
+  - Category
+  - Decision
+  - Version
+  - Rationale
+- [ ] Project structure section shows complete source tree
+- [ ] Implementation patterns section comprehensive
+- [ ] Novel patterns section (if applicable)
+
+### Document Quality
+
+- [ ] Source tree reflects actual technology decisions (not generic)
+- [ ] Technical language used consistently
+- [ ] Tables used instead of prose where appropriate
+- [ ] No unnecessary explanations or justifications
+- [ ] Focused on WHAT and HOW, not WHY (rationale is brief)
+
+---
+
+## 8. AI Agent Clarity
+
+### Clear Guidance for Agents
+
+- [ ] No ambiguous decisions that agents could interpret differently
+- [ ] Clear boundaries between components/modules
+- [ ] Explicit file organization patterns
+- [ ] Defined patterns for common operations (CRUD, auth checks, etc.)
+- [ ] Novel patterns have clear implementation guidance
+- [ ] Document provides clear constraints for agents
+- [ ] No conflicting guidance present
+
+### Implementation Readiness
+
+- [ ] Sufficient detail for agents to implement without guessing
+- [ ] File paths and naming conventions explicit
+- [ ] Integration points clearly defined
+- [ ] Error handling patterns specified
+- [ ] Testing patterns documented
+
+---
+
+## 9. Practical Considerations
+
+### Technology Viability
+
+- [ ] Chosen stack has good documentation and community support
+- [ ] Development environment can be set up with specified versions
+- [ ] No experimental or alpha technologies for critical path
+- [ ] Deployment target supports all chosen technologies
+- [ ] Starter template (if used) is stable and well-maintained
+
+### Scalability
+
+- [ ] Architecture can handle expected user load
+- [ ] Data model supports expected growth
+- [ ] Caching strategy defined if performance is critical
+- [ ] Background job processing defined if async work needed
+- [ ] Novel patterns scalable for production use
+
+---
+
+## 10. Common Issues to Check
+
+### Beginner Protection
+
+- [ ] Not overengineered for actual requirements
+- [ ] Standard patterns used where possible (starter templates leveraged)
+- [ ] Complex technologies justified by specific needs
+- [ ] Maintenance complexity appropriate for team size
+
+### Expert Validation
+
+- [ ] No obvious anti-patterns present
+- [ ] Performance bottlenecks addressed
+- [ ] Security best practices followed
+- [ ] Future migration paths not blocked
+- [ ] Novel patterns follow architectural principles
+
+---
+
+## Validation Summary
+
+### Document Quality Score
+
+- Architecture Completeness: [Complete / Mostly Complete / Partial / Incomplete]
+- Version Specificity: [All Verified / Most Verified / Some Missing / Many Missing]
+- Pattern Clarity: [Crystal Clear / Clear / Somewhat Ambiguous / Ambiguous]
+- AI Agent Readiness: [Ready / Mostly Ready / Needs Work / Not Ready]
+
+### Critical Issues Found
+
+- [ ] Issue 1: **\*\***\_\_\_**\*\***
+- [ ] Issue 2: **\*\***\_\_\_**\*\***
+- [ ] Issue 3: **\*\***\_\_\_**\*\***
+
+### Recommended Actions Before Implementation
+
+1. ***
+2. ***
+3. ***
+
+---
+
+**Next Step**: Run the **solutioning-gate-check** workflow to validate alignment between PRD, Architecture, and Stories before beginning implementation.
+
+---
+
+_This checklist validates architecture document quality only. Use solutioning-gate-check for comprehensive readiness validation._