Review Software Architecture

Evaluate software architecture at system level for quality attributes, design principles adherence, long-term maintainability.

When Use

• Evaluating proposed architecture before implementation begins
• Assessing existing system for scalability, maintainability, or security
• Reviewing Architecture Decision Records (ADRs) for project
• Performing technical debt assessment
• Evaluating whether system ready for significant scale-up or feature expansion
• Differentiating from line-level code review (which focuses on PR-level changes)

Inputs

• Required: System codebase or architecture documentation (diagrams, ADRs, README)
• Required: Context about system purpose, scale, constraints
• Optional: Non-functional requirements (latency, throughput, availability targets)
• Optional: Team size and skill composition
• Optional: Technology constraints or preferences
• Optional: Known pain points or areas of concern

Steps

Step 1: Understand System Context

Map system boundaries and interfaces:

## System Context
- **Name**: [System name]
- **Purpose**: [One-line description]
- **Users**: [Who uses it and how]
- **Scale**: [Requests/sec, data volume, user count]
- **Age**: [Years in production, major versions]
- **Team**: [Size, composition]

## External Dependencies
| Dependency | Type | Criticality | Notes |
|-----------|------|-------------|-------|
| PostgreSQL | Database | Critical | Primary data store |
| Redis | Cache | High | Session store + caching |
| Stripe | External API | Critical | Payment processing |
| S3 | Object storage | High | File uploads |

Got: Clear picture of what system does and what it depends on. If fail: Architecture documentation missing? Derive context from code structure, configs, deployment files.

Step 2: Evaluate Structural Quality

Coupling Assessment

Examine how tightly modules depend on each other:

• Dependency direction: Do dependencies flow in one direction (layered) or circular?
• Interface boundaries: Modules connected through defined interfaces/contracts or direct implementation references?
• Shared state: Mutable state shared between modules?
• Database coupling: Multiple services read/write same tables directly?
• Temporal coupling: Must operations happen in specific order without explicit orchestration?

# Detect circular dependencies (JavaScript/TypeScript)
npx madge --circular src/

# Detect import patterns (Python)
# Look for deep cross-package imports
grep -r "from app\." --include="*.py" | sort | uniq -c | sort -rn | head -20

Cohesion Assessment

Evaluate whether each module has single, clear responsibility:

• Module naming: Does name accurately describe what module does?
• File size: Files or classes excessively large (>500 lines suggests multiple responsibilities)?
• Change frequency: Do unrelated features need changes to same module?
• God objects: Classes/modules that everything depends on?

Got: Coupling and cohesion assessed with specific examples from codebase. If fail: Codebase too large for manual review? Sample 3-5 key modules and most-changed files.

Step 3: Assess SOLID Principles

## SOLID Assessment
| Principle | Status | Evidence | Impact |
|-----------|--------|----------|--------|
| SRP | Concern | UserService handles auth, profile, notifications, and billing | High — changes to billing risk breaking auth |
| OCP | Good | Plugin system for payment providers | Low |
| LSP | Good | No type-checking anti-patterns found | Low |
| ISP | Concern | IRepository has 15 methods, most implementors use 3-4 | Medium |
| DIP | Concern | Controllers directly instantiate database repositories | Medium |

Got: Each principle assessed with at least one specific example. If fail: Not all principles apply equally to every architecture style. Note when principle is less relevant (e.g., ISP matters less in functional codebases).

Step 4: Review API Design

For systems that expose APIs (REST, GraphQL, gRPC):

• Consistency: Naming conventions, error formats, pagination patterns uniform
• Versioning: Strategy exists and is applied (URL, header, content negotiation)
• Error handling: Error responses structured, consistent, no leak internals
• Authentication/Authorization: Properly enforced at API layer
• Rate limiting: Protection against abuse
• Documentation: OpenAPI/Swagger, GraphQL schema, or protobuf definitions maintained
• Idempotency: Mutating operations (POST/PUT) handle retries safely

