​

OdontoX Cache & Storage Strategy

​

TL;DR

​

The 5-tier mental model

• Auth tokens → either httpOnly cookies (best, server-controlled) or T2 sessionStorage (acceptable, tab-scoped). Never T3. XSS bypasses any T3-stored token in seconds.
• PHI (patient names, MRNs, phone numbers, diagnoses, clinical notes) → T1 only, never T2/T3/T4. HIPAA-style audits look for “data at rest on the device” and persistent storage qualifies even on a personal machine.
• Clinic ID pointer (“which clinic is the user currently working in”) → T3 is fine because losing it is annoying, not dangerous. But it must be the only source of truth — never duplicate it into URL params.
• Anything mentioned in the URL → URL is canonical, everything else is a hint. If the URL says ?clinic=A and localStorage says B, the URL wins.

​

TanStack Query: the staleTime/gcTime rules

useQuery({
  queryKey: qk.invoices.list(clinicId),
  queryFn: fetchInvoices,
  staleTime: 0,
  gcTime: 60_000,
  meta: { noPersist: true },  // never write to localStorage
});

persistQueryClient({
  queryClient,
  persister,
  maxAge: 1000 * 60 * 60,        // 1h (down from 24h)
  buster: __BUILD_HASH__,
  dehydrateOptions: {
    shouldDehydrateQuery: (q) =>
      q.state.status === 'success' && !q.meta?.noPersist,
  },
});

​

The localStorage rules

​

Keys that should move OUT of localStorage

​

Keys that are fine where they are

​

A wrapper to use going forward

// ui/src/lib/storage.ts
interface StoredValue<T> {
  v: 1;                  // schema version — bump to invalidate old data
  exp?: number;          // optional expiry epoch ms
  data: T;
}

export function setStored<T>(key: string, data: T, ttlMs?: number) {
  try {
    const payload: StoredValue<T> = { v: 1, data };
    if (ttlMs) payload.exp = Date.now() + ttlMs;
    localStorage.setItem(key, JSON.stringify(payload));
  } catch { /* Safari private mode, quota — silent */ }
}

export function getStored<T>(key: string): T | null {
  try {
    const raw = localStorage.getItem(key);
    if (!raw) return null;
    const parsed = JSON.parse(raw) as StoredValue<T>;
    if (parsed.v !== 1) { localStorage.removeItem(key); return null; }
    if (parsed.exp && parsed.exp < Date.now()) { localStorage.removeItem(key); return null; }
    return parsed.data;
  } catch { return null; }
}

1. Schema versioning — bumping v invalidates every prior value, no migration needed.
2. TTL — caller decides expiry per key; no separate “what’s stale” tracking.
3. Crash-safety — every read is wrapped in try/catch; corrupted JSON returns null instead of throwing.

​

Multi-tab coordination (currently missing)

useEffect(() => {
  const bc = new BroadcastChannel('odontox-sync');
  bc.onmessage = (e) => {
    if (e.data?.type === 'clinic-switched' || e.data?.type === 'logout') {
      queryClient.clear();
      window.location.reload();
    }
  };
  return () => bc.close();
}, []);

// in setActiveClinicId()
new BroadcastChannel('odontox-sync').postMessage({ type: 'clinic-switched' });

// in logout flow
new BroadcastChannel('odontox-sync').postMessage({ type: 'logout' });

​

URL state vs storage state

• View toggles (?view=appointments, ?tab=billing) → URL, not localStorage. A reception staffer who refreshes mid-shift should land where they were.
• Search queries (e.g., patient search box) → URL (?q=...) so back/forward works.
• Active clinic ID → localStorage (T3) because it’s not in the URL today; if you ever add clinic.odontox.io/... subdomain routing, the subdomain becomes canonical.

​

Module-by-module verdict and action items

​

Migration plan — three batches, lowest risk first

​

Batch 1 — Low-risk wins (half-day, no schema/server changes)

1. Write ui/src/lib/storage.ts wrapper (the snippet above) and migrate the safe keys to use it. No behavior change, but every read gets schema-version + try/catch for free.
2. Add meta.noPersist flag support to the QueryClient persister (the dehydrateOptions.shouldDehydrateQuery filter).
3. Tag finance, treatment-plan, and patient-list queries with meta: { noPersist: true }. Drop persister maxAge from 24h to 1h.
4. Drop odontox-patient-picker-recent writes. Replace the “recent patients” feature with a server endpoint (e.g., GET /patients/recent?userId=...) cached in T1 only — that data lives on the server anyway and avoids PHI-at-rest entirely.

​

Batch 2 — Multi-tab + impersonation cleanup (half-day)

5. Add the BroadcastChannel sync in App.tsx. Wire clinic-switched and logout broadcasts.
6. Move impersonation_original_token and impersonation_user_email to sessionStorage-only. Delete the localStorage fallbacks.
7. Make logout proactively bc.postMessage({type:'logout'}) so every tab knows.

​

Batch 3 — Auth tokens to httpOnly cookies (full day, needs server work)

8. Server: switch sign-in to set httpOnly + Secure + SameSite=Lax cookie. Add /api/v1/protected/me to read the current user from the cookie.
9. Frontend: fetchWithAuth stops reading from localStorage; trust the browser to attach the cookie. Drop auth_token and odontox_rt writes.
10. Logout: server clears the cookie via Set-Cookie: ...; Max-Age=0. Frontend just calls the endpoint.
11. Migration window: support both for one release, then remove localStorage reads.

​

Out of scope (later, if real signal exists)

• IndexedDB — overkill for current data shapes; only consider if we go offline-first.
• Service worker — adds a whole new failure mode (stale shell). Skip until there’s a real offline use case.
• Server-pushed cache invalidation (SSE cache-invalidate events) — nice-to-have but not blocking.

​

Quick “does this break things?” checklist for future caching changes

• If the data has a patient name, MRN, phone, or clinical detail → it does NOT go to T3/T4.
• If the data is an auth token → it does NOT go to T3.
• If the data is shown in the URL → URL is canonical, storage is a hint at best.
• If the data is shared across tabs (clinic switch, logout) → BroadcastChannel notifies.
• If the data has a hard freshness need (money, schedule, in-progress treatment) → meta.noPersist AND short staleTime.
• If the data is reference/admin-curated → persist freely, long staleTime is fine.
• If you’re using JSON.parse → it’s wrapped in try/catch.
• If you’re storing a value that might be missing later → null-check before assuming shape.

​

What you don’t need to do

• The TanStack Query setup is sound; the issue is what gets persisted, not the library choice.
• The clinic-scoped query keys are working; no need to redesign the key shape.
• The build-hash buster is doing its job; deploys do invalidate stale persisted data.
• The custom hooks (useLocalStorage, useRolePersistedState) already have try/catch — keep using them.
• No service worker means no offline staleness — that’s a feature, leave it.