architecture-design-review

What this skill does

# 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](references/architecture-review-process.md)** - Complete review methodology with phase-by-phase checklists
- **[review-checklists.md](references/review-checklists.md)** - Comprehensive validation checklists for all architecture aspects
- **[quality-attributes.md](references/quality-attributes.md)** - Detailed assessment of scalability, performance, security, reliability, maintainability
- **[common-patterns-to-validate.md](references/common-patterns-to-validate.md)** - Validation criteria for architecture patterns (microservices, event-driven, serverless)
- **[anti-patterns.md](references/anti-patterns.md)** - Common design flaws with detection criteria and remediation
- **[review-report-template.md](references/review-report-template.md)** - Report structure with examples and severity classification
- **[review-severity-levels.md](references/review-severity-levels.md)** - Severity classification criteria (Critical/High/Medium/Low)
- **[best-practices-for-architecture-reviews.md](references/best-practices-for-architecture-reviews.md)** - Review methodology best practices

**API & Integration:**

- **[api-design.md](references/api-design.md)** - REST, GraphQL, gRPC design assessment

**Data Architecture:**

- **[data-management.md](references/data-management.md)** - Data strategy, ownership, synchronization, consistency patterns
- **[data-storage-strategy.md](references/data-storage-strategy.md)** - Database selection, partitioning, replication
- **[data-consistency.md](references/data-consistency.md)** - Consistency models and trade-offs
- **[data-scalability.md](references/data-scalability.md)** - Sharding, replication, caching strategies
- **[database-selection.md](references/database-selection.md)** - SQL vs NoSQL, technology selection criteria

**Security:**

- **[application-security.md](references/application-security.md)** - Security architecture including authentication, authorization, encryption, compliance
- **[authentication-and-authorization.md](references/authentication-and-authorization.md)** - Identity and access management patterns

**Scalability & Performance:**

- **[horizontal-scalability.md](references/horizontal-scalability.md)** - Horizontal scaling strategies and auto-scaling
- **[caching-strategy