Architecture Audit

Architecture Audit

Overview

Evaluate the structural health of a codebase — patterns, coupling, cohesion, and alignment between what the code claims to be and what it actually is.

Core principle: Architecture is not what's drawn on a whiteboard. It's what's in the code.

The Iron Law

NO ARCHITECTURAL CLAIMS WITHOUT READING THE ACTUAL CODE

When to Use

• "Audit this codebase"
• "Is this well-architected?"
• "What's the technical debt situation?"
• System feels hard to change or understand
• New team member needs to understand the system
• Before a major refactoring or migration

When NOT to Use

• First encounter with a codebase (use codebase-mapping first)
• Debugging a specific bug (use systematic-debugging)
• Performance bottleneck investigation only (use performance-audit)
• Need to understand what the codebase does (use codebase-mapping)

Anti-Shortcut Rules

YOU CANNOT:
- Assess architecture from directory names alone — read the actual code in each layer
- Claim "clean architecture" because folders are named well — check dependency direction
- Say "patterns are consistent" without checking EVERY module — inconsistency hides in corners
- Skip dependency graph analysis — coupling only reveals itself through imports
- Accept "it works" as architectural validation — working ≠ well-architected
- Audit only the happy path — error handling architecture matters equally
- Skip cross-cutting concerns — auth, logging, config are architecture too
- Trust documentation over code — code is the source of truth, docs drift

Common Rationalizations (Don't Accept These)

Iron Questions

1. Can I add a new feature without modifying existing code? (OCP)
2. Can I replace the database without touching business logic? (DIP)
3. Can I describe what each module does in ONE sentence? (SRP/cohesion)
4. Do inner layers depend on outer layers? (dependency direction violation)
5. If I change one module, how many other modules break? (coupling)
6. Are there circular dependencies? (sure sign of tangled architecture)
7. Does the code match the claimed architecture pattern?
8. Are cross-cutting concerns (auth, logging, errors) centralized or scattered?
9. Can I test business logic without infrastructure? (testability)
10. Is there a God class/module that everything depends on?

The Audit Process

Phase 1: Structure Mapping

1. MAP the directory structure — what's where
2. IDENTIFY the architectural pattern (layered, hexagonal, microservices, monolith, etc.)
3. COMPARE claimed architecture (docs) vs actual architecture (code)
4. DOCUMENT the real dependency graph

Key questions:

• Where does business logic live?
• Where does data access happen?
• Where are the boundaries between modules?
• What's shared vs isolated?

Phase 2: Dependency Analysis

1. MAP module dependencies — who imports what
2. IDENTIFY circular dependencies
3. CHECK dependency direction — do inner layers depend on outer?
4. MEASURE coupling — how many modules change when one module changes?

Dependency direction rules:

✅ Controllers → Services → Repositories → Models
❌ Models → Services (wrong direction)
❌ Services → Controllers (wrong direction)
❌ Utilities → Business Logic (wrong direction)

Dependency health matrix:

Phase 3: Pattern Consistency

1. IDENTIFY the dominant patterns (Repository, Service, Factory, etc.)
2. CHECK if patterns are applied consistently
3. FIND violations — where does the pattern break?
4. ASSESS — is the pattern appropriate for the problem?

Common pattern violations:

Phase 4: Cohesion and Boundaries

1. CHECK module cohesion — does each module have a single, clear purpose?
2. CHECK boundary clarity — can you describe what a module does in one sentence?
3. FIND leaking abstractions — internal details exposed to consumers
4. IDENTIFY god classes/modules — things that do too much

Cohesion checklist:

Phase 5: Cross-Cutting Concerns

1. HOW is authentication handled? (centralized or scattered?)
2. HOW is authorization enforced? (middleware, decorators, manual checks?)
3. HOW is error handling done? (global handler, per-endpoint, inconsistent?)
4. HOW is logging implemented? (structured, unstructured, missing?)
5. HOW is configuration managed? (env vars, hardcoded, mixed?)
6. HOW are transactions managed? (explicit, implicit, missing?)
7. HOW is validation done? (centralized, per-endpoint, duplicated?)

Cross-cutting concern health:

Phase 6: Evolution Assessment

1. HOW hard is it to add a new feature? (new endpoint, new entity, new UI page)
2. HOW hard is it to change an existing feature?
3. HOW hard is it to delete a feature?
4. WHAT breaks when you touch one thing? (blast radius)
5. HOW would this scale at 10x the current load?
6. WHAT would a new team member struggle with?

Output Format

# Architecture Audit: [Project Name]

## Executive Summary
[2-3 sentences: overall health assessment]

## Architecture Overview
- **Pattern:** [Identified pattern]
- **Claimed vs Actual:** [Alignment assessment]
- **Module Count:** [N modules/packages/services]
- **Primary Language(s):** [Languages]

## Dependency Map
[Key dependencies and their directions]

## Findings

### 🔴 Critical
[Findings with evidence and recommendations]

### 🟠 High
[...]

### 🟡 Medium
[...]

### 🟢 Low
[...]

## Metrics

| Metric | Value | Assessment |
|--------|-------|------------|
| Circular dependencies | N | 🔴/🟢 |
| God classes (>300 lines) | N | 🔴/🟢 |
| Dependency depth | N layers | 🟡/🟢 |
| Test coverage estimate | N% | 🟡/🟢 |
| Avg file length | N lines | 🟡/🟢 |
| Cross-cutting consistency | N/7 centralized | 🟡/🟢 |

## Recommendations
[Priority-ordered improvements with effort estimates]

## Verdict
[PASS / CONDITIONAL PASS / FAIL]

Red Flags — Stop and Escalate

• No clear boundaries between modules
• Circular dependencies everywhere
• Business logic in 10+ different layers
• No tests
• No consistent error handling
• Config values hardcoded throughout
• God module that everything imports from
• Domain layer imports framework/infrastructure code

Integration

• Before: codebase-mapping for initial understanding
• Alongside: security-audit, performance-audit, database-audit
• After: refactoring-safely for recommended improvements
• Triggers: writing-plans for remediation work

Converted and distributed by TomeVault — claim your Tome and manage your conversions.