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	relations
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-02T02:20:58.504326+00:00	target type direction strength edge_id 1d64c80d-61ec-434f-902a-3a511e2b92c2 RELATED_TO outgoing 0.71 971778f6-4161-4ae3-be07-44f5e4645577 target type direction strength edge_id fc4eb194-1b19-4bb7-8b63-97ae30c8a3e0 RELATED_TO outgoing 0.72 a78f60a1-1597-4b18-835d-c6bc8d97c535 target type direction strength edge_id e5ec55be-ced4-4c30-8390-940b45dc2ed5 RELATED_TO outgoing 0.7 8e624197-1bd1-49cd-9082-437551829431 target type direction strength edge_id e1fad787-7de7-4f62-afb7-6df2ffdea1ed RELATED_TO incoming 0.9 4cbd5bef-19ad-4c61-b737-234618b32dba target type direction strength edge_id 27a1f728-ec90-469c-a6ab-5644d333322f RELATED_TO outgoing 0.7 a24de396-42d1-4311-af1b-0d3dbf6f8d7a target type direction strength edge_id a2d02aea-07fd-4528-8158-f2f42a23a2dd RELATED_TO incoming 0.5 b0015c81-b5ab-4972-8811-04dc5ddaebf4 target type direction strength edge_id 346c5a34-3fed-44ff-832a-b0c9eb42ca88 RELATED_TO incoming 0.8 fbf4a323-421b-4964-ba27-bffd66df6d69 target type direction strength edge_id e1fad787-7de7-4f62-afb7-6df2ffdea1ed REQUIRES outgoing 0.85 cb95feca-40ee-4cfb-af50-cd2e1b8844cd target type direction strength edge_id 1b71b163-b56f-4226-9731-a76ef245e532 RELATED_TO incoming 0.75 863714f3-635e-427a-a1fb-499b14b192e8

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.