Caching

WHEN_TO_USE

• When implementing a cache layer (in-memory, Redis, CDN) for an API or service.
• When choosing TTL values or invalidation strategies for cached data.
• When designing cache key schemas to avoid collisions or stale-data bugs.
• When reviewing code that reads from or writes to any cache.
• When debugging stale data, cache stampedes, or inconsistent responses.
• When configuring TanStack Query staleTime/gcTime for client-side caching.

INVALIDATION

• [P0-MUST] Define an invalidation strategy for every cache. Stale data is worse than no cache.
• [P0-MUST] Invalidate caches when the underlying data changes, do not rely solely on TTL expiry.
• [P1-SHOULD] Prefer event-driven invalidation (on write/update/delete) over time-based expiry alone.
• [P1-SHOULD] Use cache versioning (include a version key) when data schemas change.

TTL_GUIDELINES

• [P1-SHOULD] Set TTLs based on data volatility: static config (hours/days), user profiles (minutes), real-time data (seconds or no cache).
• [P1-SHOULD] Use stale-while-revalidate: serve stale data immediately while refreshing in the background.
• [P2-MAY] Use shorter TTLs in development and longer TTLs in production.

CACHE_KEYS

• [P0-MUST] Include all query parameters that affect the result in the cache key.
• [P1-SHOULD] Use a consistent key format: <entity>:<id>:<variant> (e.g., user:123:profile, products:list:page=2).
• [P1-SHOULD] Namespace keys by service or module to prevent collisions.
• [P2-MAY] Hash long or complex keys to keep storage efficient.

CACHE_LAYERS

• [P1-SHOULD] Use the appropriate cache layer for the use case: