docs: add cache proposal for background renewal

Co-authored-by: aider (openrouter/thinkingmachines/inkling-small:free) <aider@aider.chat>

docs/cache-proposal.md

@@ -0,0 +1,39 @@
+# Cache Proposal for Kubectl Web GUI
+
+## Problem
+With ~1600 pods, loading full lists from kubectl is slow. We need backend caching with background renewal so users are not blocked.
+
+## Ideas
+
+### 1. In-Memory TTL Cache with Background Refresh
+- Store parsed item lists in a Python dict with 5-minute TTL.
+- A background thread (threading.Timer or asyncio) refreshes each resource type every 4 minutes.
+- Users always read from memory; refresh is invisible.
+
+### 2. Stale-While-Revalidate Pattern
+- Serve cached data immediately.
+- If cache is older than 3 minutes, trigger a background kubectl call to update it.
+- User gets fast response; data updates shortly after.
+
+### 3. Per-Resource Background Workers
+- One lightweight thread per resource (pods, nodes, pvcs, configmaps).
+- Each thread runs kubectl on its own interval (e.g., 4 min).
+- Cache is always warm; no user request triggers kubectl unless bypass is used.
+
+### 4. Cache Invalidation on Actions
+- After delete/cordon/uncordon, invalidate only that resource's cache.
+- Next load will refresh just that resource, not all.
+
+### 5. Partial / Chunked Cache
+- Cache full list but paginate in backend.
+- Background refresh updates the full list; pagination stays fast.
+
+## Background Renewal Approach
+- Use threading.Thread with a loop and time.sleep(240) per resource.
+- Or use FastAPI startup event to spawn refresh tasks.
+- Ensure thread-safe access to the shared cache dict (GIL helps, but use locks if needed).
+
+## Trade-offs
+- Memory usage: ~1600 pods is small; acceptable.
+- Staleness: 4-5 minutes is okay for a local GUI.
+- Refresh impact: background only, so app stays responsive.