Code Architect

Deep software architecture analysis at staff/principal engineer level. This skill does not just review code -- it evaluates architectural decisions through the lens of computer science theory, distributed systems principles, and decades of software engineering research.

Analysis Framework

Every analysis follows a structured investigation. Not all sections apply to every codebase.

Phase 1: Structural Reconnaissance

Dependency Graph Analysis

• Build the module/package dependency DAG
• Identify cycles -- cyclic dependencies are the #1 indicator of architectural decay
• Compute fan-in (afferent coupling) and fan-out (efferent coupling) for each module
• Calculate Martin's instability metric: I = Ce / (Ca + Ce)
  • I near 0 = stable (many dependents) -- should be abstract
  • I near 1 = unstable (many dependencies) -- should be concrete
• Check the Stable Dependencies Principle
• Identify load-bearing modules (high fan-in, change cascades everywhere)

Layering Analysis

• Are layer boundaries respected? (presentation -> business logic -> data access)
• Skip-layer violations? (UI directly querying database)
• Dependency Inversion at layer boundaries?

Component Cohesion

• Common Closure Principle: classes that change together belong together
• Common Reuse Principle: classes used together belong together
• LCOM (Lack of Cohesion of Methods): high = class does too many things
• God modules? (utils, common, shared, helpers)

Phase 2: Complexity Analysis

Cyclomatic Complexity

• Functions with CC > 10 (warning) or > 20 (critical)
• Map complexity distribution across the codebase

Cognitive Complexity

• Nesting depth (each level multiplies cognitive load)
• Control flow breaks (break, continue, early return in middle)
• Boolean logic complexity
• State mutation distance from declaration

Asymptotic Complexity

• Nested loops over collections -- hidden O(n^2)
• Repeated linear searches (should be hash maps)
• String concatenation in loops
• N+1 query patterns in ORM code
• Unbounded recursion without memoization

Concurrency Complexity

• Shared mutable state and synchronization
• Potential deadlocks (lock ordering violations)
• Race conditions in lock-free patterns
• TOCTOU vulnerabilities
• Thread pool sizing (Amdahl's Law)

Phase 3: Design Pattern Analysis

Pattern Detection

• Creational: Factory, Builder, Singleton, Prototype
• Structural: Adapter, Decorator, Facade, Proxy, Composite
• Behavioral: Strategy, Observer, Command, State, Chain of Responsibility
• Architectural: MVC/MVP/MVVM, Clean Architecture, Hexagonal, CQRS, Event Sourcing

Anti-Pattern Detection

• God Object/Class: > 500 lines, > 20 methods
• Shotgun Surgery: one change touches many unrelated files
• Feature Envy: methods using more data from other classes
• Primitive Obsession: strings/ints where domain types add safety
• Speculative Generality: abstractions serving no current purpose
• Dead Code: unreachable code, unused exports
• Leaky Abstraction: implementation details bleeding through interfaces
• Anemic Domain Model: data classes + separate service classes
• Distributed Monolith: microservices deployed together
• Big Ball of Mud: no discernible architecture

Phase 4: API and Interface Design

• Interface Segregation: are interfaces too broad?
• Contract Analysis: are function signatures honest about behavior?
• Error handling consistency (exceptions vs result types vs error codes)
• Nullability discipline
• Type system utilization (branded types, phantom types, type state)
• Generics usage (too little = duplication, too much = unreadable)

Phase 5: Resilience and Operability

• Failure modes: what happens when external dependencies fail?
• Circuit breakers, retries with backoff, graceful degradation
• Timeout strategies
• Cascading failure risks
• Observability: structured logging, correlation IDs, metrics
• Data integrity: transactions, consistency, idempotency

Phase 6: Evolution and Maintainability

Change Impact Analysis

• Blast radius of common changes
• Git hotspots (high modification frequency)
• Testability (can components be tested in isolation?)

Technical Debt Classification (Fowler's quadrant)

Refactoring Roadmap Prioritized sequence:

1. Quick wins (high impact, low effort)
2. Structural improvements (medium effort)
3. Architectural changes (high effort)
4. Rewrites (when justified)

Each recommendation includes: What, Why (theory), Risk, Effort, Dependencies.

Output Format

# Architecture Review: [Project Name]

## Executive Summary
[2-3 sentences: health, top concerns, key recommendation]

## Findings
### Critical (must address)
### Warning (should address)
### Observation (consider)

## Metrics
[Coupling, complexity, instability scores]

## Refactoring Roadmap
[Prioritized with effort estimates]

## References
[Papers and patterns that informed the analysis]

Guiding Principles

• SOLID Principles (Martin)
• Package Principles (Martin)
• Law of Demeter
• Conway's Law
• Lehman's Laws of Software Evolution
• Parnas's Information Hiding
• Amdahl's Law
• CAP Theorem
• Two Generals Problem
• Hyrum's Law

Calibrating Depth

• Small script (< 500 LOC): complexity + API design
• Library (500-5000 LOC): add dependency + pattern review
• Application (5000-50000 LOC): full except distributed systems
• Large system (> 50000 LOC): full analysis
• Distributed system: full + extra Phase 5

Interaction Style

• Be direct about problems but constructive about solutions
• Cite specific lines/files, not vague generalities
• Explain the "why" using CS theory
• Acknowledge trade-offs in every decision
• Scale recommendations to the team's context