architecture-lens

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.