stevefeldman/architecture-review

Architecture Review

Analyze the overall architecture and design patterns of any codebase to assess maintainability, scalability, and adherence to best practices.

Usage

/architecture-review                          # Full review of current codebase
/architecture-review data-flow                # Focus on data flow only
/architecture-review security,scalability     # Multiple focus areas

Instructions

Review the codebase architecture with the following scope: $ARGUMENTS

If $ARGUMENTS specifies a focus area, limit the review to the relevant sections below. If no focus is given, perform a full review but keep each section concise — breadth over depth.

1. Discovery

Before analyzing, establish context:

• Identify the tech stack, frameworks, and runtime environment
• Read project config files (package.json, go.mod, requirements.txt, etc.)
• Map the directory structure and identify architectural boundaries
• Check for existing architecture docs, ADRs, or CLAUDE.md files

2. Structural Analysis

• Patterns: Identify architectural patterns in use (MVC, Clean Architecture, hexagonal, event-driven, etc.)
• Module boundaries: Review separation of concerns and layer structure
• Dependencies: Analyze coupling between modules, check for circular dependencies, assess dependency direction
• Component design: Check single responsibility adherence, interface design, and abstraction levels

3. Data Flow & State

• Trace data flow through the application end-to-end
• Review state management patterns and implementation
• Analyze data persistence, storage strategies, and caching layers
• Check for proper data validation and transformation at boundaries

4. Resilience & Operations

• Error handling: Review strategy consistency, propagation, and recovery patterns
• Scalability: Assess horizontal/vertical scaling capabilities, stateless design, bottlenecks
• Observability: Review logging, monitoring, and alerting integration
• Configuration: Check separation of config from code, environment management, feature flags

5. Security Architecture

• Review security boundaries and trust zones
• Check authentication and authorization architecture
• Analyze data protection and encryption practices
• Assess input validation at system boundaries

6. Testability & Quality

• Review test structure and organization across architectural layers
• Check for testability in design (dependency injection, interface-based design)
• Assess test coverage distribution and identify undertested layers
• Review mocking and dependency isolation strategies

7. Evolution & Debt

• Assess the architecture's ability to accommodate change
• Identify technical debt and modernization opportunities
• Review technology stack alignment with current requirements
• Check for proper versioning and backward compatibility

8. Recommendations

Produce a scored report:

## Architecture Review Report

### Overall Score: [X]/100

| Dimension           | Score | Status |
|---------------------|-------|--------|
| Structure & Patterns| X/100 | 🟢/🟡/🔴 |
| Data Flow & State   | X/100 | 🟢/🟡/🔴 |
| Resilience & Ops    | X/100 | 🟢/🟡/🔴 |
| Security            | X/100 | 🟢/🟡/🔴 |
| Testability         | X/100 | 🟢/🟡/🔴 |
| Evolution & Debt    | X/100 | 🟢/🟡/🔴 |

### Key Strengths
- [Top 3 things done well]

### Critical Issues
- [Issues requiring immediate attention]

### Recommended Improvements
1. [Highest impact, with specific file/module references]
2. [...]
3. [...]

### Architecture Evolution Roadmap
- Short-term: [Quick wins]
- Medium-term: [Structural improvements]
- Long-term: [Strategic changes]

Focus on actionable insights with specific file paths and code references. Every recommendation should include why it matters and what to do about it.