architectural-analysis

# Architectural Analysis ## Instructions Perform comprehensive architectural audit focused on structural issues, dead code, duplication, and systemic problems. ### Phase 1: Discovery & Planning #### Step 1: Map Codebase Structure ```bash # Get directory structure find . -type d -not -path "*/node_modules/*" -not -path "*/.git/*" # Count files by type find . -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" | wc -l ``` #### Step 2: Identify Entry Points - Main application entry (`index.ts`, `main.ts`, `app.ts`) - API routes/controllers - Public exports (`index.ts` files) - CLI entry points - Test files #### Step 3: Create Comprehensive File List Use Glob to find all source files. Create todo list with one item per file to analyze. ### Phase 2: Dead Code Detection For EACH file in the todo list: #### Step 1: Identify Exports - What does this file export? - Are exports functions, classes, types, constants? - Is anything exported at all? #### Step 2: Search for Usage For each export, search if it's imported/used anywhere: ```bash # Search for imports of this export grep -r "import.*ExportName" . --include="*.ts" --include="*.tsx" grep -r "from.*filename" . --include="*.ts" --include="*.tsx" # Search for direct usage grep -r "ExportName" . --include="*.ts" --include="*.tsx" ``` #### Step 3: Categorize Code **Dead Code** (mark for removal): - Exported but never imported - Functions defined but never called - Classes instantiated nowhere - Types defined but never used - Constants defined but never referenced - Entire files with no imports from other files **Possibly Dead** (needs verification): - Only used in commented-out code - Only used in dead code - Only used in other unused exports - Used only in tests for deprecated features **Internal Dead Code**: - Functions defined in file but never called (not exported) - Variables assigned but never read - Parameters accepted but never used #### Step 4: Check for False Positives Not dead if: - Used in tests (may be public API) - Dynamically imported/required - Used via reflection/string references - Part of public API (even if not used internally) - Framework hooks (lifecycle methods, callbacks) - Accessed via `window` or global scope #### Step 5: Record Findings ``` File: path/to/file.ts Status: [DEAD|POSSIBLY_DEAD|USED] Exports: [list] Dead Exports: - ExportName - No imports found - AnotherExport - Only used in test for deprecated feature Confidence: [HIGH|MEDIUM|LOW] ``` #### Step 6: Mark Complete Update todo list. ### Phase 3: Duplication Detection #### Step 1: Identify Duplicated Logic Patterns Search for common patterns that suggest duplication: - Similar function names across files - Repeated code blocks - Multiple implementations of same concept **Manual Pattern Recognition**: - Read files in same directory - Look for suspiciously similar code - Compare utilities/helpers across modules - Check for copy-pasted blocks **Grep-Based Detection**: ```bash # Find similar function signatures grep -r "function validateEmail" . --include="*.ts" grep -r "async.*fetch.*api" . --include="*.ts" grep -r "export.*UserForm" . --include="*.tsx" ``` #### Step 2: Analyze Duplicated Functionality For each potential duplication: - Read both/all implementations - Are they actually the same logic? - Do they handle same cases? - Could one replace the other? - Are differences intentional or accidental? #### Step 3: Categorize Duplication **Exact Duplication** (CRITICAL): - Identical or near-identical code in multiple places - Copy-pasted functions - Duplicated utility functions - **Impact**: Bug fixes need multiple updates, maintenance burden **Similar Logic** (HIGH): - Same algorithm, different implementation - Slightly different parameter handling - Different names, same purpose - **Impact**: Inconsistency risk, harder to maintain **Conceptual Duplication** (MEDIUM): - Multiple ways to do the same thing - Competing implementations - Overlapping utilities - **Impact**: Confusion, decision paralysis **Type Duplication** (HIGH): - Same interface/type defined multiple times - Similar types that should be unified - Duplicate constants/enums - **Impact**: Type inconsistency, refactoring difficulty #### Step 4: Record Duplication ``` Duplication Group: Email Validation Type: Exact Duplication Instances: - src/utils/validators.ts:42 - validateEmail() - src/lib/email.ts:15 - isValidEmail() - src/components/forms/validation.ts:67 - checkEmailFormat() Analysis: All three implement same regex check Recommendation: Keep utils/validators.ts version, remove others Impact: 3 places to update when logic changes ``` ### Phase 4: Architectural Anti-Patterns #### Step 1: Identify God Objects/Classes Search for files that do too much: - Files over 500 lines - Classes with 10+ methods - Files with many responsibilities - Modules that import from everywhere ```bash # Find large files find . -name "*.ts" -exec wc -l {} + | sort -rn | head -20 ``` Analyze large files: - What does this file do? - Does it have single responsibility? - Should it be split? #### Step 2: Detect Circular Dependencies Look for: - File A imports from B, B imports from A - Circular chains: A → B → C → A - Module coupling cycles Use grep to trace import chains: ```bash # Check what file imports grep "^import.*from" src/services/auth.ts # Check what imports this file grep -r "from.*auth" src/ --include="*.ts" ``` #### Step 3: Find Tight Coupling Identify: - High-level modules depending on low-level modules - Business logic depending on infrastructure - Core logic depending on framework specifics - Modules that import from many other modules #### Step 4: Spot Layer Violations Check architecture layers: - Do components import directly from database layer? - Do models import from views? - Do utilities import from business logic? - Is there proper separation of concerns? #### Step 5: Identify Other Anti-Patterns **Singleton Abuse**: - Global state everywhere - Module-level mutable state - Static class methods accessing shared state **Anemic Domain Models**: - Data classes with no behavior - All logic in services, models just have getters/setters **Shotgun Surgery**: - Single feature change requires touching many files - Indicates poor cohesion **Feature Envy**: - Methods that use more data from other classes than their own ### Phase 5: Type Issues Analysis #### Step 1: Find Type Abuse Search for problematic type usage: ```bash # Find 'any' usage grep -r ": any" . --include="*.ts" --include="*.tsx" -n # Find 'unknown' usage grep -r ": unknown" . --include="*.ts" -n # Find type assertions grep -r "as any" . --include="*.ts" -n grep -r "as unknown" . --include="*.ts" -n # Find @ts-ignore grep -r "@ts-ignore" . --include="*.ts" -n grep -r "@ts-expect-error" . --include="*.ts" -n ``` #### Step 2: Analyze Type Confusion For each file with type issues: - Why is `any` used? - Could proper type be defined? - Is type assertion hiding a real type error? - Are @ts-ignore comments masking actual problems? #### Step 3: Find Type Duplication Look for: - Same interface defined in multiple files - Similar types that could be unified - Types that could extend from common base - Constants/enums duplicated across files #### Step 4: Identify Missing Types Check for: - Implicit `any` from missing type annotations - Functions without return type - Callbacks without proper typing - Generic types that should be specific ### Phase 6: Code Smells Detection #### Step 1: Long Methods/Functions ```bash # Find functions with many lines # (manual inspection of large files) ``` Flag functions over 50 lines - likely doing too much. #### Step 2: Long Parameter Lists Search for functions with 4+ parameters: - Could use object parameter instead? - Are parameters related (should be grouped)? #### Step 3: Complex Conditionals Look for: - Deeply nested if statements (3+ levels) - Long boolean expressions - Switch statements with 10+ cases - Complex ternary operators #### Step 4: Magic Numbers/Strings Search for: - Hardcoded numbers with unclear meaning - String literals used repeatedly - Unexplained constants Should be named constants. #### Step 5: Commented-Out Code ```bash # Find commented code blocks grep -r "^[[:space:]]*//.*function\|class\|const" . --include="*.ts" ``` Commented code should be deleted (use git history). #### Step 6: Poor Naming Look for: - Single letter variables (outside loops) - Abbreviations without context (`usr`, `msg`, `tmp`) - Misleading names - Names that don't reflect purpose ### Phase 7: Generate Report Read `assets/report-template.md` and write the populated report to `.audits/architectural-analysis-[timestamp].md`. Replace every placeholder (X, Y, Z, file paths, line numbers) with findings from Phases 2-6. Keep every section present even if a finding count is zero — note "None found" rather than deleting headings. ### Phase 8: Summary for User Read `assets/summary-template.md` and emit the populated summary inline in chat after writing the full report. Replace placeholders and link to the full report at the end. ## Critical Principles - **NEVER EDIT FILES** - This is analysis only, not cleanup - **NEVER SKIP FILES** - Analyze entire codebase systematically - **BE THOROUGH** - Dead code detection requires checking all imports - **VERIFY DUPLICATES** - Don't just match names, check if logic is same - **UNDERSTAND ARCHITECTURE** - See the big picture, not just individual files - **QUANTIFY IMPACT** - Count lines, estimate cleanup potential - **BE CONFIDENT** - Mark confidence level (HIGH/MEDIUM/LOW) for findings - **TRACK PROGRESS** - Use todo list for file-by-file analysis ## Success Criteria A complete architectural analysis includes: - All files analyzed for dead code - All exports checked for usage - Duplication groups identified and cataloged - Architectural anti-patterns found and explained - Type issues located and categorized - Code smells flagged - Impact assessment quantified - Structured report generated