Architecture Review

When to Use

Invoke with /architecture-review when:

• Evaluating overall project structure and organization
• Planning a major refactoring or migration
• Assessing whether the architecture can support planned features
• Onboarding to a codebase and building a mental model
• Due diligence on an inherited or acquired codebase

Process

Phase 1: Map the Architecture

Build a structural overview:

1. Read project config — identify framework, language, dependencies
2. Map directory structure — identify layers, modules, boundaries
3. Identify entry points — servers, CLI handlers, event processors, main functions
4. Trace data flow — request → handler → service → data → response
5. Identify patterns — MVC, Clean Architecture, hexagonal, microservices, monolith

Phase 2: SOLID Principles Check

Evaluate adherence to SOLID (adapted for all paradigms):

Single Responsibility (S)

• Does each module/class/file have one clear reason to change?
• Are there god modules that do everything? (>500 lines, multiple concerns)
• Is business logic mixed with infrastructure? (DB queries in handlers, HTTP in services)

Open/Closed (O)

• Can new features be added without modifying existing code?
• Are extension points available? (plugins, middleware, strategy pattern)
• Is there excessive switch/if-else that grows with each feature?

Liskov Substitution (L)

• Do subtypes/implementations honor the contracts of their interfaces?
• Are there interface implementations that throw "not implemented" errors?
• Do overrides change the expected behavior of base methods?

Interface Segregation (I)

• Are interfaces/type contracts focused and minimal?
• Do consumers depend on methods they don't use?
• Are there "fat" interfaces that force empty implementations?

Dependency Inversion (D)

• Do high-level modules depend on abstractions, not concrete implementations?
• Are external services (DB, cache, API clients) behind interfaces?
• Can infrastructure be swapped without changing business logic?

Phase 3: Module Boundaries & Dependencies

Analyze module health:

• Circular dependencies: modules that import each other (directly or transitively)
• Dependency direction: do dependencies flow inward (toward domain) or outward?
• Coupling: changing one module requires changes in many others
• Cohesion: are related concepts grouped together?
• Public surface: are internal details properly encapsulated?
• Barrel exports: do index/barrel files re-export the right things?

Phase 4: Layer Analysis

Check architectural layering:

• Presentation → Business → Data: is the layering consistent?
• Layer violations: does the presentation layer directly access the database?
• Shared state: is mutable state shared across layers?
• Configuration: is config centralized or scattered across modules?
• Cross-cutting concerns: how are logging, auth, validation handled? (middleware, decorators, aspect-oriented)

Phase 5: Scalability Assessment

Evaluate growth readiness:

• Can the codebase support 10x the current feature set without restructuring?
• Are there single points of failure in the architecture?
• Is there a clear strategy for splitting modules if they grow too large?
• Are there hard-coded limits (max items, timeouts) that should be configurable?

Output Format

# Architecture Review Report

## Architecture Overview
[Diagram or description of the current architecture]
[Identified pattern: MVC / Clean / Layered / etc.]

## SOLID Compliance
| Principle | Status | Key Findings |
|-----------|--------|-------------|
| Single Responsibility | ✅/⚠️/❌ | ... |
| Open/Closed | ✅/⚠️/❌ | ... |
| Liskov Substitution | ✅/⚠️/❌ | ... |
| Interface Segregation | ✅/⚠️/❌ | ... |
| Dependency Inversion | ✅/⚠️/❌ | ... |

## Module Health
| Module | Coupling | Cohesion | Issues |
|--------|----------|----------|--------|

## Critical Structural Issues
1. [Issue + impact + recommendation]

## Recommendations
### Short-term (can fix now)
- ...

### Medium-term (next sprint)
- ...

### Long-term (architectural evolution)
- ...

Common Rationalizations

Notes

• This review focuses on structural architecture, not code-level quality (see /code-quality-audit)
• For small projects (<5 files), a full architecture review may be overkill — suggest /code-quality-audit instead
• Architectural recommendations should consider the team size and project phase

Related Skills

This skill applies the SOLID lens in report mode. For complementary lenses:

• /deepening-review — Depth/seam paradigm in interactive mode. Surfaces shallow modules and grills the chosen one with the user. Uses the vocabulary in agent_docs/architecture-language.md. Run this skill for breadth, /deepening-review for surgical depth.
• /interface-design — Once a deepening candidate is picked (or any new module is being designed), spawns parallel sub-agents producing competing interfaces, then compares.
• /refactoring-guide — Sequences the actual changes once a direction is agreed.