## API Design Review
| Aspect | Status | Notes |
|--------|--------|-------|
| Naming consistency | Good | RESTful resource naming throughout |
| Versioning | Concern | No versioning strategy — breaking changes affect all clients |
| Error format | Good | RFC 7807 Problem Details used consistently |
| Auth | Good | JWT with role-based scopes |
| Rate limiting | Missing | No rate limiting on any endpoint |
| Documentation | Concern | OpenAPI spec exists but 6 months out of date |

Got: API design reviewed against common standards with specific findings. If fail: No API exposed? Skip this step and focus on internal module interfaces.

Step 5: Evaluate Scalability and Reliability

• Statelessness: Can application scale horizontally (no local state)?
• Database scalability: Are queries indexed? Schema suitable for data volume?
• Caching strategy: Caching applied at appropriate layers (database, application, CDN)?
• Failure handling: What happens when dependency unavailable (circuit breaker, retry, fallback)?
• Observability: Logs, metrics, traces implemented?
• Data consistency: Eventual consistency acceptable or strong consistency required?

Got: Scalability and reliability assessed relative to stated non-functional requirements. If fail: Non-functional requirements undocumented? Recommend defining them as first step.

Step 6: Assess Technical Debt

## Technical Debt Inventory
| Item | Severity | Impact | Estimated Effort | Recommendation |
|------|----------|--------|-----------------|----------------|
| No database migrations | High | Schema changes are manual and error-prone | 1 sprint | Adopt Alembic/Flyway |
| Monolithic test suite | Medium | Tests take 45 min, developers skip them | 2 sprints | Split into unit/integration/e2e |
| Hardcoded config values | Medium | Environment-specific values in source code | 1 sprint | Extract to env vars/config service |
| No CI/CD pipeline | High | Manual deployment prone to errors | 1 sprint | Set up GitHub Actions |

Got: Technical debt catalogued with severity, impact, effort estimates. If fail: Debt inventory overwhelming? Prioritize top 5 items by impact/effort ratio.

Step 7: Review Architecture Decision Records (ADRs)

ADRs exist? Evaluate:

• Decisions have clear context (what problem was being solved)
• Alternatives considered and documented
• Trade-offs explicit
• Decisions still current (not superseded without documentation)
• New significant decisions have ADRs

ADRs do not exist? Recommend establishing them for key decisions.

Step 8: Write the Architecture Review

## Architecture Review Report

### Executive Summary
[2-3 sentences: overall health, key concerns, recommended actions]

### Strengths
1. [Specific architectural strength with evidence]
2. ...

### Concerns (by severity)

#### Critical
1. **[Title]**: [Description, impact, recommendation]

#### Major
1. **[Title]**: [Description, impact, recommendation]

#### Minor
1. **[Title]**: [Description, recommendation]

### Technical Debt Summary
[Top 5 debt items with prioritized recommendations]

### Recommended Next Steps
1. [Actionable recommendation with clear scope]
2. ...

Got: Review report actionable with prioritized recommendations. If fail: Review time-boxed? Clearly state what was covered and what remains unassessed.

Checks

• System context documented (purpose, scale, dependencies, team)
• Coupling and cohesion assessed with specific code examples
• SOLID principles evaluated where applicable
• API design reviewed (if applicable)
• Scalability and reliability assessed against requirements
• Technical debt catalogued and prioritized
• ADRs reviewed or their absence noted
• Recommendations specific, prioritized, actionable

Pitfalls

• Review code instead of architecture: This skill is about system-level design, not line-level code quality. Use code-reviewer for PR-level feedback.
• Prescribe specific technology: Architecture reviews should identify problems, not mandate specific tools unless clear technical reason.
• Ignore team context: "Best" architecture for 3-person team differs from 30-person team. Consider organizational constraints.
• Perfectionism: Every system has tech debt. Focus on debt actively causing pain or blocking future work.
• Assume scale: Don't recommend distributed systems for app serving 100 users. Match architecture to actual requirements.

See Also

• security-audit-codebase — security-focused code and configuration review
• configure-git-repository — repository structure and conventions
• design-serialization-schema — data schema design and evolution
• review-data-analysis — review of analytical correctness (complementary perspective)