# storytold/lightcraft architecture

> Architecture diagram of the GitHub repository storytold/lightcraft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/storytold/lightcraft
- Repository: https://github.com/storytold/lightcraft

## Overview

LightCraft is a cross-platform photo library and non-destructive RAW developer, with native, browser, CLI, and MCP entry points. The main user workflow is to import or open photos, organize and search a catalog, adjust images, then preview or export results. The graph preserves documented editing, masking, color, AI-agent, and multi-platform capabilities. Several links between app layers are dashed because the sampled excerpts do not show their runtime wiring; unsampled subsystems are represented only where the tree and README establish their role.

Main entry points: [`crates/engine/src/cmd/mod.rs`](https://github.com/storytold/lightcraft/blob/main/crates/engine/src/cmd/mod.rs) (Engine commands), [`apps/lightcraft-web/src/lib.rs`](https://github.com/storytold/lightcraft/blob/main/apps/lightcraft-web/src/lib.rs) (Web app), [`crates/catalog/src/query.rs`](https://github.com/storytold/lightcraft/blob/main/crates/catalog/src/query.rs) (Search and sort), [`crates/engine/src/media.rs`](https://github.com/storytold/lightcraft/blob/main/crates/engine/src/media.rs) (Decode and previews)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App entry points"]
  node_desktop["Desktop app<br/>[main.rs]"]
  node_browser["Web app<br/>[lib.rs]"]
  node_cli["CLI<br/>[main.rs]"]
  node_engine["Engine commands<br/>[mod.rs]"]
end

subgraph group_library["Photo library"]
  node_catalog[("Catalog model<br/>[model.rs]")]
  node_search["Search and sort<br/>[query.rs]"]
  node_keywords["Keywords<br/>[keywords.rs]"]
  node_folders["Folders and albums<br/>[folders.rs]"]
  node_rules["Catalog rules<br/>[rules.rs]"]
  node_import["Photo import<br/>[import.rs]"]
  node_files["File operations<br/>[files.rs]"]
  node_webstore[("Browser storage<br/>[store.rs]")]
end

subgraph group_imaging["Image development"]
  node_media["Decode and previews<br/>[media.rs]"]
  node_codecs["Image codecs<br/>[lib.rs]"]
  node_develop["Develop settings<br/>[lib.rs]"]
  node_pipeline["Develop pipeline<br/>[lib.rs]"]
  node_gpu["GPU rendering<br/>[render.rs]"]
  node_export["Image export<br/>[export.rs]"]
  node_denoise["Denoising<br/>[lib.rs]"]
  node_webworkers["Render workers<br/>[workers.rs]"]
end

subgraph group_automation["AI and services"]
  node_mcp["MCP server<br/>[server.rs]"]
  node_faces["Face recognition<br/>[lib.rs]"]
end

node_photographer(("Photographer"))

node_photographer -->|"edits photos"| node_desktop
node_photographer -->|"edits photos"| node_browser
node_desktop -.->|"dispatches commands"| node_engine
node_browser -.->|"dispatches commands"| node_engine
node_cli -.->|"runs commands"| node_engine
node_mcp -.->|"exposes tools"| node_engine
node_engine -.->|"imports photos"| node_import
node_import -.->|"records photos"| node_catalog
node_engine -->|"queries catalog"| node_search
node_search -->|"uses folder filters"| node_folders
node_search -->|"uses rules"| node_rules
node_search -->|"uses keywords"| node_keywords
node_engine -.->|"requests previews"| node_media
node_media -.->|"decodes images"| node_codecs
node_media -->|"uses denoising"| node_denoise
node_media -->|"supports face work"| node_faces
node_engine -.->|"sets adjustments"| node_develop
node_develop -.->|"configures rendering"| node_pipeline
node_pipeline -.->|"renders on GPU"| node_gpu
node_engine -.->|"exports results"| node_export
node_browser -.->|"persists data"| node_webstore
node_browser -->|"dispatches renders"| node_webworkers

click node_desktop "https://github.com/storytold/lightcraft/blob/main/apps/lightcraft/src/main.rs"
click node_browser "https://github.com/storytold/lightcraft/blob/main/apps/lightcraft-web/src/lib.rs"
click node_cli "https://github.com/storytold/lightcraft/blob/main/apps/lightcraft-cli/src/main.rs"
click node_mcp "https://github.com/storytold/lightcraft/blob/main/crates/mcp/src/server.rs"
click node_engine "https://github.com/storytold/lightcraft/blob/main/crates/engine/src/cmd/mod.rs"
click node_catalog "https://github.com/storytold/lightcraft/blob/main/crates/catalog/src/model.rs"
click node_search "https://github.com/storytold/lightcraft/blob/main/crates/catalog/src/query.rs"
click node_keywords "https://github.com/storytold/lightcraft/blob/main/crates/catalog/src/keywords.rs"
click node_folders "https://github.com/storytold/lightcraft/blob/main/crates/catalog/src/folders.rs"
click node_rules "https://github.com/storytold/lightcraft/blob/main/crates/catalog/src/rules.rs"
click node_import "https://github.com/storytold/lightcraft/blob/main/crates/engine/src/import.rs"
click node_files "https://github.com/storytold/lightcraft/blob/main/crates/engine/src/files.rs"
click node_media "https://github.com/storytold/lightcraft/blob/main/crates/engine/src/media.rs"
click node_codecs "https://github.com/storytold/lightcraft/blob/main/crates/codecs/src/lib.rs"
click node_develop "https://github.com/storytold/lightcraft/blob/main/crates/develop/src/lib.rs"
click node_pipeline "https://github.com/storytold/lightcraft/blob/main/crates/pipeline/src/lib.rs"
click node_gpu "https://github.com/storytold/lightcraft/blob/main/crates/gpu/src/render.rs"
click node_export "https://github.com/storytold/lightcraft/blob/main/crates/engine/src/export.rs"
click node_faces "https://github.com/storytold/lightcraft/blob/main/crates/faces/src/lib.rs"
click node_denoise "https://github.com/storytold/lightcraft/blob/main/crates/denoise/src/lib.rs"
click node_webstore "https://github.com/storytold/lightcraft/blob/main/apps/lightcraft-web/src/store.rs"
click node_webworkers "https://github.com/storytold/lightcraft/blob/main/apps/lightcraft-web/src/workers.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop,node_browser,node_cli,node_engine toneBlue
class node_catalog,node_search,node_keywords,node_folders,node_rules,node_import,node_files,node_webstore toneAmber
class node_media,node_codecs,node_develop,node_pipeline,node_gpu,node_export,node_denoise,node_webworkers toneMint
class node_mcp,node_faces toneRose
class node_photographer toneIndigo
```

## Components

### App entry points

- [Desktop app](https://github.com/storytold/lightcraft/blob/main/apps/lightcraft/src/main.rs): `apps/lightcraft/src/main.rs`
- [Web app](https://github.com/storytold/lightcraft/blob/main/apps/lightcraft-web/src/lib.rs): `apps/lightcraft-web/src/lib.rs`
- [CLI](https://github.com/storytold/lightcraft/blob/main/apps/lightcraft-cli/src/main.rs): `apps/lightcraft-cli/src/main.rs`
- [Engine commands](https://github.com/storytold/lightcraft/blob/main/crates/engine/src/cmd/mod.rs): `crates/engine/src/cmd/mod.rs`

### Photo library

- [Catalog model](https://github.com/storytold/lightcraft/blob/main/crates/catalog/src/model.rs): `crates/catalog/src/model.rs`
- [Search and sort](https://github.com/storytold/lightcraft/blob/main/crates/catalog/src/query.rs): `crates/catalog/src/query.rs`
- [Keywords](https://github.com/storytold/lightcraft/blob/main/crates/catalog/src/keywords.rs): `crates/catalog/src/keywords.rs`
- [Folders and albums](https://github.com/storytold/lightcraft/blob/main/crates/catalog/src/folders.rs): `crates/catalog/src/folders.rs`
- [Catalog rules](https://github.com/storytold/lightcraft/blob/main/crates/catalog/src/rules.rs): `crates/catalog/src/rules.rs`
- [Photo import](https://github.com/storytold/lightcraft/blob/main/crates/engine/src/import.rs): `crates/engine/src/import.rs`
- [File operations](https://github.com/storytold/lightcraft/blob/main/crates/engine/src/files.rs): `crates/engine/src/files.rs`
- [Browser storage](https://github.com/storytold/lightcraft/blob/main/apps/lightcraft-web/src/store.rs): `apps/lightcraft-web/src/store.rs`

### Image development

- [Decode and previews](https://github.com/storytold/lightcraft/blob/main/crates/engine/src/media.rs): `crates/engine/src/media.rs`
- [Image codecs](https://github.com/storytold/lightcraft/blob/main/crates/codecs/src/lib.rs): `crates/codecs/src/lib.rs`
- [Develop settings](https://github.com/storytold/lightcraft/blob/main/crates/develop/src/lib.rs): `crates/develop/src/lib.rs`
- [Develop pipeline](https://github.com/storytold/lightcraft/blob/main/crates/pipeline/src/lib.rs): `crates/pipeline/src/lib.rs`
- [GPU rendering](https://github.com/storytold/lightcraft/blob/main/crates/gpu/src/render.rs): `crates/gpu/src/render.rs`
- [Image export](https://github.com/storytold/lightcraft/blob/main/crates/engine/src/export.rs): `crates/engine/src/export.rs`
- [Denoising](https://github.com/storytold/lightcraft/blob/main/crates/denoise/src/lib.rs): `crates/denoise/src/lib.rs`
- [Render workers](https://github.com/storytold/lightcraft/blob/main/apps/lightcraft-web/src/workers.rs): `apps/lightcraft-web/src/workers.rs`

### AI and services

- [MCP server](https://github.com/storytold/lightcraft/blob/main/crates/mcp/src/server.rs): `crates/mcp/src/server.rs`
- [Face recognition](https://github.com/storytold/lightcraft/blob/main/crates/faces/src/lib.rs): `crates/faces/src/lib.rs`

### Other components

- **Photographer**

## Connections

- Photographer → Desktop app: edits photos (evidence: `README.md`)
- Photographer → Web app: edits photos (evidence: `README.md`)
- Desktop app → Engine commands: dispatches commands
- Web app → Engine commands: dispatches commands
- CLI → Engine commands: runs commands
- MCP server → Engine commands: exposes tools
- Engine commands → Photo import: imports photos
- Photo import → Catalog model: records photos
- Engine commands → Search and sort: queries catalog
- Search and sort → Folders and albums: uses folder filters (evidence: `crates/catalog/src/query.rs`)
- Search and sort → Catalog rules: uses rules (evidence: `crates/catalog/src/query.rs`)
- Search and sort → Keywords: uses keywords (evidence: `crates/catalog/src/query.rs`)
- Engine commands → Decode and previews: requests previews
- Decode and previews → Image codecs: decodes images
- Decode and previews → Denoising: uses denoising (evidence: `crates/engine/src/media.rs`)
- Decode and previews → Face recognition: supports face work
- Engine commands → Develop settings: sets adjustments
- Develop settings → Develop pipeline: configures rendering
- Develop pipeline → GPU rendering: renders on GPU
- Engine commands → Image export: exports results
- Web app → Browser storage: persists data
- Web app → Render workers: dispatches renders (evidence: `apps/lightcraft-web/src/workers.rs`)
