Feat/290 last known good caching

ARCHITECTURE.md

@@ -144,9 +144,48 @@ enrichedTips (displayed to user)
 
 See `docs/PERFORMANCE_PROFILING.md` for measurement techniques.
 
-## Data Flow
+### API Resilience & Caching (Issue #290)
+
+Read-heavy views implement last-known-good caching to survive API outages:
 
-## Security Boundaries
+```
+Live API Request
+    |
+    v
+Fetch with timeout (10s)
+    ├─ Success?
+    │  ├─ Yes: Store in persistent cache → Return live data
+    │  │
+    │  └─ No: Timeout/error occurred
+    │         Check persistent cache
+    │         ├─ Cache found → Return cached data
+    │         └─ No cache → Return error
+    |
+    v
+User sees: live data OR cached data OR error
+UI shows:  freshness metadata + retry button (if cached)
+```
+
+**Features:**
+
+- **Persistent cache**: localStorage-backed, survives browser reload
+- **TTL management**: 2-5 minute caches per endpoint type
+- **Automatic fallback**: No code changes needed, transparent
+- **Freshness indicators**: Users shown data source and age
+- **Transaction lockout**: Risky actions disabled on stale data
+- **Pattern invalidation**: Related caches cleared on state change
+
+**Layers:**
+
+1. `persistentCache.js` - Low-level storage with TTL
+2. `useCachedData` - Generic hook for any fetch
+3. `cachedApiClient.js` - Transparent HTTP wrapper
+4. `FreshnessIndicator.jsx` - Visual feedback component
+5. `ResilienceContext.jsx` - Global coordination
+
+See `docs/LAST_KNOWN_GOOD_CACHING.md` for architecture and patterns.
+
+## Data Flow
 
 | Boundary | Trust Model |
 |---|---|

CHANGELOG.md

@@ -8,6 +8,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Changed
 
+- Added last-known-good caching for read-heavy surfaces (Issue #290):
+  - Persistent cache stores successful API responses with configurable TTL
+  - Automatic fallback to cached data when live APIs are unavailable or slow
+  - Visual freshness indicators show users whether they are viewing live or cached data
+  - Transaction operations locked when live data unavailable to prevent incorrect actions
+  - Strategic cache invalidation on state changes (tip-sent, profile-update)
+
 - Event feed pipeline refactored for scale and performance (Issue #291):
   - Implemented selective message enrichment: messages are now fetched only
     for visible/paginated tips instead of all tips, reducing API calls by ~90%
@@ -19,6 +26,33 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   - RecentTips component refactored to use new `useFilteredAndPaginatedEvents`
     hook, centralizing filter/sort/paginate logic and improving composability.
 
+### Added (Issue #290)
+
+- `frontend/src/lib/persistentCache.js`: localStorage-backed cache with TTL support,
+  metadata tracking, and statistics collection.
+- `frontend/src/hooks/useCachedData.js`: Generic hook for fetch with automatic
+  fallback to persistent cache on error or timeout.
+- `frontend/src/hooks/useCachedStats.js`: Platform stats-specific hook with
+  appropriate TTL and timeout settings.
+- `frontend/src/hooks/useCachedLeaderboard.js`: Leaderboard-specific hook with
+  extended cache TTL for aggregated data.
+- `frontend/src/lib/cachedApiClient.js`: Transparent fetch wrapper with automatic
+  response caching, timeout handling, and per-endpoint TTL configuration.
+- `frontend/src/lib/cacheInvalidationManager.js`: Utilities for pattern-based and
+  event-based cache invalidation to prevent stale data cascades.
+- `frontend/src/hooks/useTransactionLockout.js`: Hook for controlling transaction
+  availability based on data source (live/cache/none).
+- `frontend/src/context/ResilienceContext.jsx`: Global context for coordinating
+  cache invalidation and connection status monitoring across the app.
+- `frontend/src/components/FreshnessIndicator.jsx`: Visual component showing cache
+  status, data age, and retry button for manual refresh.
+- `docs/LAST_KNOWN_GOOD_CACHING.md`: Comprehensive guide covering architecture,
+  components, usage patterns, TTL guidelines, and troubleshooting.
+- `docs/MIGRATION_GUIDE_290.md`: Step-by-step integration guide for adding caching
+  to existing components with before/after examples.
+- Unit tests for persistent cache, cached data hook, cache invalidation, and
+  transaction lockout with edge case and integration coverage.
+
 ### Added (Issue #291)
 
 - `frontend/src/lib/eventCursorManager.js`: Opaque cursor-based pagination