Architecture Review

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

Top Recommendations

Prioritized list of the most impactful architectural improvements.

Overall Health

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