adr.zone

ADR Example: Redis for application read-through cache (Outcome-First 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.

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

ADR-0028: Use Redis for short-lived application caching

Status

Accepted

Outcome

Lower tail latency on hot read paths without making the database a de facto cache with unclear invalidation.

Decision

Use Redis for short-lived, TTL-bound read-through caching on approved endpoints. Redis is not a system of record: on miss or eviction, the authoritative store is read.

Primary tradeoff

We accept Redis as an additional runtime dependency and treat cache invalidation as a correctness concern requiring review.

Why

  • Hot read paths repeat the same queries against primary storage
  • Redis is already deployed for session and rate limits
  • SRE has failover playbooks for Redis

Decision boundaries

Impacted:

  • API read hot paths (approved routes)
  • Redis cluster namespace conventions
  • Code review standards for cache-correctness

Not impacted:

  • Write paths (remain authoritative in primary store)
  • Non-approved routes
  • Session and rate-limit use cases (already separate)

Assumptions:

  • TTL-bound data is acceptable for approved routes
  • Miss/eviction paths stay correct by reading the authoritative store

Guardrails:

  • Cache keys must include all dimensions that affect correctness (tenant, flags, etc.)
  • Memory cap and naming convention enforced
  • Flush runbook maintained for regional incidents
  • New cached routes require SRE sign-off before prod