BMAD-METHOD/expansion-packs/bmad-javascript-fullstack/checklists/architecture-review-checklist.md

Architecture Review Checklist

Document Completeness

Executive Summary

• System Overview - Clear 2-3 paragraph description of the system
• Technology Stack - All major technologies listed with versions
• Architecture Pattern - Pattern identified (monolith, microservices, serverless, JAMstack)
• Key Design Decisions - 3-5 major decisions documented with rationale
• Scalability Overview - High-level scalability approach described

Frontend Architecture

• Framework Choice - React, Vue, or other with version and justification
• Build Tool - Vite, Next.js, or Webpack with configuration approach
• State Management - Clear strategy (React Query, Zustand, Redux, Context)
• Routing - Client-side vs server-side routing explained
• Styling Approach - CSS solution chosen (Tailwind, CSS Modules, Styled Components)
• Component Structure - Folder structure and component organization defined
• Code Splitting - Strategy for bundle optimization
• SEO Strategy - SSR, SSG, or CSR approach with reasoning

Backend Architecture

• Runtime and Framework - Node.js version and framework (Express, Fastify, NestJS)
• API Design - REST, GraphQL, or tRPC with endpoint organization
• Authentication - Strategy defined (JWT, OAuth, session-based)
• Authorization - RBAC, ABAC, or other approach
• Middleware Stack - Security, logging, error handling middleware
• Background Jobs - Queue system if needed (Bull, BullMQ)
• File Uploads - Strategy for handling file uploads
• Email System - Email sending approach (SendGrid, SES, SMTP)

Database Design

• Database Choice - SQL vs NoSQL with justification
• Schema Design - Entity relationships documented
• Indexes - Key indexes identified for performance
• Migrations - Migration strategy defined
• Seeding - Data seeding approach for development
• Backup Strategy - Backup frequency and retention
• Connection Pooling - Connection management strategy

API Design

• Versioning Strategy - URL-based, header-based, or other
• Request/Response Format - JSON schema or GraphQL schema
• Error Handling - Standardized error response format
• Pagination - Cursor-based or offset-based approach
• Rate Limiting - Rate limit strategy and thresholds
• CORS Configuration - Allowed origins and methods
• API Documentation - OpenAPI/Swagger or other documentation

TypeScript Configuration

• Strict Mode - Strict TypeScript settings justified
• Path Aliases - Import aliases configured (@/, ~/)
• Type Definitions - Strategy for third-party type definitions
• Shared Types - Location of shared types between frontend/backend

Non-Functional Requirements

Performance

• Performance Targets - Specific metrics defined (Lighthouse score, API latency)
• Caching Strategy - Redis, CDN, or in-memory caching approach
• Database Optimization - Query optimization and indexing plan
• Asset Optimization - Image optimization, lazy loading strategy
• Bundle Size - Target bundle sizes and code splitting approach

Security

• Authentication Security - Token expiration, refresh strategy
• Authorization Checks - Where and how authorization is enforced
• Input Validation - Validation on both frontend and backend
• SQL Injection Prevention - Parameterized queries or ORM usage
• XSS Prevention - Content Security Policy and sanitization
• CSRF Protection - Token-based CSRF protection
• Secrets Management - Environment variables and secret storage
• HTTPS Enforcement - SSL/TLS configuration
• Security Headers - Helmet.js or equivalent configuration
• Dependency Scanning - npm audit or Snyk integration

Scalability

• Horizontal Scaling - Stateless application design
• Database Scaling - Read replicas or sharding strategy
• Caching Layer - Cache invalidation strategy
• CDN Usage - Static asset delivery via CDN
• Load Balancing - Load balancer configuration if needed
• Auto-scaling - Metrics and triggers for scaling

Reliability

• Error Handling - Global error handling strategy
• Logging Strategy - Structured logging with correlation IDs
• Monitoring - APM and error tracking tools (Sentry, Datadog)
• Health Checks - Liveness and readiness endpoints
• Graceful Shutdown - Proper cleanup on application shutdown
• Database Migrations - Zero-downtime migration strategy
• Rollback Plan - How to rollback failed deployments

DevOps & Deployment

• CI/CD Pipeline - Build, test, and deploy automation
• Environment Strategy - Development, staging, production environments
• Infrastructure as Code - Terraform, CloudFormation, or Docker Compose
• Container Strategy - Docker configuration and orchestration
• Deployment Strategy - Blue-green, canary, or rolling deployments
• Backup and Disaster Recovery - RTO and RPO defined

Implementation Readiness

Development Environment

• Local Setup - Clear README with setup instructions
• Environment Variables - .env.example file with all required variables
• Database Setup - Local database setup instructions
• Seed Data - Development seed data available
• Hot Reload - Development server with hot module replacement

Code Quality

• Linting - ESLint configuration defined
• Formatting - Prettier configuration
• Pre-commit Hooks - Husky or lint-staged configuration
• Code Style Guide - Naming conventions and patterns documented
• TypeScript Standards - Type usage guidelines

Testing Strategy

• Unit Testing - Framework chosen (Jest, Vitest)
• Integration Testing - API testing approach (Supertest)
• E2E Testing - E2E framework (Playwright, Cypress)
• Coverage Goals - Target code coverage percentages
• CI Integration - Tests run in CI pipeline

Documentation

• Architecture Diagrams - System architecture visualized
• Database Schema - ER diagram or schema documentation
• API Documentation - Endpoint documentation (Swagger, GraphQL introspection)
• Deployment Guide - How to deploy to production
• ADRs - Architecture Decision Records for key choices

Risk Assessment

Technical Risks

• Complexity Risks - Over-engineering or under-engineering identified
• Performance Bottlenecks - Potential bottlenecks documented
• Scalability Limits - Known scalability constraints
• Technology Risks - Unproven or bleeding-edge tech flagged
• Dependency Risks - Critical third-party dependencies assessed

Mitigation Strategies

• Risk Mitigation - Plan for each identified risk
• Fallback Options - Alternative approaches documented
• Monitoring Plan - How risks will be monitored in production

Validation Questions

Alignment with Requirements

• Requirements Coverage - All functional requirements addressed
• Non-functional Requirements - Performance, security, scalability covered
• Scope Appropriateness - Architecture matches project scope
• Over-engineering Check - Not adding unnecessary complexity
• Future-proofing - Extensible without being over-architected

Team Capability

• Team Skills - Team has or can acquire necessary skills
• Learning Curve - New technologies have acceptable learning curve
• Support Resources - Documentation and community support available
• Maintenance Burden - Architecture is maintainable long-term

Cost Considerations

• Infrastructure Costs - Estimated monthly costs
• Development Costs - Time and effort realistic
• Third-party Services - External service costs budgeted
• Scaling Costs - Cost implications of scaling understood

Final Assessment

Architecture Quality Rating: ⭐⭐⭐⭐⭐

Ready for Implementation: [ ] Yes [ ] No

Critical Issues to Address: List any must-fix issues before development begins

Recommendations: Suggestions for improvement or alternative approaches

Next Steps: What needs to happen before story creation begins