claude-memory/graph/code-patterns/two-phase-cached-loading-pattern-for-api-heavy-screens-in-ru-77c0b8.md

id	type	title	tags	importance	confidence	created	updated
77c0b897-4124-432f-84de-700ff82dcde1	code_pattern	Two-phase cached loading pattern for API-heavy screens in Rust TUI	sba-scouting rust caching ratatui async tokio sqlx standings api pattern	0.8	0.8	2026-03-02T00:33:19.472159+00:00	2026-03-02T00:33:19.472159+00:00

Two-Phase Cached Loading Pattern

Context

Implemented for the standings screen in SBA Scout Rust TUI. Should be reused for other API-heavy screens.

Pattern

Phase 1: Instant cache load on mount

• Load from SQLite cache on mount() — instant display
• Cache table (standings_cache) stores JSON blob per season with fetched_at timestamp
• Show "updated Xm ago" indicator to user

Phase 2: Background refresh

• Spawn background tokio::task to fetch from live API
• Update DB cache after successful fetch
• Send StandingsRefreshed message back to UI via mpsc::UnboundedSender<AppMessage>
• Show spinner while refreshing

Key Implementation Details

• Use serde::Serialize on response types for JSON round-trip through DB (serde_json::to_string / from_str)
• Cache table needs: season (key), data_json (TEXT), fetched_at (DATETIME)
• Handle stale cache gracefully — always show cached data immediately, refresh in background

Critical API Shape Gotcha

The Major Domo CLI returns bare arrays, but the actual REST API wraps responses:

{"count": N, "standings": [...]}

Always verify real API response shape, not just CLI output. Mismatched deserialization will silently fail or panic.