pedronauck/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

# 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:

# 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:

# 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

# 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:

# 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:

# 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

# 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

# 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