Conduct systematic architecture design reviews to validate system design, assess quality attributes, evaluate technology choices, and identify risks before implementation.
Review Process
Follow this structured approach for comprehensive architecture reviews:
1. Gather Architecture Documentation
Collect required materials:
Required Documents:
- Architecture diagrams (C4: Context, Container, Component)
- Architecture Decision Records (ADRs) with rationale and alternatives
- Technical specifications and non-functional requirements (performance, scalability, security)
- Data models, schemas, and API specifications
- Technology stack with justifications
- Deployment and infrastructure diagrams
Context Information:
- Business constraints (budget, timeline, compliance requirements)
- Performance targets (quantified: response time, throughput)
- Scalability goals (user growth, data volume projections)
- Security requirements (authentication model, data protection, compliance)
- Integration requirements (internal/external systems, APIs)
2. Assess Architecture Style and Patterns
Validate architecture style appropriateness:
Style-Requirement Fit:
- Monolithic: Small teams (<10), simple domains, <1000 users
- Microservices: Large teams (>20), complex domains, >100K users
- Serverless: Event-driven, variable load, stateless operations
- Event-Driven: Asynchronous workflows, loose coupling, high throughput
Pattern Assessment:
☐ Architecture style matches requirements (scale, team, complexity)
☐ Service boundaries align with business domains (DDD)
☐ Communication patterns appropriate (sync vs async)
☐ Data management strategy clear (per-service vs shared DB)
☐ Integration patterns documented (gateway, mesh, events)
☐ Deployment model specified (containers, VMs, serverless)
Anti-Pattern Detection:
- Big Ball of Mud: No structure, tight coupling, shared database
- God Service: Single service handling multiple domains
- Chatty Communication: Excessive inter-service calls (>5/request)
- Distributed Monolith: Services coupled through shared database
- Golden Hammer: Same technology for all problems
3. Evaluate Quality Attributes
Scalability Assessment:
- Horizontal scaling: Load balancers, stateless services, auto-scaling
- Database scaling: Sharding, read replicas, caching layers
- Capacity planning: Current load → projected load (document growth strategy)
- Cost implications: Baseline and peak infrastructure costs
Performance Validation:
- Response time budgets allocated per layer
- Caching strategy (CDN, Redis, application cache)
- Database optimization (indexes, connection pooling, query analysis)
- Async processing for long-running tasks (queues, background jobs)
Security Review:
☐ Authentication mechanism (OAuth 2.0, JWT, SAML)
☐ Authorization model (RBAC, ABAC, policy-based)
☐ API security (rate limiting, input validation, CORS)
☐ Data encryption (at-rest: AES-256, in-transit: TLS 1.3)
☐ Secret management (AWS Secrets Manager, HashiCorp Vault)
☐ Network security (VPC, security groups, WAF)
☐ Security headers (HSTS, CSP, X-Frame-Options)
Availability & Reliability:
- Multi-AZ/region deployment for high availability
- Circuit breakers prevent cascade failures
- Health checks and auto-recovery configured
- Backup/DR procedures (RPO < 1hr, RTO < 4hrs)
- Graceful degradation for non-critical features
4. Review Technology Stack
Technology Fit Validation:
- Backend framework matches use case (Spring Boot, Node.js, Django, Go)
- Database selection justified (PostgreSQL, MongoDB, Cassandra, Redis)
- Deployment platform appropriate (Kubernetes, ECS, Cloud Run)
- Assess alternatives considered and documented in ADRs
Technology Risk Assessment:
- Vendor Lock-in: Evaluate portability and migration complexity
- Team Skills: Document training needs and timeline
- Community Support: Check ecosystem maturity and long-term viability
- Performance: Validate technology meets requirements
- Licensing: Verify compliance with commercial use
5. Analyze Data Architecture
Data Strategy Validation:
- Database per service vs shared database (justify choice)
- SQL vs NoSQL selection with rationale
- Data partitioning and sharding strategy
- Data consistency model (strong vs eventual)
- Data ownership clearly assigned
- Cross-service queries minimized
6. Review Monitoring and Observability
Observability Checklist:
☐ Metrics: Application, infrastructure, business metrics
☐ Logging: Centralized aggregation with correlation IDs
☐ Tracing: Distributed tracing across services
☐ Alerting: Error rate, latency, availability thresholds
☐ Dashboards: Real-time visibility into system health
☐ On-call: Rotation and escalation procedures
7. Generate Review Report
Report Structure:
-
Executive Summary: Architecture style, overall assessment (Approved/Conditional/Not Approved), top strengths and concerns
-
Findings: Organized by severity (Critical/High/Medium/Low) with:
- Description and impact
- Recommendation with effort estimate
- Priority (Must Fix / Should Fix / Consider)
-
Risk Assessment: Technical, resource, timeline, operational risks with mitigations
Finding Format:
Finding: [Clear description]
Severity: Critical | High | Medium | Low
Impact: [Specific consequences]
Recommendation: [Actionable solution]
Effort: [Time estimate]
Priority: Must Fix | Should Fix | Consider
Reference Documentation
Load detailed guidance for specific review areas:
Core Review Resources:
- architecture-review-process.md - Complete review methodology with phase-by-phase checklists
- review-checklists.md - Comprehensive validation checklists for all architecture aspects
- quality-attributes.md - Detailed assessment of scalability, performance, security, reliability, maintainability
- common-patterns-to-validate.md - Validation criteria for architecture patterns (microservices, event-driven, serverless)
- anti-patterns.md - Common design flaws with detection criteria and remediation
- review-report-template.md - Report structure with examples and severity classification
- review-severity-levels.md - Severity classification criteria (Critical/High/Medium/Low)
- best-practices-for-architecture-reviews.md - Review methodology best practices
API & Integration:
- api-design.md - REST, GraphQL, gRPC design assessment
Data Architecture:
- data-management.md - Data strategy, ownership, synchronization, consistency patterns
- data-storage-strategy.md - Database selection, partitioning, replication
- data-consistency.md - Consistency models and trade-offs
- data-scalability.md - Sharding, replication, caching strategies
- database-selection.md - SQL vs NoSQL, technology selection criteria
Security:
- application-security.md - Security architecture including authentication, authorization, encryption, compliance
- authentication-and-authorization.md - Identity and access management patterns
Scalability & Performance:
- horizontal-scalability.md - Horizontal scaling strategies and auto-scaling
- caching-strategy.md - Cache layers, invalidation, CDN
Reliability & Operations:
- high-availability-design.md - HA architecture, redundancy, failover
- fault-tolerance.md - Circuit breakers, retries, bulkheads, timeouts
- disaster-recovery.md - Backup, recovery procedures, RPO/RTO planning
- monitoring-and-observability.md - Metrics, logging, tracing, alerting
Microservices:
- service-boundaries-microservices.md - Service decomposition, bounded contexts, domain boundaries
Additional Topics:
- external-integrations.md - Third-party API integration patterns
- testing-strategy.md - Test coverage, integration testing, contract testing
- operational-readiness.md - Production readiness checklist
- cost-analysis.md - Infrastructure cost estimation and optimization
- infrastructure-costs.md - Detailed cost breakdown by component
- infrastructure.md - Infrastructure design and deployment patterns
- risk-assessment.md - Technical risk identification and mitigation
Note: For technology selection guidance (frameworks, databases, cloud platforms), reference the architecture-design skill.
Critical Review Principles
Focus on Architecture, Not Implementation:
- Review designs and patterns, not code quality
- Validate decisions and trade-offs, not syntax
- Assess structure and boundaries, not variable names
Be Specific with Findings: ✅ "Circuit breaker missing on Order→Payment calls (avg 50 calls/sec). Add Resilience4j with 50% error threshold." ❌ "Need better error handling"
Quantify Performance Requirements: ✅ "API response time must be <200ms for 95th percentile at 1000 req/s" ❌ "API should be fast"
Provide Actionable Recommendations: ✅ "Split UserService into Authentication (identity) and Profile (data) services. Estimated 3-week effort. Use event bus for sync." ❌ "Consider improving service boundaries"
Assess Based on Context:
- Startup MVP has different requirements than enterprise system
- 100-user system doesn't need microservices complexity
- Evaluate appropriateness for scale, team, and timeline