lightcraft/docs/architecture.md

Architecture

Last reviewed: 2026-10-10 · Last updated: 2026-10-10 · Change: major (created from the code; the full design notes stay in the local plan/architecture.md) · Target: Adobe Lightroom Classic 15.5 / Lightroom 9.6

How LightCraft is built today. The longer design document (plan/architecture.md) is local-only (plan/ is gitignored); this page is the committed, current summary. Sizes are Rust lines counted on 2026-10-10 (≈ 202,000 tracked lines in 505 files: 24 library crates, 3 apps and xtask).

Layers

cargo xtask layers (part of cargo xtask ci, xtask/src/layers.rs) enforces that nothing below L5 depends on egui, eframe, winit or rfd, and that each crate only uses lower layers.

Layer	Crates (lines)	Role
L0	geom (1.4k), color (0.9k), raster (0.8k), tiff (2.0k), fetch (1.4k), sysmem (0.1k)	Matrices and warps, colour spaces and transfer functions, float image buffers, TIFF/IFD read and write, pinned HTTPS model downloads, the one unsafe FFI call (malloc_zone_pressure_relief)
L1	raw (22.3k), codecs (7.3k), meta (4.3k), develop (2.5k), denoise-core (2.2k), denoise (2.7k), faces (5.3k), scenes (1.0k), heif (2.1k, optional)	Raw decoders and demosaic, DNG colour model; standard codecs and encoders; EXIF/XMP/IPTC; the non-destructive edit model and control specs; AI denoise; face detection and recognition; procedural demo photos; HEIC
L2	pipeline (9.8k)	The develop pipeline: scene-referred float, resolution independent; the CPU reference (oracle) for everything else
L3	catalog (11.0k), gpu (5.1k), preview (1.3k), merge (3.8k), segment (2.3k)	Library model and persistence; wgpu compute twin of the pipeline; thumbnail/preview cache and job pool; HDR and panorama merge; SAM 3 segmentation
L4	engine (53.2k)	Session, command registry (everything is a command), history, render and export jobs, import, Lightroom catalog and preset import, faces index, view-models
L5	ui-egui (46.9k), mcp (2.3k)	The Lightroom-style egui interface (swappable); the MCP server
L6	apps/lightcraft (2.8k), apps/lightcraft-cli (1.5k), apps/lightcraft-web (3.4k), xtask (2.7k)	Desktop app (eframe + wgpu, native menus, control server), CLI (render, commands, calibrate, snapshot, MCP), WASM build, tooling

Data model

• Photo records in catalog hold the original's path, content hash, metadata, ratings, flags, labels, keywords, faces and the current develop::Settings. Albums, smart albums (rule trees), stacks, virtual copies, versions and folder records live alongside.
• Persistence (crates/catalog/src/journal.rs): an append-only journal of human-readable operations plus periodic snapshots, compacted in the background; torn appends and crashes are tested (tests_torn_append.rs, tests_journal.rs). A lock file guards against two writers.
• Edits are a develop::Settings value (every slider is a control spec with id, range and default), normalized to image coordinates so previews and exports match. Process versions (docs/process-versions.md) keep old edits rendering the same after a retune.
• Sidecars: XMP read and write with Adobe crs: interop (docs/xmp-interop.md); Lightroom Classic .lrcat import through a pure-Rust SQLite reader (docs/lightroom-catalog-import.md).

Rendering

1. Decode (raw, codecs): raw files to linear camera RGB (demosaic, black/white levels, opcodes, highlight handling) and a camera-to-XYZ colour model; standard images to linear light through their ICC profile.
2. Develop (pipeline): white balance, profile, exposure and tone (local Laplacian highlights/shadows), curves, HSL / colour mixer, point colour, colour grading, texture, clarity, dehaze, detail (sharpening, NR, AI denoise result), optics (lens profile, CA, defringe, vignette), geometry (crop, Upright, transforms), masks with local adjustments, heal/clone, grain, effects. Stage caching and a source pyramid make slider drags cheap.
3. GPU (gpu): the same stages in WGSL on Metal / DX12 / Vulkan, checked against the CPU path (within 1/255); GPU errors fall back to the CPU (docs/gpu-pipeline.md).
4. Display and export: display-profile conversion (docs/display-profiles.md); export through one encoder for app, CLI, MCP and web (lightcraft_engine::export).

Agent control

Every action is an engine command (id, label, menu path, shortcut, params, enabled, run). The UI, the CLI, the JSON-lines control channel (docs/control-protocol.md) and MCP (docs/mcp.md) all dispatch by id, and headless snapshots render the UI without a window.

Quality gates

cargo xtask ci: fmt, clippy -D warnings with the never-crash lints, the HEIF build, tests, parity (every id and path cited in parity-checklist.md exists), layers, assets (every asset attributed, no Adobe formats) and the WASM build. Other workflows build and test FreeBSD and Windows ARM64, lint packaging, and build releases.

Revision history

Date	Change	Summary
2026-10-10	major	Created from the code (crate sizes, layers, data model, rendering, control, gates)