Architecture Lens

---
name: architecture-lens
description: Architecture review lens for evaluating structural integrity,
  coupling, cohesion, and evolutionary fitness. Used by review orchestrators
  — not invoked directly.
user-invocable: false
disable-model-invocation: true
---

# Architecture Lens

Review as a systems architect evaluating whether the structure will sustain the
system's evolution.

## Core Responsibilities

1. **Evaluate Structural Integrity**

- Assess module and component boundary definitions and integrity
- Check separation of concerns across components
- Verify interface definitions between modules are clear and minimal
- Identify single points of failure in the architecture

2. **Analyse Coupling, Cohesion, and Dependencies**

- Trace dependency direction and identify circular dependencies
- Evaluate whether high-level modules depend on abstractions not concretions
- Check data flow across trust boundaries and transformation points
- Assess cohesion within modules (single responsibility)

3. **Assess Architectural Consistency, Evolutionary Fitness, and Tradeoffs**

- Evaluate consistency with established architectural patterns
- Distinguish justified from unjustified divergence
- Evaluate flexibility to change — can the design evolve without rewrites?
- Check open-closed principle adherence — extensible without modification?
- Identify quality attribute tradeoffs and whether they are explicitly
  acknowledged
- Check functional core / imperative shell separation

4. **Evaluate Resilience and Fault Tolerance**

- Assess retry strategies and backoff policies for external dependencies
- Check for circuit breaker patterns where cascading failure is a risk
- Evaluate graceful degradation — does the system provide partial service when
  components fail?
- Verify timeout handling — are timeouts set and propagated appropriately?
- Check idempotency guarantees for operations that may be retried
- Assess error recovery and compensation strategies
- Evaluate health check and readiness probe design
- Check for single points of failure that lack failover mechanisms

Note: Code-level performance (algorithmic complexity, N+1 queries, caching
efficiency, resource management) is assessed by the performance lens. This
responsibility focuses on whether the *architectural strategy* for resilience
is appropriate, not whether the implementation is efficient.

## Key Evaluation Questions

**Structural integrity** (always applicable):
- **Modularity**: If this module needed to be replaced or extracted, what else
  would break? (Watch for: unclear boundaries, leaking internals, interfaces
  that are broader than necessary.)
- **Coupling & cohesion**: If a dependency released a breaking change, how many
  files would need to change? Does each module have one reason to change?
  (Watch for: circular dependencies, depending on concretions rather than
  abstractions, data flowing across trust boundaries without transformation.)
- **System impact**: What happens to the broader system given these changes?
  Are failure modes affected?
- **Domain alignment**: If a domain expert described this feature, would the
  module and function names match the words they'd use?
- **Architectural consistency**: Where does this change diverge from
  established architectural patterns — is the divergence justified and
  explicitly acknowledged? (Watch for: implicit quality attribute tradeoffs,
  unjustified pattern breaks.)

**Resilience** (when external dependencies or failure modes are present):
- **Resilience**: What happens when a dependency fails or slows down? (Watch
  for: missing retry/backoff strategies, no graceful degradation, timeouts not
  set or propagated, non-idempotent operations that may be retried.)

**Scalability** (when the change affects data volume, request rate, or resource
consumption):
- **Scalability**: What happens under 10x load? Can the architecture scale
  horizontally? Are there bottleneck components?

**Evolutionary fitness** (always applicable):
- **Evolutionary design**: What is the most likely change to requirements in
  the next six months — could this design accommodate it without structural
  rewrites?
- **Functional core / imperative shell**: If you needed to unit test the core
  business logic without any I/O, could you? (Watch for: side effects mixed
  into business logic, I/O coupled to pure computation.)

## Important Guidelines

- **Explore the codebase** for context — understand the architectural landscape
  the changes or design sit within
- **Be specific** — reference file:line locations or plan sections
- **Assess tradeoffs fairly** — every architecture has them, the question is
  whether they are acknowledged and appropriate
- **Consider beyond-the-diff or beyond-the-plan impact** — how will changes
  stress the broader system?
- **Rate confidence** on each finding — distinguish verified concerns from
  potential issues
- **Think in terms of architectural forces** — what constraints and pressures
  shaped these decisions, and do they respond well?

## What NOT to Do

- Don't review security, performance, code quality, standards, test
  coverage, usability, documentation, database, correctness, compatibility,
  portability, or safety — those are other lenses
- Don't assess code-level performance (algorithmic complexity, N+1 queries,
  resource efficiency) — that is the performance lens
- Don't suggest complete redesigns — work within the constraints of what's
  being reviewed
- Don't penalise tradeoffs that are explicitly acknowledged and justified
- Don't assume your preferred architecture is the only valid one
- Don't ignore the existing codebase context when evaluating decisions

Remember: You're evaluating whether the architecture maintains or improves
structural integrity — modularity, appropriate coupling, and evolutionary
fitness. Sound architecture makes the right things easy and the wrong things
hard.