Architecture Review

Architecture Review

Identify primitives. Draw black boxes. Wrap dependencies.

Core principle: "It's faster to write five lines of code today than to write one line today and then have to edit it in the future." - Eskil Steenberg

When to Use

Always use for:

• Planning new modules or subsystems
• Major refactors affecting 3+ files
• Adding external dependencies
• Code that "works but feels tangled"
• Pre-review of architectural decisions

Skip for:

• Bug fixes within existing architecture
• Adding features to well-defined modules
• Configuration changes

The Four-Phase Review

Phase 1: Primitive Identification

Find the fundamental data types that flow through the system.

Questions to answer:

1. What is the basic unit of information?
2. What operations are performed on this data?
3. Can this primitive handle future requirements without change?

Examples by domain:

Web service:
- Request (method + path + headers + body)
- Response (status + headers + body)
- User (id + credentials + permissions)

Data pipeline:
- Record (schema + values + metadata)
- Transform (input_type → output_type)
- Batch (records + timestamp + source)

Checklist:

• List all data types that cross module boundaries
• Each primitive has clear, minimal definition
• Primitives are stable (won't need frequent changes)
• Operations on primitives are well-defined

Phase 2: Black Box Boundaries

Every module should be replaceable using only its interface.

The test: Can you describe this module to a new developer using ONLY:

• What goes in (inputs)
• What comes out (outputs)
• What guarantees it provides

Checklist:

• Each module has explicit input/output types
• Internal implementation details are hidden
• Interface is documented without reference to internals
• Module can be rewritten without touching callers

Red flags:

# BAD: Leaky abstraction
class DataProcessor:
    def process(self, data):
        self._internal_buffer.append(data)  # Caller knows about buffer
        return self._cached_results[-1]  # Caller knows about caching

# GOOD: Clean interface
class DataProcessor:
    def process(self, data: InputType) -> OutputType:
        """Processes data and returns result."""
        ...  # Implementation hidden

Phase 3: Dependency Audit

Never depend directly on what you don't control.

External dependencies to wrap:

• Third-party libraries (pandas, requests, boto3)
• Platform APIs (file system, network)
• Data sources (databases, APIs, message queues)
• Configuration systems

Checklist:

• External libraries accessed through wrapper layer
• No direct imports of external APIs in business logic
• Wrappers have stable interfaces even if underlying changes
• Dependencies can be swapped without touching core code

Example wrapper pattern:

# platform/storage.py - Wrapper layer
from typing import Protocol

class StorageProtocol(Protocol):
    """Our interface - stable even if S3/GCS/local changes."""
    def read(self, key: str) -> bytes: ...
    def write(self, key: str, data: bytes) -> None: ...

# Business logic imports from wrapper, not boto3 directly
from platform.storage import StorageProtocol

Phase 4: Replaceability Test

For each component, answer:

Checklist:

• Single developer can own each module
• Failure in one module doesn't cascade
• Clear boundaries enable parallel development
• Future features fit existing structure

Architecture Patterns

Good Architecture

┌─────────────────────────────────────────────────────────┐
│  External Layer (wrapped)                               │
│  └─ APIs, databases, file systems, third-party libs    │
├─────────────────────────────────────────────────────────┤
│  Service Layer (primitives: request → response)         │
│  └─ Each service is independent black box              │
├─────────────────────────────────────────────────────────┤
│  Domain Layer (primitives: input → output)              │
│  └─ Business logic, pure functions where possible      │
├─────────────────────────────────────────────────────────┤
│  Infrastructure Layer (wrapped)                         │
│  └─ Logging, metrics, configuration                    │
└─────────────────────────────────────────────────────────┘

Bad Architecture Signs

• Lower layers import from upper layers
• Business logic depends on specific infrastructure
• Business logic scattered across layers
• "Utility" modules used everywhere
• Circular imports

Quick Reference

Common Rationalizations

Integration with Plan Agent

When using plan agent for architecture design:

1. Run architecture review FIRST
2. Identify primitives and boundaries
3. Let plan agent design within those constraints
4. Review plan output against this checklist

Output Format

After review, document:

## Architecture Review: [Component/System Name]

### Primitives
- [List with definitions]

### Module Boundaries
| Module | Input | Output | Responsibility |
|--------|-------|--------|----------------|

### Dependency Map
- External: [wrapped/unwrapped status]
- Internal: [dependency direction]

### Risks
- [Identified architectural risks]

### Recommendations
- [Concrete changes needed]