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

Create report at .audits/architectural-analysis-[timestamp].md:

# Architectural Analysis Report
**Date**: [timestamp]
**Files Analyzed**: X
**Dead Code Files**: Y
**Duplication Groups**: Z

---

## Executive Summary
- **Dead Code**: X files, Y exports completely unused
- **Duplicated Functionality**: Z duplication groups
- **Architectural Anti-Patterns**: W issues
- **Type Issues**: V problematic usages
- **Code Smells**: U instances

**Estimated Cleanup**: Remove ~X lines of dead code, consolidate Y duplications

---

## Dead Code

### Completely Dead Files (DELETE)
| File | Reason | Confidence |
|------|--------|------------|
| `src/old/legacy-processor.ts` | No imports found | HIGH |
| `src/utils/unused-helper.ts` | Exported but never used | HIGH |
| `src/temp/temp-service.ts` | Temporary file left behind | HIGH |

**Total Lines**: X,XXX lines can be deleted

### Dead Exports (REMOVE)
| File | Export | Reason |
|------|--------|--------|
| `src/utils/format.ts` | `formatOldDate()` | Replaced by `formatDate()`, no usage |
| `src/services/auth.ts` | `oldLogin()` | Deprecated, no usage found |

### Possibly Dead (VERIFY)
| File | Export | Reason | Verification Needed |
|------|--------|--------|---------------------|
| `src/lib/api.ts` | `fetchOldApi()` | Only used in commented code | Check if truly deprecated |

### Internal Dead Code
- `src/services/user.ts:125` - Private method `_validateLegacy()` never called
- `src/components/form.tsx:89` - Variable `tempData` assigned but never read

---

## Duplicated Functionality

### CRITICAL: Exact Duplicates

#### Duplication Group 1: Email Validation
**Instances**: 3
**Files**:
- `src/utils/validators.ts:42` - `validateEmail(email: string)`
- `src/lib/email.ts:15` - `isValidEmail(email: string)`
- `src/components/forms/validation.ts:67` - `checkEmailFormat(email: string)`

**Analysis**: All three use identical regex pattern `/^[^\s@]+@[^\s@]+\.[^\s@]+$/`
**Lines Duplicated**: ~15 lines × 3 = 45 lines
**Recommendation**:
- Keep: `src/utils/validators.ts:validateEmail()`
- Remove: Other two implementations
- Update: All imports to use validators version

#### Duplication Group 2: API Error Handling
**Instances**: 4
**Files**: [list]
**Analysis**: [similar]

### HIGH: Similar Logic

#### Duplication Group: Date Formatting
**Instances**: 2
**Files**:
- `src/utils/date.ts:30` - `formatDate()` - Uses date-fns
- `src/lib/format.ts:45` - `formatDateTime()` - Uses native Date

**Analysis**: Both format dates but use different libraries
**Recommendation**: Standardize on date-fns, remove native version

### Type Duplication

#### Type Group: User Interface
**Instances**: 3
**Files**:
- `src/types/user.ts` - `User` interface
- `src/models/user.ts` - `UserModel` interface (identical fields)
- `src/api/types.ts` - `UserData` interface (identical fields)

**Recommendation**: Use single `User` type from `src/types/user.ts`

---

## Architectural Anti-Patterns

### God Objects

#### `src/services/application-manager.ts` (850 lines)
**Responsibilities**: Database, auth, config, logging, caching, validation
**Issue**: Violates SRP, does everything
**Recommendation**: Split into:
- `database.service.ts`
- `auth.service.ts`
- `config.service.ts`
- `logging.service.ts`

### Circular Dependencies

#### Cycle 1: `auth.ts` ↔ `user.ts`
- `auth.ts` imports `getUserById` from `user.ts`
- `user.ts` imports `validateToken` from `auth.ts`
**Issue**: Creates tight coupling, makes testing hard
**Recommendation**: Extract shared types to separate file

### Tight Coupling

#### `components/UserForm.tsx` → `services/database.ts`
**Issue**: UI component directly importing database layer
**Recommendation**: Use service layer abstraction

### Layer Violations

#### `models/User.ts` imports from `components/`
**Issue**: Model layer should not know about view layer
**Recommendation**: Remove dependency, pass data via props

