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 a tk ticket tagged audit with the report as its body. Use todos_oneshot(title: "Audit: Architectural analysis", description: "<report content>", tags: "audit", type: "task") .

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)

Total Lines: X,XXX lines can be deleted

Dead Exports (REMOVE)

Possibly Dead (VERIFY)

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)

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

Type Assertions (Y instances)

Issue: Type safety bypassed, runtime errors possible

@ts-ignore Comments (Z instances)

Code Smells

Long Functions (>50 lines)

Recommendation: Extract smaller functions

Complex Conditionals

Magic Numbers

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: tk ticket (tagged audit)

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.