API and Caching Standards

API & Caching Standards

Cache Pattern

const cache = new Map<string, { data: T; timestamp: number }>()
const CACHE_TTL = 300000 // 5 min default

function getCached(key: string): T | null
function setCached(key: string, data: T): void
export function invalidateCache(scope?: string): void

// API accepts skipCache param
export const fetch = async (id: string, skipCache = false): Promise<T>

TTL Guidelines

Type	TTL
Schema/FK graph	5 min
Metrics	2 min
Simulation results	5 min

Invalidation Rules

• Invalidate related caches together (FK → cascade → dependencies)
• Partial invalidation by ID when possible
• Expose invalidation functions as exports

Rate Limit Protection

• Retry with exponential backoff (2s, 4s, 8s) for 429/503/504
• Sequential processing with 300ms delays for batches
• Backend: parallel batches max 5-10 queries

Component Pattern

// Mount: use cache
useEffect(() => { void loadData(false) }, [id])

// Refresh button: bypass cache
<Button onClick={() => void loadData(true)}>Refresh</Button>

Backend Optimization

• Build indexes/lookups upfront before loops
• Lazy-load secondary data
• Early exit for edge cases