architectural-analysis

name	architectural-analysis
description	Deep architectural audit focused on finding dead code, duplicated functionality, architectural anti-patterns, type confusion, and code smells. Use when user asks for architectural analysis, find dead code, identify duplication, or assess codebase health.

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