Audit Architecture

Analyze the structural health of a codebase by examining coupling, cohesion, hidden dependencies, and design patterns.

Prerequisites

Omen CLI must be installed and available in PATH.

Workflow

Step 1: Map Module Dependencies

Run the dependency graph analysis:

omen -f json graph

Look for:

• Circular dependencies
• God modules (too many dependents)
• Orphan modules (no connections)

Step 2: Detect Architectural Smells

Run the smells analysis:

omen -f json smells

Detects cyclic dependencies, hub modules, unstable dependencies, and central connectors using Tarjan's SCC algorithm.

Step 3: Measure Cohesion

Run the cohesion analysis for CK metrics:

omen -f json cohesion

Metrics to watch:

• LCOM (Lack of Cohesion): > 0.7 indicates class doing too many things
• WMC (Weighted Methods per Class): > 30 indicates too complex
• CBO (Coupling Between Objects): > 10 indicates too many dependencies

Step 4: Find Hidden Dependencies

Run the temporal coupling analysis:

omen -f json temporal

Files that always change together but don't have explicit imports indicate:

• Shared global state
• Implicit contracts
• Missing abstractions

Step 5: Check Ownership Distribution

Run the ownership analysis:

omen -f json ownership

Look for:

• Modules with no clear owner
• Over-concentrated ownership (bus factor = 1)
• Fragmented ownership (many contributors, none dominant)

Architecture Smells

Common issues to identify:

Smell	Detection	Impact
Circular Dependency	A -> B -> C -> A in graph	Hard to test, modify
God Module	> 50% of code depends on it	Single point of failure
Shotgun Surgery	High temporal coupling	Changes ripple everywhere
Feature Envy	Low cohesion in classes	Wrong abstraction boundaries
Knowledge Silo	Bus factor = 1	Team risk

Output Format

Present architecture review as:

# Architecture Review

## Module Dependency Analysis

### Dependency Graph
[Mermaid diagram from graph analysis]

### Issues Detected

#### Circular Dependencies
- `auth/` <-> `user/` <-> `session/`
  - Impact: Cannot deploy or test independently
  - Fix: Extract shared interface to `contracts/`

#### God Modules
- `core/` - 75% of modules depend on this
  - Impact: Changes here affect everything
  - Fix: Split into focused submodules

## Cohesion Analysis

### Low Cohesion Classes (LCOM > 0.7)
| Class | LCOM | WMC | Recommendation |
|-------|------|-----|----------------|
| UserService | 0.85 | 45 | Split into UserAuth, UserProfile |
| DataProcessor | 0.78 | 38 | Extract strategies for each type |

### High Coupling (CBO > 10)
- `api/handlers.go` - CBO: 15
  - Depends on too many internal modules
  - Consider facade pattern

## Hidden Dependencies

### Temporal Coupling (> 0.8)
- `config/settings.go` <-> `cache/redis.go` (0.92)
  - No import relationship
  - Likely shares configuration assumptions
  - Fix: Explicit configuration injection

## Ownership Distribution

### Knowledge Silos
- `legacy/` - Single owner (bob), no recent contributions
  - Risk: Bob leaves, no one knows this code
  - Fix: Pair programming, documentation

### Fragmented Ownership
- `core/` - 8 contributors, none > 20%
  - Risk: No clear decision maker
  - Fix: Assign primary maintainer

## Recommendations

### Immediate Actions
1. Break circular dependency in auth/user/session
2. Document legacy/ module before Bob's vacation

### Medium Term
1. Split core/ into focused modules
2. Add explicit dependency injection for config

### Long Term
1. Establish module ownership model
2. Create architecture decision records (ADRs)