RawCull Architecture on RawCull

Concurrency Architecture

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

Concurrency Architecture

RawCull is a Swift 6 / strict-concurrency codebase. Almost every piece of mutable shared state — caches, in-flight request tables, coordinators, view models — is isolated to either an actor or @MainActor, and cross-boundary data is required to be Sendable. This document is an inventory of that system and the patterns it relies on, so you can extend it safely.

The two isolation domains

RawCull’s concurrency model boils down to two kinds of isolated types:

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.

Culling and Persistence

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

Culling and Persistence

“Culling” is RawCull’s core job: attach a rating/status to each RAW file so the photographer can filter down to keepers and export just those. This document covers the model that owns that decision, how it’s filtered for display, and how it’s saved to disk.

The model: `CullingModel`

CullingModel (Model/ViewModels/CullingModel.swift) is a @MainActor @Observable class, constructed exactly once by RawCullViewModel (var cullingModel = CullingModel() — the comment above it says explicitly “This is the only place CullingModel is initialised”). It holds:

Export and Copy Pipeline

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

Export / Copy Pipeline (rsync)

Once files are rated, RawCull needs to get the keepers out to another folder (a backup drive, a delivery folder, etc.). It does this by shelling out to the system’s /usr/bin/rsync, rather than using FileManager copy APIs directly. This document explains that pipeline and, importantly, why the code around it uses vocabulary (“synchronize”, “offsite server”, “SSH parameters”) that has nothing to do with what RawCull actually does.

Intelligence and AI Subsystem

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

Intelligence / AI Subsystem

RawCull/Intelligence/ is where RawCull’s on-device machine-learning features live: grouping near-duplicate “burst” shots, ranking them by sharpness/subject focus, letting the user search photos by natural-language description, and (optionally) running a heavier “Deep Review” AI pass that recommends a winner within a burst. All of it runs locally — no photo data or embeddings leave the machine, and every optional model requires an explicit license acceptance and download before RawCull will use it.

The Intelligence Runtime

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

The Intelligence Runtime

This document is a deep dive into RawCullIntelligenceRuntime and its composition partner RawCullAIIntegration — together “the runtime” — which is only summarized in Intelligence and AI Subsystem. Read that doc first for the subsystem’s overall shape (folders, backends, CoreAI attribution); this document explains how the runtime object itself is built, how it reacts when a part of its configuration changes, how to extend it safely, and why it’s built this way.

SwiftUI View Layer

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

SwiftUI View Layer

RawCull/Views/ (87 files across 16 subfolders, ~15k lines) is the presentation layer. This doc covers the navigation architecture, the grid/inspection tools that make up most of the screen time, and the SwiftUI state-management idioms used consistently across the whole layer, so you can match the existing style when adding a view.

RawCullApp (see Architecture Overview) hosts three Window scenes; the main one wraps RawCullMainView (Main/RawCullMainView.swift), which is the root of everything a user actually browses photos through.

Settings and Configuration

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

Settings and Configuration

RawCull’s user-configurable state splits into two independently-persisted models: general app preferences (SettingsViewModel) and AI-feature preferences (RawCullAISettingsModel, covered in depth in Intelligence and AI Subsystem). This doc covers the general settings model, its persistence, and the memory monitor shown alongside it.

`SettingsViewModel`

Model/ViewModels/SettingsViewModel.swift is an @MainActor @Observable class exposing a flat list of plain stored properties for every tunable in the app — no nested config struct, so SwiftUI settings controls can bind to each property directly (Bindable(settingsViewModel).thumbnailSizeGrid, etc.). It groups into four areas via // MARK: comments:

RawCull Features and Roadmap

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

RawCull vs. Other Culling Apps, and Where RawCull Goes After 3.2.0

This document is deliberately different from the rest of the Docs/ catalog: docs 00–07 and runtime.md explain how the code works. This one is a product-positioning and roadmap document — it compares RawCull (current version 3.2.0) against other well-known photo-culling tools on macOS, and lays out a set of principles and concrete ideas for how the app should evolve afterward. It’s written for the same reader as the rest of the catalog (Swift/SwiftUI-literate, new to this codebase), but the goal here is product understanding, not implementation detail.

Known Issues and Findings

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

Known Issues and Findings

This is a code-review pass over the main RawCull app target (excluding RawCullTests and the external SPM packages). Overall the codebase is unusually clean for its size: no force-unwraps (!), no try!, no force-casts (as!), no unguarded array [0] accesses, no DispatchSemaphore or Timer/NotificationCenter leaks, and every startAccessingSecurityScopedResource() call has a matching stopAccessingSecurityScopedResource() on all paths, including cancellation and deinit. The findings below are the exceptions to that otherwise solid baseline. Severities: High (real user-facing breakage or data-loss risk), Medium (real bug/gap, narrow trigger conditions or degraded UX), Low (code-quality / robustness / maintainability).

RawCull Architecture on RawCull

Concurrency Architecture

Concurrency Architecture

The two isolation domains

Image Pipeline and Caching

Image Pipeline and Caching

End-to-end flow

Culling and Persistence

Culling and Persistence

The model: CullingModel

Export and Copy Pipeline

Export / Copy Pipeline (rsync)

Intelligence and AI Subsystem

Intelligence / AI Subsystem

The Intelligence Runtime

The Intelligence Runtime

SwiftUI View Layer

SwiftUI View Layer

Navigation architecture

Settings and Configuration

Settings and Configuration

SettingsViewModel

RawCull Features and Roadmap

RawCull vs. Other Culling Apps, and Where RawCull Goes After 3.2.0

Known Issues and Findings

Known Issues and Findings

The model: `CullingModel`

`SettingsViewModel`