Future Edge Cache Playbook
A working note for using edge cache, static fallbacks, and stale-while-revalidate around a personal website system.
Edge cache should make nhwwnhww.xyz faster and calmer without hiding stale data risks: public notes and photos can cache aggressively, while private dashboards and project logs need clear freshness boundaries.
# Future Edge Cache Playbook
## Context
The personal site is becoming a small system rather than a single brochure page. [[personal-website-as-operating-system]] now includes public notes, photography, private finance tools, project evidence, and automation outputs.
That makes cache behavior a product decision. A visitor reading the Digital Garden should get a fast page even if the origin is cold. An admin checking an ETF import should see freshness and fallback state clearly. A Codex-driven maintenance loop such as [[codex-product-production-loop]] should leave enough metadata for future deployments to know what can be cached and what must stay live.
## Problem
Without an edge cache strategy, the site can become fragile in two opposite ways.
- Too little cache makes every read depend on the origin, local service, or upstream provider being healthy.
- Too much cache hides stale garden notes, old photo metadata, finance snapshots, or project logs after an update.
- Static fallback pages can help crawlers and no-JavaScript readers, but they must be regenerated when public notes change.
- Private or admin-only data must not leak through public cache keys.
The hard part is not turning cache on. The hard part is deciding which surfaces are safe to serve stale, which ones need revalidation, and which ones must never be cached publicly.
## Pattern
Use different cache behavior for different information zones.
| Surface | Cache shape | Revalidation rule |
| --- | --- | --- |
| Digital Garden public notes | Static fallback plus edge cache | Rebuild on note changes; allow stale public HTML briefly. |
| Photography Archive | Cache image assets and public album metadata | Long cache for immutable assets; shorter cache for album indexes. |
| ETF Dashboard | Private API responses with explicit freshness state | Do not public-cache account data; show live, cached, or degraded status. |
| Project Logs | Public summaries only, not raw private logs | Cache published summaries; keep source logs private. |
`stale-while-revalidate` is useful when old public content is better than a slow or broken page. It is risky when old data looks like a fresh account balance, provider quote, or admin action result. The cache contract should be visible in the product surface, not buried in deployment config.
## Current Implementation
The current site already has pieces of this pattern.
- The Digital Garden generates a public index, RSS, JSON feed, sitemap, and static HTML fallbacks during build.
- [[digital-garden-auto-update]] keeps generated candidates in the inbox until review, which prevents unapproved text from entering public cache outputs.
- [[cloudflare-r2-d1-pages]] is the infrastructure direction for static hosting, object storage, and lightweight metadata.
- [[photography-archive-system]] naturally fits long-lived image caching, especially when album assets are immutable.
- [[etf-portfolio-dashboard]] needs a stricter private-data boundary: provider status and cache freshness can be shown, but account data should not become public edge content.
The practical rule is simple: public generated artifacts can be cached after `npm run build`; private inbox, admin, finance, credentials, and raw project logs should stay behind authenticated APIs or local-only workflows.
## Next Iteration
The next useful version is a small cache playbook checked into the repo:
1. Define cache headers for public garden HTML, feeds, and static assets.
2. Separate immutable photo assets from mutable album metadata.
3. Add freshness labels to finance API responses and UI cards.
4. Keep project logs as private evidence and publish only reviewed summaries.
5. Add a build-time check that public outputs do not reference the private garden inbox folder, private logs, tokens, or admin-only paths.
This note should stay close to the operating rule: edge cache is useful when it makes public knowledge and media resilient, but dangerous when it makes private or time-sensitive data look current.
## Recent Update - 2026-W26
[[weekly-review-2026-w26]] is the first weekly note to depend on this cache boundary. The practical next step is to verify actual deployment behavior before turning this seed into headers, cache durations, or provider-specific Cloudflare rules.
Open this garden note