--- name: architecture-review description: Review project architecture, identify structural issues, and plan refactoring. Analyzes directory structure, module boundaries, dependencies, and code organization. Provides systematic approaches for cleanup, restructuring, and migration. Primary focus on TypeScript/JavaScript projects with patterns applicable to other languages. Use this skill when auditing codebases, planning refactors, or improving project organization. --- # Architecture Review Analyze, audit, and improve project structure. ## Review Process ``` ┌─────────────────────────────────────────────────────────────┐ │ ARCHITECTURE REVIEW │ ├─────────────────────────────────────────────────────────────┤ │ │ │ 1. DISCOVERY 2. ANALYSIS 3. PLANNING │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Map structure│ → │ Identify │ → │ Prioritize │ │ │ │ List deps │ │ issues │ │ changes │ │ │ │ Trace flows │ │ Find smells │ │ Plan phases │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ 4. EXECUTION 5. VALIDATION │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ Incremental │ → │ Test │ │ │ │ refactoring │ │ Verify │ │ │ │ Safe moves │ │ Document │ │ │ └─────────────┘ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ## Quick Assessment Checklist ### Structure Health - [ ] Clear separation between layers (UI, business logic, data) - [ ] Consistent directory naming conventions - [ ] Logical grouping (by feature or by type) - [ ] Reasonable file sizes (<500 lines typical) - [ ] No deeply nested directories (>4 levels) ### Dependency Health - [ ] No circular dependencies - [ ] Clear dependency direction (UI → Logic → Data) - [ ] External dependencies isolated - [ ] Shared code properly extracted - [ ] No god modules everything imports ### Code Organization - [ ] Single responsibility per file/module - [ ] Related code colocated - [ ] Clear public API boundaries - [ ] Consistent export patterns - [ ] No barrel file explosion ### Maintainability - [ ] Easy to find code for a feature - [ ] Changes isolated to relevant areas - [ ] New developers can navigate easily - [ ] Tests colocated or clearly organized - [ ] Configuration centralized ## Common Structural Patterns ### Feature-Based (Recommended for Apps) ``` src/ ├── features/ │ ├── auth/ │ │ ├── components/ │ │ ├── hooks/ │ │ ├── api.ts │ │ ├── types.ts │ │ └── index.ts │ ├── users/ │ │ ├── components/ │ │ ├── hooks/ │ │ ├── api.ts │ │ ├── types.ts │ │ └── index.ts │ └── orders/ │ └── ... ├── shared/ │ ├── components/ │ ├── hooks/ │ ├── utils/ │ └── types/ ├── lib/ # Third-party wrappers ├── config/ # App configuration └── app.tsx # Entry point ``` **Pros:** Colocation, feature isolation, clear ownership **Cons:** May duplicate patterns, harder to share ### Layer-Based (Common for APIs) ``` src/ ├── controllers/ # HTTP handlers ├── services/ # Business logic ├── repositories/ # Data access ├── models/ # Data structures ├── middleware/ # HTTP middleware ├── utils/ # Helpers ├── types/ # TypeScript types ├── config/ # Configuration └── index.ts # Entry point ``` **Pros:** Clear responsibilities, familiar pattern **Cons:** Features spread across folders, harder to delete features ### Hybrid (Scales Well) ``` src/ ├── modules/ │ ├── auth/ │ │ ├── auth.controller.ts │ │ ├── auth.service.ts │ │ ├── auth.repository.ts │ │ ├── auth.types.ts │ │ └── index.ts │ ├── users/ │ └── orders/ ├── shared/ │ ├── database/ │ ├── middleware/ │ └── utils/ ├── config/ └── main.ts ``` **Pros:** Feature isolation + clear layers within **Cons:** More boilerplate per feature ## Structural Anti-Patterns ### 🚨 God Module ``` // utils/helpers.ts - 2000+ lines export function formatDate() { ... } export function validateEmail() { ... } export function calculateTax() { ... } export function parseCSV() { ... } export function sendNotification() { ... } // ... 50 more unrelated functions ``` **Fix:** Split by domain (date-utils.ts, validation.ts, tax.ts, etc.) ### 🚨 Circular Dependencies ``` // users/service.ts import { OrderService } from '../orders/service'; // orders/service.ts import { UserService } from '../users/service'; // Circular! ``` **Fix:** Extract shared logic, use dependency injection, or events ### 🚨 Leaky Abstractions ``` // components/UserList.tsx import { prisma } from '../lib/prisma'; // Direct DB access in component! const users = await prisma.user.findMany(); ``` **Fix:** Add service layer, components only call APIs/hooks ### 🚨 Barrel File Explosion ``` // features/index.ts export * from './auth'; export * from './users'; export * from './orders'; // ... 20 more // This causes everything to load even if you need one thing import { LoginButton } from '../features'; // Loads ALL features ``` **Fix:** Import directly from feature, use selective exports ### 🚨 Scattered Configuration ``` // Config in 10 different places src/config.ts src/lib/config.js src/utils/env.ts src/services/settings.ts .env, .env.local, .env.production ``` **Fix:** Single config module that loads all env vars ### 🚨 Deep Nesting ``` src/features/users/components/forms/inputs/text/validation/rules/email.ts ``` **Fix:** Flatten structure, maximum 3-4 levels deep ## Issue Severity Classification | Severity | Impact | Examples | |----------|--------|----------| | **Critical** | Blocks development, causes bugs | Circular deps, broken imports | | **High** | Significant maintenance burden | God modules, no separation | | **Medium** | Slows development | Inconsistent patterns, poor naming | | **Low** | Minor friction | Style inconsistencies, extra files | ## Review Output Template ```markdown # Architecture Review: [Project Name] ## Overview - **Project Type:** [Web App / API / Library / Monorepo] - **Primary Language:** [TypeScript / JavaScript / etc.] - **Framework:** [React / Next.js / Express / NestJS / etc.] - **Size:** [~X files, ~Y lines] ## Current Structure [Directory tree or description] ## Findings ### Critical Issues 1. [Issue]: [Description] - **Location:** [file/folder] - **Impact:** [What problems it causes] - **Recommendation:** [How to fix] ### High Priority 1. ... ### Medium Priority 1. ... ### Low Priority 1. ... ## Recommendations ### Immediate Actions - [ ] [Action 1] - [ ] [Action 2] ### Short-term (1-2 weeks) - [ ] [Action 1] ### Long-term (1+ month) - [ ] [Action 1] ## Proposed Structure [New directory tree if restructuring needed] ## Migration Plan [Phased approach if significant changes] ``` ## When to Restructure **DO restructure when:** - Developers can't find code - Simple changes touch many files - Circular dependencies are common - Tests are hard to write due to coupling - New features require copying boilerplate - Team has grown and needs clearer boundaries **DON'T restructure when:** - "It doesn't feel right" (need concrete issues) - Only for consistency with a blog post - Major deadline approaching - No tests to verify refactoring - Team doesn't agree on target structure --- **References:** - [references/analysis-techniques.md](references/analysis-techniques.md) — Dependency graphs, complexity metrics, code analysis - [references/refactoring-patterns.md](references/refactoring-patterns.md) — Safe refactoring techniques, migration strategies - [references/structural-patterns.md](references/structural-patterns.md) — Directory structures for different project types - [references/dependency-management.md](references/dependency-management.md) — Circular deps, coupling, module boundaries - [references/cleanup-strategies.md](references/cleanup-strategies.md) — Dead code removal, consolidation, naming conventions