Architecture Case Study
Architecture Decisions
Key architecture decisions, rationale and accepted trade-offs.
Decision 1 — Introduce an edge intermediary rather than scale the origin first
Context
Repeated read traffic was consuming shared backend capacity.
Options considered
- increase backend capacity;
- optimise each consumer independently;
- introduce a reusable intermediary caching/proxy layer.
Decision
Introduce an edge intermediary for suitable API reads.
Rationale
Scaling the origin would add capacity but would not address repeated processing of equivalent requests. Consumer-specific caching would duplicate logic and create inconsistent behaviour across applications.
A shared intermediary solved the repeated-work problem once while preserving the existing backend as the authority.
Trade-off
The architecture introduces another runtime component that must be operated and observed.
Decision 2 — Keep the backend authoritative
Decision
The edge layer may reuse responses, but it does not become the source of truth.
Rationale
Moving data ownership into the caching layer would expand scope significantly and create consistency/governance challenges that were not required to solve the delivery problem.
Trade-off
A cache miss still depends on origin availability and performance.
Decision 3 — Externalise endpoint policy
Decision
Cache enablement and selected freshness behaviour are controlled through configuration rather than hard-coded uniformly.
Rationale
Different endpoint types have different volatility and risk profiles. Configuration allows incremental adoption and safer operational tuning.
Trade-off
Configuration becomes an operational dependency and therefore requires validation and governance.
Decision 4 — Normalise request identity
Decision
Equivalent requests should resolve to a consistent cache identity regardless of irrelevant ordering differences.
Rationale
Without normalisation, semantically identical requests can fragment the cache and reduce effectiveness.
Trade-off
Identity rules must be designed carefully so that inputs which genuinely change the result are never collapsed incorrectly.
Decision 5 — Design for bypass and reversibility
Decision
The architecture includes ways to bypass caching or disable it for specific behaviours.
Rationale
A performance optimisation should not become an operational trap. Teams need a safe path back to authoritative origin behaviour when diagnosing issues or changing policy.
Trade-off
More control paths create more states to test and observe.
Decision quality
The decisions are intentionally tied to the original drivers: compatibility, efficiency, safe freshness, operability and incremental delivery. They are not technology choices in isolation.