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

Create report at

.audits/architectural-analysis-[timestamp].md

markdown

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

markdown

# 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

After completing the analysis, follow handbook

15.04

to create

tk

tickets for all surfaced issues.

architectural-analysis

NPX Install

Tags

SKILL.md Content

Architectural Analysis

Instructions

Phase 1: Discovery & Planning

Step 1: Map Codebase Structure

Step 2: Identify Entry Points

Step 3: Create Comprehensive File List

Phase 2: Dead Code Detection

Step 1: Identify Exports

Step 2: Search for Usage

Step 3: Categorize Code

Step 4: Check for False Positives

Step 5: Record Findings

Step 6: Mark Complete

Phase 3: Duplication Detection

Step 1: Identify Duplicated Logic Patterns

Step 2: Analyze Duplicated Functionality

Step 3: Categorize Duplication

Step 4: Record Duplication

Phase 4: Architectural Anti-Patterns

Step 1: Identify God Objects/Classes

Step 2: Detect Circular Dependencies

Step 3: Find Tight Coupling

Step 4: Spot Layer Violations

Step 5: Identify Other Anti-Patterns

Phase 5: Type Issues Analysis

Step 1: Find Type Abuse

Step 2: Analyze Type Confusion

Step 3: Find Type Duplication

Step 4: Identify Missing Types

Phase 6: Code Smells Detection

Step 1: Long Methods/Functions

Step 2: Long Parameter Lists

Step 3: Complex Conditionals

Step 4: Magic Numbers/Strings

Step 5: Commented-Out Code

Step 6: Poor Naming

Phase 7: Generate Report

Phase 8: Summary for User

Critical Principles

Success Criteria