The caching layers

In 1 minute

The events list is the most-read query, so three caches sit in front of Postgres: the browser’s React Query cache, the web server’s data cache and the API’s Valkey cache. Each keeps a copy for about 30 seconds. When an event is created or booked, the API clears Valkey at once and then tells the web server to clear its cache. So a change shows in milliseconds, not minutes.

Picture it

flowchart TB
  B["browser<br/>React Query, 30 s"] --> W["web data cache<br/>30 s, tag events"]
  W --> V["Valkey events cache<br/>soft 30 s, hard 300 s"]
  V --> PG[(Postgres)]
  API["API, after a change commits"]
  API -.->|"2. POST /api/revalidate"| W
  API -.->|"1. bump generation"| V

How it works

1. Cache-aside. The API looks in Valkey first. On a miss it reads Postgres and stores the copy. The log line says fresh, stale, miss or error.
2. Soft and hard age. After about 30 s (plus random jitter) a copy is stale: one request rebuilds it under a 5 s lock while the others get the stale copy. After 300 s it is deleted.
3. Clear by generation. A change bumps one counter, events:upcoming:gen. Every key contains the generation, so all old keys are ignored at once and expire by themselves.
4. Clear the web cache. The API then calls the web server’s POST /api/revalidate with the shared secret, which drops every list tagged events.

In MiniTickets

The Valkey side is apps/api/src/queries/events-cache.ts → getUpcomingFromCache, driven by apps/api/src/services/events.ts → listUpcomingEvents. The web side is apps/web/src/features/events/server/cached-events.ts.

Each Valkey call gives up after 100 ms, so a slow Valkey falls through to Postgres instead of slowing every page. If Postgres fails, an old copy is served (stale-if-error).

Measured locally: with the revalidate call, a new event was in the server HTML after 8-68 ms; without it, after about 30 s. A change nothing clears took 90.6 s, because each layer can refresh from a stale copy below it. HTML pages and API answers send no-store, so no shared cache keeps them.

From → to	What happens	What allows it
API app → Events list cache	events.list asks the cache first	code services/events.ts listUpcomingEvents → queries/events-cache.tslistUpcomingEvents
Events list cache → ElastiCache Valkeyonly when dataEnabled = true	the cached lists and the generation key	code queries/events-cache.ts: GET/SET with PX, 100 ms timeoutgetUpcomingFromCache

See the events cache on the map →

See it in AWS

Console

The cache is keys in Valkey, not a console page. The API log’s request lines carry the cache field.

CLI

aws logs tail /minitickets/dev/api --since 10m --filter-pattern cache

Code

The revalidate route: apps/web/src/app/api/revalidate/route.ts → POST.

Break it

Symptom	Cause	Where to look
A new event shows only after ~30 s	The revalidate call failed	API log: revalidate warnings
Many cache error lines, Postgres load rises	Valkey slower than 100 ms	ElastiCache metrics
Web log: 401 on /api/revalidate	The two tasks hold different secrets	Restart both services

Say it in an interview

Say it like this (20-30 seconds)

The events list has three cache layers: React Query in the browser, the Next.js data cache on the web server and a cache-aside copy in Valkey, each about 30 seconds. Writes commit first, then bump a generation counter in Valkey and call a revalidate hook on the web server. Stale copies are rebuilt by one request under a lock to prevent a stampede, and a 100 ms Valkey timeout keeps a slow cache from slowing the site.

Follow-ups

What is a cache stampede, and how is it stopped?

When a popular entry expires, every request misses at once and hits Postgres. Measured before the fix: 100 requests made 100 database queries; after it, 1. Only the lock holder rebuilds; the others serve the stale copy.

Why bump a generation instead of deleting the key?

There is one key per filter. Deleting means finding them all. One INCR moves every filter to a new, empty key at once, and a reader that started before the change can never write old data back under the new generation.

Why commit first and invalidate second?

The other order leaves a gap: a reader could refill the cache from the old data before the commit. Write, then invalidate, so the next miss reads the new data.

What is the trade-off of clearing on every booking?

Every booking empties every cached list. With many bookings per second almost every read would be a miss. Fine at our traffic; later, seat counts could be cached apart from the list.

Advanced: Keys and versions

A key looks like events:upcoming:v3:g7:<16-hex hash of the filters>. v3 is the shape version: a deploy that changes the cached value bumps it, so new code never reads old-shaped data. The hash keeps keys short and free of special characters. Search results are not cached in these layers; each search text would make its own key.

Checkpoint

Answer these without scrolling up. If one feels hard, reread that section.

1. Name the three caches in front of Postgres for the events list.
2. What is the difference between the soft and the hard age?
3. How does one write clear every filter’s key at once?
4. What happens when Valkey answers slower than 100 ms?
5. Why can a change that nothing clears take longer than 30 + 30 seconds?

Redraw it from memory: browser → web data cache → Valkey → Postgres, and the two arrows that clear them

Try this: on the map, play the sale-day flow and open the failure branch of the events cache step

Mark this page as read