Image Pipeline and Caching

Fri, 04 Sep 2026 00:00:00 +0000

Image Pipeline and Caching

This is the path a RAW file takes from “user picked a folder” to “sharp preview pixels on screen”, and the multi-layer cache system that keeps that fast on repeat visits. Read Concurrency Architecture first — this document assumes you know the actor/TaskGroup/Sendable vocabulary from there.

End-to-end flow

User selects folder
 │
 ▼
DiscoverFiles (actor) ──► finds candidate RAW file URLs
 │
 ▼
ScanFiles (actor) ──► reads EXIF/metadata per file → [FileItem]
 │ (feeds RawCullViewModel.files)
 ▼
ScanAndCreateThumbnails (actor, background, low priority)
 │ proactively decodes + caches grid thumbnails
 ▼
 ┌─────────────────────────────┐
 │ SharedMemoryCache (RAM) │ ← only RequestThumbnail admits here
 │ DiskCacheManager (disk) │ ← both scan-preload and requests write here
 └─────────────────────────────┘
 ▲
 │ (user scrolls the grid / opens loupe)
 │
RequestThumbnail (actor) ──► coalesces duplicate concurrent requests,
 │ checks memory cache → disk cache → decode
 ▼
 CGImage/NSImage rendered by a SwiftUI Image/ThumbnailComponents view

For full-size zoom/export, a parallel path exists through ScanAndExtractJPGs / ExtractAndSaveJPGs / SaveJPGImage, backed by FullSizeJPGDiskCache instead of DiskCacheManager.

Caching on RawCull

Image Pipeline and Caching

Image Pipeline and Caching

End-to-end flow