playbook/brooks-lint/skills/brooks-audit/architecture-guide.md

Architecture Audit Guide — Mode 2

Purpose: Analyze the module and dependency structure of a system for decay risks that operate at the architectural level. Every finding must follow the Iron Law: Symptom → Source → Consequence → Remedy.

Monorepo note: Treat each deployable service or library as a top-level module. Draw dependencies between services, not between their internal packages. Apply the Conway's Law check at the service ownership level. Within a single service, apply standard module-level analysis.

---

Analysis Process

Work through these six steps in order.

Step 0: Gather Codebase Context

Before drawing anything, establish what you can see.

If the user provided a full directory tree or pasted relevant file contents: skip the proactive reading below and proceed to Step 1.

Otherwise, proactively read the project using these tools:

1. Top-level structure — glob top two levels to identify module boundaries:

   Glob: **/*(depth 2, directories only)
   

2. Entry points — read the package manifest or main config file (e.g., package.json, go.mod, pom.xml, Cargo.toml, pyproject.toml) to confirm language, framework, and declared dependencies.
3. Dependency edges — grep import statements to discover inter-module calls. Run once per language present; limit to the first 200 matches to avoid token overrun:

   Grep: "^\s*(import|from|require\(|use )" across *.ts|*.py|*.go|*.rs|*.java
   

4. Large modules — for any top-level directory with > 10 files, read the file matching index.*, main.*, or __init__.* to understand its stated responsibility.

Stop when you can answer all three:

• What are the top-level modules (names and count)?
• Which modules import from which other modules?
• Which module has the highest fan-in or fan-out?

If the project has > 100 top-level files or > 4 levels of nesting, note which areas were sampled vs. inferred, and flag this in the report scope line.

Step 1: Draw the Module Dependency Graph (Mermaid)

Before evaluating any risk, map the dependencies as a Mermaid diagram. Use this format:

graph TD
  subgraph UI
    WebApp
  end

  subgraph Domain
    AuthService
    OrderService
    PaymentService
  end

  subgraph Infrastructure
    Database
  end

  WebApp --> AuthService
  WebApp --> OrderService
  OrderService --> PaymentService
  OrderService --> Database
  PaymentService --> Database
  AuthService -.->|circular| OrderService

  classDef critical fill:#ff6b6b,stroke:#c92a2a,color:#fff
  classDef warning fill:#ffd43b,stroke:#e67700
  classDef clean fill:#51cf66,stroke:#2b8a3e,color:#fff

  class PaymentService critical
  class OrderService warning
  class Database,AuthService,WebApp clean

The example shows the final colored output. Draw nodes, subgraphs, and edges first; the classDef and class lines can only be written after the risk scan (Rule 6 below).

Rules:

1. Nodes — Use top-level directories or services as nodes, not individual files
2. Grouping — One subgraph per architectural layer or top-level directory (e.g., UI, Domain, Infrastructure)
3. Edges — Solid arrows (-->) point FROM the depending module TO the dependency; use dotted arrows with label (-.->|circular|) for circular dependencies. If no circular dependencies exist, use only solid arrows
4. Node limit — Keep the graph to ~50 nodes maximum; collapse low-risk leaf modules into their parent if needed
5. Fan-out — For any node with fan-out > 5, use a descriptive label: HighFanOutModule["ModuleName (fan-out: 7)"]
6. Colors — Apply classDef colors AFTER completing Steps 2-4: critical (red #ff6b6b) for nodes with Critical findings, warning (yellow #ffd43b) for Warning findings, clean (green #51cf66) for nodes with no findings or only Suggestions. If no findings at all, classify all nodes as clean
7. Direction — Default to graph TD (top-down); use graph LR only if the architecture is clearly a left-to-right pipeline

Step 2: Scan for Dependency Disorder

The most architecturally consequential risk — scan this first.

Look for:

• Circular dependencies (any -.->|circular| edge in the map above)
• Arrows flowing upward (high-level domain depending on low-level infrastructure)
• Stable, widely-depended-on modules that import from frequently-changing modules
• Modules with fan-out > 5
• Absence of a clear layering rule (no consistent answer to "what depends on what?")

Step 3: Scan for Domain Model Distortion

Look for:

• Do module names match the business domain vocabulary?
• Is there a layer called "services" that contains all the business logic while domain objects are pure data structures?
• Are there modules that cross bounded context boundaries (e.g., billing logic in the user module)?
• Is there an anti-corruption layer where external systems interface with the domain?

Step 4: Scan for Remaining Four Risks

Check each in turn:

Knowledge Duplication:

• Are there multiple modules implementing the same concept independently?
• Does the same domain concept appear under different names in different modules?

Accidental Complexity:

• Are there entire layers in the architecture that do not add value?
• Are there modules whose responsibility cannot be stated in one sentence?

Change Propagation:

• Which modules are "blast radius hotspots"? (A change here requires changes in many other modules)
• Does the dependency map reveal why certain features are slow to develop?

Cognitive Overload:

• Can the module responsibility of each module be stated in one sentence from its name alone?
• Would a new developer know which module to add a new feature to?

Step 5: Testability Seam Assessment

A seam is a place in the architecture where behavior can be altered without editing source code — typically an interface, a configuration point, or a dependency injection boundary. Seam density is a proxy for testability and evolvability.

Scan for:

• No seam at the infrastructure boundary: can you replace a real database, file system, or HTTP client with a test double without editing the module under test? If not, the architecture forces integration tests where unit tests would suffice.
• Seam collapse: a module that was once testable in isolation has had its seams removed (e.g., direct constructor instantiation replaced a dependency injection point, or a global singleton replaced an injected collaborator).
• Missing seam in legacy areas: modules without an obvious injection point or interface boundary — any change requires touching the entire call stack to substitute behavior.

If all modules have clear seams at their infrastructure boundaries → no finding.

If seams are absent or collapsed: flag as 🟡 Warning with a Remedy pointing to the specific module and the injection point that needs to be restored or introduced.

Source: Feathers — Working Effectively with Legacy Code, Ch. 4: The Seam Model

Step 6: Conway's Law Check

After the six-risk scan, assess the relationship between architecture and team structure:

• Does the module/service structure reflect the team structure? (Conway's Law: "Organizations design systems that mirror their communication structure")
• If yes: is this intentional design or accidental coupling?
• A mismatch that causes cross-team coordination overhead for every feature is 🔴 Critical.
• A mismatch that is theoretical but not yet causing pain is 🟡 Warning.
• If team structure is unknown, note this as context missing and skip the check.

Calibration examples:

• 🔴 Critical: the Payments module is owned by Team A but contains auth logic owned by Team B — every Payments change requires a sync meeting with Team B
• 🟡 Warning: two separate teams own the utils/ and helpers/ directories which do the same things — theoretically painful but not yet causing release coordination issues
• Not a finding: a single team owns a monorepo with multiple logical modules — Conway's Law misalignment requires separate teams to be meaningful

---

Output

Use the standard Report Template from ../_shared/common.md. Mode: Architecture Audit.

Place the Mermaid dependency graph FIRST under "Module Dependency Graph". Reference relevant node names in findings. Add classDef color assignments LAST, after all findings are identified.