Version 4.3.0 — Stability & Caching Layer

Release Date: 2025-02-20
Focus: React Query caching, REST spike prevention, documentation alignment

---

🔥 Summary

This release introduces a stability-focused layer on top of the existing Performance Optimization Edition.
The goal is to make data loading predictable and efficient by standardizing React Query caching rules, eliminating low-interval polling, and formalizing "no REST on hover / animation" as a core principle.

---

✨ Added / Changed

1. React Query Caching Rules

• Global Defaults (QueryClient):
  • staleTime: 30_000 ms (30 seconds) — data is considered fresh for dashboards and maps
  • gcTime: 60_000 ms (60 seconds) — cache is retained for quick back/forward navigation
  • refetchOnWindowFocus: false — no hidden refetch bursts when users switch browser tabs
  • refetchOnReconnect: false — avoids reconnect storms on flaky networks
  • refetchOnMount: false — no re-fetch on mount while data is still fresh
  • retry: 1 with exponential backoff for transient Supabase issues
• Per-hook Overrides:
  • Critical flows (e.g. live dashboards) can opt-in to shorter staleTime (5–10s), but must do so explicitly.

2. REST Spike Prevention

• No Low-Interval Polling:
  • Removed legacy 5-second polling for driver shipments in the Driver Dashboard.
  • Shipment lists now rely on:
    • Initial snapshot fetch
    • Supabase Realtime channel (per-driver shipments stream)
• No REST on Hover / Animation:
  • Confirmed and documented that:
    • FloorplanViewer (Lagerkarte) does not issue Supabase requests in onMouseMove, hover handlers, or panning/zoom.
    • Simulation hooks (useFloorplanSimulation, useWarehouseSimulation) are purely in-memory:
      • All ticks operate on local state derived from initial snapshots.
      • No Supabase / HTTP calls are made from simulation tick loops.
• Event-Driven Fetching Only:
  • Data-loading logic is tied to:
    • Explicit toggles (e.g. enabling overlays)
    • Route / floorplan selection
    • Realtime events and targeted React Query invalidations
  • No fetches are triggered directly from render cycles.

3. Stability Layer Principles (Documented)

• New documentation sections describe the stability layer:
  • Snapshot-first: Prefer get-dashboard-snapshot-v2 and other aggregated endpoints for dashboard views.
  • Cache-first: Use React Query caches and IndexedDB before hitting Supabase again.
  • Realtime over Polling: Use Supabase Realtime for high-frequency updates, with polling only as a slow fallback.
  • No REST on Hover / Animation: Hover and animation code paths must never trigger network calls.
  • Simulation is Local: All movement / visualization simulations operate on local state.

4. Documentation Alignment

• Updated VitePress documentation to match the current stability layer:
  • Architecture Guide: Clarified multi-layer caching and React Query defaults (30s / 60s).
  • Performance Optimization Guide: Documented the stability rules, React Query configuration, and realtime strategy.
  • Changelog: Added v4.3.0 entry and updated version history to include the 4.x series.

---

🧩 Compatibility & Scope

• Additive Only:
  • No schema changes.
  • No business logic changes to inventory, safety, or workflows.
  • No UI layout or theme changes.
• Focus:
  • Stability, caching, and REST behavior only.

---

🚀 Migration Notes

1. React Query Defaults

   • If you previously relied on refetchOnWindowFocus behavior, switch to:
     • Explicit queryClient.invalidateQueries(...) on relevant actions, or
     • Per-hook overrides (refetchOnWindowFocus: true) where truly required.

2. Polling

   • Do not re-introduce high-frequency polling (< 30s) for any view.
   • If realtime is unavailable, prefer:
     • Snapshot-based reload buttons, or
     • Low-frequency polling (30–60s) with clear comments.

3. New Development

   • When adding new modules:
     • Reuse existing React Query client and key factories.
     • Follow the stability layer principles described in the Performance guide.

---

📚 Related Documentation

• Latest Changelog
• Performance Optimization Guide
• Architecture Overview
• Dashboard Snapshot v2