location-reference-cache

Redis read tier for retail location reference data (location number 1–9999) with a four-level hierarchy (base division → region → market → site), read-through caching, stampede protection, Caffeine L1 hot keys, RabbitMQ invalidation, and rate limiting in front of a location MDM system of record.

Part of the Enterprise Platform Reference Architecture.

Hierarchy (exclusive ownership)

Base Division (01–04)
  └── Region (R1–R3)
        └── Market (M1–M6)
              └── Site (location number 1–9999)

Architecture

flowchart LR
  clients[Consumers] --> api[REST API]
  api --> l1[Caffeine L1 hot keys]
  l1 --> redis[Redis read-through]
  redis --> mdm[(Location MDM H2/Postgres)]
  mdm --> rabbit[RabbitMQ location.changed]
  rabbit --> inv[Invalidation listener]
  inv --> redis

Loading

Patterns demonstrated

Pattern	Implementation
Read-through cache	LocationReadThroughCache
Stampede guard	Redis SETNX lock + double-check
TTL jitter	StampedeGuard.jitteredTtl
Hot-key L1	Caffeine for configured location numbers
Event invalidation	RabbitMQ topic location.changed.#
Org roll-up invalidation	Redis SET org:{bd}:{region}:{market}:stores
Rate limiting	Redis sliding window per client

Run

mvn test
mvn spring-boot:run
curl -H "X-Client-Id: demo" http://localhost:8087/api/locations/1234
docker compose up --build
./scripts/demo.sh

API

Method	Path
GET	/api/locations/{locationNbr}
GET	/api/locations/{locationNbr}/org-path
GET	/api/locations/market/{bd}/{region}/{market}
POST	/api/admin/locations/{locationNbr}/simulate-change
POST	/api/admin/cache/warm

Documentation

• System design
• Industry applicability
• Business & governance: BRD · SOP · NFR · Cost savings
• ADRs: docs/adr/

Tech

Java 21, Spring Boot 3.3, Redis, Caffeine, RabbitMQ, H2/PostgreSQL, Maven, Docker.