---

## Type Issues

### `any` Usage (X instances)

| File | Line | Context | Severity |
|------|------|---------|----------|
| `src/api/client.ts` | 45 | `response: any` | HIGH |
| `src/utils/parse.ts` | 23 | `data: any` | HIGH |

**Total `any` usages**: X
**Recommendation**: Define proper types for all cases

### Type Assertions (Y instances)

| File | Line | Assertion | Issue |
|------|------|-----------|-------|
| `src/lib/api.ts` | 67 | `as User` | Unsafe cast, no validation |
| `src/utils/parse.ts` | 89 | `as unknown as T` | Double cast to bypass types |

**Issue**: Type safety bypassed, runtime errors possible

### @ts-ignore Comments (Z instances)

| File | Line | Reason | Should Fix |
|------|------|--------|------------|
| `src/legacy/old.ts` | 34 | "Type error in legacy code" | Refactor or remove file |

---

## Code Smells

### Long Functions (>50 lines)

| File | Function | Lines | Issue |
|------|----------|-------|-------|
| `src/services/processor.ts` | `processData()` | 127 | Does too much, hard to test |

**Recommendation**: Extract smaller functions

### Complex Conditionals

| File | Line | Issue |
|------|------|-------|
| `src/utils/validator.ts` | 45 | Nested 4 levels deep |
| `src/lib/parser.ts` | 89 | Boolean expression spans 3 lines |

### Magic Numbers

| File | Line | Magic Value | Should Be |
|------|------|-------------|-----------|
| `src/config/limits.ts` | 12 | `86400` | `SECONDS_PER_DAY` |
| `src/utils/format.ts` | 34 | `1000` | `MS_PER_SECOND` |

### Commented-Out Code

**Files with commented code**: X
- `src/old/legacy.ts` - 45 lines of commented code
- `src/services/auth.ts` - Old implementation commented out

**Recommendation**: Delete all commented code (use git history)

---

## Statistics

**Dead Code**:
- Files: X
- Exports: Y
- Lines: Z (estimated)

**Duplication**:
- Groups: X
- Files affected: Y
- Duplicated lines: ~Z

**Architectural Issues**:
- God objects: X
- Circular dependencies: Y
- Layer violations: Z

**Type Issues**:
- `any` usage: X
- Type assertions: Y
- @ts-ignore: Z

**Code Smells**:
- Long functions: X
- Complex conditionals: Y
- Magic numbers: Z

---

## Impact Assessment

### Code Cleanup Potential
- **Dead code removal**: ~X,XXX lines
- **Duplication consolidation**: ~Y,YYY lines
- **Total reduction**: ~Z,ZZZ lines (AA% of codebase)

### Maintainability Improvement
- Fewer places to update when fixing bugs
- Clearer code responsibilities
- Better type safety
- Reduced cognitive load

### Risk Areas
- High coupling in `services/` directory
- Type safety compromised in `api/` layer
- Architectural violations in `components/`

Phase 8: Summary for User

Provide concise summary:

# Architectural Analysis Complete

## Dead Code Found
- **X completely dead files** - Can be deleted immediately
- **Y unused exports** - Can be removed
- **~Z,ZZZ lines** of dead code identified

## Top Dead Files
1. `src/old/legacy-processor.ts` - No imports
2. `src/temp/temp-service.ts` - Temporary file
3. `src/utils/unused-helper.ts` - Exported but never used

## Duplication Found
- **X duplication groups** identified
- **Most duplicated**: Email validation (3 copies)
- **~Y,YYY lines** of duplicated code

## Architectural Issues
- **Z god objects** doing too much
- **W circular dependencies** found
- **V layer violations** detected

## Type Issues
- **X `any` usages** - Should have proper types
- **Y type assertions** - Bypassing type safety
- **Z @ts-ignore comments** - Masking errors

## Code Smells
- **X long functions** (>50 lines)
- **Y complex conditionals** (3+ nesting)
- **Z magic numbers** - Should be constants

## Cleanup Potential
Removing dead code and consolidating duplication could eliminate **~X,XXX lines** (Y% of codebase)

**Full Report**: `.audits/architectural-analysis-[timestamp].md`

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