architecture-review

name	architecture-review
description	Reviews the system architecture for structural issues, dependency cycles, layer violations, scalability concerns, and single points of failure. Use for periodic health checks or before major new features.
argument-hint	[component, module, or 'full' for entire project]
allowed-tools	Read, Grep, Glob, Bash

Architecture Review

Project Structure

!find . -type f -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/vendor/*" -not -path "*/__pycache__/*" -not -path "*/target/*" -not -path "*/bin/*" -not -path "*/obj/*" -not -path "*/.next/*" -not -path "*/dist/*" -not -path "*/build/*" 2>/dev/null | head -80

Directory Layout

!tree -L 3 -I "node_modules|.git|vendor|__pycache__|target|bin|obj|.next|dist|build" 2>/dev/null || find . -type d -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/vendor/*" -maxdepth 3 2>/dev/null

Package/Module Config

!cat package.json go.mod Cargo.toml pyproject.toml requirements.txt *.csproj pom.xml 2>/dev/null | head -60

---

Review Areas

1. Project Structure & Organization

• Is the directory layout clear and consistent?
• Does it follow established conventions for the stack? (e.g., src/, app/, lib/, pkg/)
• Are related files co-located or scattered?
• Is there a clear entry point?

2. Dependency Architecture

• Map the dependency graph between major modules/packages
• Identify circular dependencies — modules that import each other
• Check for layer violations — e.g., presentation layer importing directly from data layer
• Look for god modules — modules that everything depends on
• Assess coupling: can modules be changed independently?

3. Separation of Concerns

• Is business logic separated from framework/transport code?
• Are side effects (I/O, network, database) isolated at boundaries?
• Is configuration separated from code?
• Are there clear interfaces between layers?

4. Scalability Considerations

• Stateless vs stateful components — which components hold state?
• Are there bottlenecks that would fail under load?
• Database query patterns — are they efficient at scale?
• Caching strategy — what is cached, where, and when invalidated?
• Background job handling — how are long-running tasks managed?

5. Reliability & Resilience

• Single points of failure: What happens if any component goes down?
• Error boundaries: Where do errors propagate, and are they caught?
• Retry logic: For external service calls, is there retry with backoff?
• Graceful degradation: Does the system handle partial failures?
• Health checks: Are there endpoints or mechanisms to monitor health?

6. Security Architecture

• Authentication and authorization boundaries
• Where is input validation enforced?
• How are secrets managed?
• API rate limiting and abuse prevention

---

Output Format

Architecture Diagram (ASCII)

┌─────────┐     ┌─────────┐     ┌──────────┐
│ Frontend │────▶│   API   │────▶│ Database │
└─────────┘     └─────────┘     └──────────┘
                     │
                     ▼
               ┌───────────┐
               │  External  │
               │  Services  │
               └───────────┘

Findings Table

#	Area	Finding	Severity	Recommendation

Top Recommendations

Prioritized list of the most impactful architectural improvements.

Overall Health

Rate: Healthy / Needs Attention / At Risk — with reasoning.