playbook/skills/thirdparty/codebase-recon/references/architecture-analysis.md

Architecture Analysis

Techniques for analyzing system structure, dependencies, and component relationships.

Dependency Mapping

Forward Dependencies

What a component relies on:

1. Direct imports — explicit dependencies in code
2. Indirect references — called through interfaces
3. Runtime dependencies — configuration, environment
4. Data dependencies — shared state, databases

Reverse Dependencies

What relies on this component:

1. Direct dependents — explicit imports from other modules
2. Interface consumers — components using this API
3. Side effect consumers — code relying on mutations
4. Event subscribers — listeners for this component's events

Circular Dependencies

Red flags:

• A imports B, B imports A
• Longer cycles: A → B → C → A
• Implicit cycles through shared state

Resolution strategies:

• Extract shared code to separate module
• Introduce interface/abstraction layer
• Invert dependency direction
• Break into smaller components

Layer Identification

Detecting Layers

Look for:

• Directional flow — data/control flows one way
• Abstraction levels — concrete → abstract as you ascend
• Responsibility clustering — similar concerns grouped
• Interface boundaries — clear contracts between groups

Common Layer Patterns

Three-tier:

• Presentation (UI, API endpoints)
• Business logic (domain, workflows)
• Data access (repositories, queries)

Hexagonal/Clean:

• Core domain (entities, business rules)
• Application layer (use cases, orchestration)
• Infrastructure (frameworks, external services)
• Interfaces (controllers, adapters)

Microservices:

• Service boundary (API gateway)
• Service logic (domain per service)
• Data layer (per-service database)
• Cross-cutting (auth, logging, monitoring)

Layer Violations

Violations indicate architectural drift:

• Lower layer imports higher layer
• Business logic in presentation layer
• Data access code in domain entities
• Infrastructure concerns leaking into core

Interface Analysis

Contract Definition

Examine:

• Input types — what does it accept?
• Output types — what does it return?
• Error modes — what can fail, how?
• Side effects — mutations, I/O, state changes
• Invariants — what must always be true?

API Quality

Strong interfaces show:

• Cohesion — methods belong together
• Minimal surface — small, focused API
• Clear contracts — types tell the story
• Stability — changes don't cascade
• Composability — works well with others

Weak interfaces show:

• Kitchen sink — unrelated methods bundled
• Leaky abstractions — implementation details exposed
• Unstable — frequent breaking changes
• Rigid — hard to extend or compose

Component Relationships

Relationship Types

Composition:

• Component owns sub-components
• Lifecycles coupled
• Strong cohesion
• Example: Page owns Header, Footer

Aggregation:

• Component references others
• Independent lifecycles
• Loose coupling
• Example: ShoppingCart references Product

Dependency:

• Uses another component's interface
• No ownership
• Can be swapped
• Example: AuthService uses Database

Association:

• Knows about but doesn't own
• Weak relationship
• Often bidirectional
• Example: User ↔ Post (many-to-many)

Coupling Analysis

Low coupling (good):

• Communicate through interfaces
• Few shared assumptions
• Changes localized
• Easy to test in isolation

High coupling (risky):

• Direct field access
• Shared mutable state
• Knowledge of implementation
• Changes ripple widely

Architectural Pattern Recognition

Layered Architecture

Indicators:

• Unidirectional dependencies (top → bottom)
• Each layer uses only layer below
• Clear separation of concerns

Trade-offs:

• ✓ Simple, well-understood
• ✓ Easy to enforce rules
• ✗ Can become rigid
• ✗ Performance overhead

Event-Driven Architecture

Indicators:

• Pub/sub or message queues
• Decoupled components
• Asynchronous communication
• Event sourcing patterns

Trade-offs:

• ✓ Scalable, resilient
• ✓ Loose coupling
• ✗ Harder to reason about flow
• ✗ Eventual consistency challenges

Microservices

Indicators:

• Service per bounded context
• Independent deployment
• API-based communication
• Decentralized data

Trade-offs:

• ✓ Independent scaling
• ✓ Technology diversity
• ✗ Distributed system complexity
• ✗ Operational overhead

Analysis Workflow

Top-Down

Start broad, narrow focus:

1. System boundaries — what's in scope?
2. Major components — high-level modules
3. Component interactions — how they communicate
4. Internal structure — zoom into each component
5. Implementation — code-level details

Bottom-Up

Start specific, build understanding:

1. Entry point — main(), server start, UI root
2. Call graph — trace execution paths
3. Cluster calls — group related functionality
4. Extract components — identify logical boundaries
5. Map relationships — connect the pieces

Targeted

Focus on specific concern:

1. Define question — what are you trying to understand?
2. Identify relevant code — where does this happen?
3. Trace dependencies — what does it touch?
4. Analyze impact — what would changing this affect?
5. Document findings — capture insights

Documentation Extraction

From architecture analysis, capture:

• Component diagram — boxes and arrows
• Dependency graph — what imports what
• Layer diagram — abstraction levels
• Sequence diagrams — interaction flows
• Decision records — why this structure?