adr.zone

ADR Example: Redis for application read-through cache (ISO 42010 Companion format)

A concrete architecture decision example for using Redis to shave latency on hot read paths while keeping the relational store the source of truth. Below is the same decision in Nygard, MADR, Y-Statement, Outcome-First, or ISO 42010 Companion—use the format toggle to compare structure, not just wording.

Last reviewed: .

When this type of decision shows up

  • You repeat the same read queries and need bounded TTL-based caching, not a second system of record.
  • You already run Redis for adjacent workloads and can reuse operational playbooks and failover practice.
  • Reviewers need cache invalidation and key design treated as correctness, not a performance afterthought.

Format

Preview

Use Redis for short-lived application caching

ISO 42010 Companion — an architecture decision companion using ISO/IEC/IEEE 42010 vocabulary. Not a standard ADR format or conformity template—use it to connect stakeholders, concerns, views, and traceability to a related decision.

Record ID (cross-ref): ADR-42010-0028

System / subject scope

Public API tier, Redis cluster shared with session use cases, primary relational store as authority.

Stakeholders and roles

API teams, SRE, DB owners, security for key material if any.

Stakeholder concerns (to be addressed in the architecture description)

Latency, cost of repeated reads, correctness on eviction, security of cache key namespaces.

View and viewpoint (what is shown, and from which perspective)

Viewpoint: runtime / performance. View: per-route caching policy, Redis namespaces, and failure degradation paths.

Decision

Place a Redis-backed read-through cache for TTL-bound data where routes are allowlisted. Authoritative state remains in the primary database; eviction and miss paths must be correct.

Rationale (with respect to the concerns and alternatives)

The architecture description for request handling should show where acceleration exists without pretending Redis is a store of record. Concerns: speed vs staleness; mitigations: TTL, key design, and runbooks for flush.

Architectural impact (elements, relationships, and operational follow-through)

Code paths add cache get/set; metrics for miss/hit; load tests for Redis down scenarios.

Traceability (requirements, policy, SLOs, other ADRs)

SRE runbook for Redis; ADR for next cache allowlist change.

Before accepting your caching decision

This is an illustrative ADR. Check these assumptions in your own system rather than treating the sample's Accepted status as a recommendation for every workload.

  • Define which reads may be stale and for how long. TTL limits entry lifetime; it does not replace a policy for updates and invalidation.
  • Include tenant, authorization scope, and other result-changing inputs in cache keys. Test that one tenant cannot receive another tenant's cached result.
  • Test misses, eviction, and Redis outages against the authoritative database. Decide how to bound database load when the cache is unavailable.
  • Assign an owner for memory limits, hit-rate and latency monitoring, invalidation, and the emergency flush runbook before accepting the decision.

Use the worked MADR guide to compare the alternatives, then add the accepted record to your decision-log index.