architecture-review

Architecture Review Analyze, audit, and improve project structure. Key Principles Measure before changing — Map structure and identify concrete issues before proposing changes Clear boundaries — Layers (UI, logic, data) separated with consistent dependency direction Colocation — Related code together; easy to find, change, and delete features Incremental migration — Refactor in phases, validate each step with tests Quick Assessment No circular dependencies Consistent directory naming and grouping (by feature or by type) Single responsibility per file/module, reasonable file sizes (<500 lines) External dependencies isolated, shared code properly extracted New developers can navigate and find code for any feature easily Quick Start Checklist Map current structure: directory tree, dependency graph, module boundaries Identify issues: circular deps, god modules, leaky abstractions, deep nesting Classify severity: critical (blocks dev), high (maintenance burden), medium/low (friction) Propose target structure with migration plan Execute incrementally, validating with tests after each move References Reference Description analysis-techniques.md Dependency graphs, complexity metrics, code analysis refactoring-patterns.md Safe refactoring techniques, migration strategies structural-patterns.md Directory structures for different project types dependency-management.md Circular deps, coupling, module boundaries cleanup-strategies.md Dead code removal, consolidation, naming conventions anti-rationalization.md Iron Law, common rationalizations, red flag STOP list for architecture discipline