"/home/yossef/notes/git/projects/maplibra/decisions/Caching Strategy.md"

path: maplibra/decisions/Caching Strategy.md

- **fileName**: Caching Strategy
- **Created on**: 2026-06-16 00:48:42

Caching Strategy

Purpose: How the app caches MVF data and derived routing assets to avoid re-building on every open.

Related: ../Home.md, ../Architecture.md, ../modules/Asset System.md, ../modules/MVF Loading.md, ../flows/Startup Sequence.md

Decision

Use a two-tier cache: IndexedDB for large payloads (MVF data, routing graphs) and localStorage for small metadata (cache keys, meta index, user preferences).

Rationale

1. IndexedDB is the only browser storage suitable for megabytes of binary data
2. localStorage is fast for small lookups but has a 5MB limit
3. Cache API (service worker cache) is used for HTTP fetch caching but not for structured data
4. SHA-256 hashing ensures cache entries are keyed by content, not filename
5. Schema versioning prevents stale cache reads after app updates

Tier 1: IndexedDB (Derived Asset Cache)

• Database: mvf-derived-assets
• Store: assets (keyPath: key)
• Cache key format: derived-v2:<SHA-256>:<optionsKey>
• Entry structure: { key, assets, mvf, createdAt, updatedAt, meta }
• Assets serialization: JSON objects and ArrayBuffers stored as { json } or { buffer } maps
• Size limit: No explicit limit, but meta index is capped at 100 entries

Tier 2: localStorage (Meta Index)

• Key: mvf-cache-meta-index — maps file metadata to cache keys
• Key: mvf-latest-cache-key — hints the most recently used cache entry
• Key: inguide-theme — user theme preference
• Key: mappedin_layer_visibility — debug layer legend toggle states
• Key: floor storage key — last selected floor per building

Tier 3: Cache API (HTTP Fetch)

• Cache name: mvf-bundles
• Usage: Caches fetch responses for MVF ZIP URLs
• Lifetime: Controlled by browser; app does not manage it directly

Cache Lookup Flow

1. Parse startup source (URL, file, or cache)
2. Build sourceIdentityKey from URL, file name, size, or offline package ID
3. Check localStorage meta index for a matching cache key
4. If miss, scan IndexedDB entries and refresh the index
5. Verify CACHED_MVF_SCHEMA_VERSION matches the current app
6. Deserialize assets and return

Cache Write Flow

1. After MVF load and derived asset build, serialize assets
2. Write { key, assets, mvf, meta } to IndexedDB
3. Update localStorage meta index
4. Set mvf-latest-cache-key if both assets and MVF are present

Schema Versioning

• CACHED_MVF_SCHEMA_VERSION is incremented when the MVF cache structure changes
• Old schema entries are rejected with a user-friendly error: "Cached map data was created by an older version."
• This forces the user to re-upload or re-download the map

Memory vs Cache

• Floor data cache (in-memory LRU) is separate from IndexedDB
• IndexedDB persists across sessions; in-memory cache is lost on page reload
• In-memory cache is limited to 4 floors by default with memory pressure eviction

Tradeoffs

• Pro: Fast re-opens, offline support, reduced network usage
• Con: Storage quota limits, schema migration complexity, privacy concerns (storing building data)
• Mitigation: Clear cache button in settings, automatic eviction on quota exceeded

When It Was Made

Added progressively across phases. The derived asset cache was added in Phase 5+ to avoid re-building routing graphs on every open.

Related Notes

• ../modules/Asset System.md

• ../modules/MVF Loading.md

• ../flows/Startup Sequence.md

• src/app/derived-asset-cache.js

• src/app/cached-mvf-loader.js

  continue:[[]]
  before:[[]]