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)

Rationalization	Reality
"The folder structure looks clean"	Folder structure ≠ architecture. Check dependency direction.
"We're using MVC/Clean Architecture"	Claiming a pattern ≠ implementing it. Verify with imports.
"Only the core modules matter"	Utility modules, middleware, and config can rot the architecture.
"It's a small project, architecture doesn't matter"	Small projects become large projects. Foundation matters.
"We'll fix the architecture later"	Later never comes. Architectural debt compounds exponentially.
"The tests prove the architecture is fine"	Tests can pass in a poorly architected system.