Architecture Design Review

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:

1. Executive Summary: Architecture style, overall assessment (Approved/Conditional/Not Approved), top strengths and concerns

2. Findings: Organized by severity (Critical/High/Medium/Low) with:

   • Description and impact
   • Recommendation with effort estimate
   • Priority (Must Fix / Should Fix / Consider)

3. 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