# cybertimon/rapidraw architecture

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

- Interactive diagram: https://gitdiagram.com/cybertimon/rapidraw
- Repository: https://github.com/cybertimon/rapidraw

## Overview

1. **Overall shape**
   - RapidRAW is a cross-platform desktop photo editor built as a **Tauri** app.
   - The architecture splits cleanly into a **React/TypeScript frontend** for UI and workflow, and a **Rust backend** for file I/O, image processing, and platform integration.
   - The backend does the heavy lifting; the frontend mainly coordinates state, user interaction, and rendering.

2. **Frontend shell and navigation**
   - The app entry is `src/main.tsx` / `src/App.tsx`, with the UI organized into **Library** and **Editor** views.
   - The main UI is composed of panels for library browsing, filmstrip, editing controls, metadata, presets, export, masks, and AI tools.
   - Layout is highly modular and resizable, with a lot of the screen split into persistent panels rather than route-based pages.

3. **Frontend state model**
   - Global state is managed with **Zustand stores**: `useLibraryStore`, `useEditorStore`, `useProcessStore`, `useSettingsStore`, and `useUIStore`.
   - This is the main boundary for editing workflow state: selected folder/image, current adjustment values, processing status, UI layout, and settings.
   - Hooks such as `useImageLoader`, `useImageProcessing`, `useLibraryActions`, and `useTauriListeners` connect the store layer to backend events.

4. **Library and file-management flow**
   - The library subsystem discovers folders/images, tracks recursive trees, sorting/filtering, tags, ratings, and album-like organization.
   - User actions like import, rename, move, copy, delete, and folder creation are initiated in the frontend but executed through Rust commands.
   - The library view depends on generated thumbnails and metadata, so file scanning and preview generation are part of the backend/data pipeline, not just UI rendering.

5. **Editor and adjustment workflow**
   - The editor is built around a **non-destructive adjustment stack**: tonal controls, curves, color, detail, effects, crop/transform, masks, and presets.
   - The frontend owns the editing controls and immediate interaction state, while actual image recomputation is delegated to Rust/GPU processing.
   - Changes are persistent via sidecar metadata rather than by modifying original photos.

6. **Rust backend entry points and command layer**
   - `src-tauri/src/main.rs` and `lib.rs` are the Tauri application boundary, exposing commands/events to the web frontend.
   - Modules like `app_state.rs`, `app_settings.rs`, `file_management.rs`, `cache_utils.rs`, and `window_customizer.rs` suggest a service-oriented backend that centralizes app state, persistence, caching, and window/platform behavior.
   - The backend also handles platform-specific integration, including Android support and desktop window behavior.

7. **Image ingestion and RAW processing pipeline**
   - RAW decoding is handled through **rawler**-based processing (`raw_processing.rs`, `image_loader.rs`, `formats.rs`), with EXIF extraction in `exif_processing.rs`.
   - The pipeline likely flows from file read → decode/demosaic → correction/adjustment stages → GPU-ready image buffers.
   - Supporting modules such as `lens_correction.rs`, `negative_conversion.rs`, `denoising.rs`, `hdr_deghosting.rs`, and `panorama_stitching.rs` indicate specialized processing stages beyond basic RAW rendering.

8. **GPU rendering and shader boundary**
   - The performance-critical render path is built on **wgpu** with **WGSL shaders** under `src-tauri/src/shaders`.
   - The backend owns the image-processing engine, while the frontend requests previews/render updates and displays the result on canvas/image components.
   - This is the key architecture boundary: React manages interaction; Rust + GPU produce the actual pixels for live previews and export-quality output.

9. **Masks, AI, and generative editing**
   - Masking is a first-class subsystem: traditional brush/gradient masks, composition logic, and AI-derived masks for subject/sky/foreground/depth.
   - AI-related modules (`ai_commands.rs`, `ai_connector.rs`, `ai_processing.rs`, `mask_generation.rs`, `tagging.rs`) suggest two paths:
     - **built-in local AI** for masking/tagging/basic edits
     - optional **external ComfyUI-based generative editing** through a connector/middleware
   - The README’s described AI connector model means large image payloads are cached and only small deltas like masks/prompts are repeatedly transferred.

10. **Export, presets, and sidecar persistence**
   - Editing is non-destructive: the app stores state in **`.rrdata` sidecar files** and writes metadata when exporting or syncing with image files.
   - Preset import/export and copy-paste of settings are part of the same configuration model used to transfer adjustment state across images.
   - The export subsystem handles file format conversion, metadata options, naming, resizing, watermarking, and batch output.

11. **Caching and background performance**
   - The presence of `cache_utils.rs`, `ImageLRUCache.ts`, thumbnail hooks, and preview/process managers points to aggressive caching and background work to keep the UI responsive.
   - Frontend managers (`ImageLoaderManager`, `ImageProcessingManager`) isolate asynchronous work from the UI tree.
   - The design favors incremental updates: thumbnails, previews, and analysis overlays are updated independently rather than forcing full reprocessing everywhere.

12. **Metadata, tagging, and organization services**
   - Metadata handling is not just display-only; the app includes EXIF viewing/editing, tagging, color labels, ratings, and search/filter support.
   - Tagging has its own Rust utilities (`tagging_utils`) and frontend panels/hooks, showing it is a distinct subsystem with shared data across library and editor contexts.
   - Lensfun database files in `src-tauri/lensfun_db` act as embedded correction data for camera/lens matching.

13. **Platform, packaging, and delivery**
   - The repo includes desktop packaging metadata, Linux Flatpak assets, Android scaffolding, icons, and platform-specific Tauri config files.
   - This is a **single codebase, multi-target application**: desktop is the primary target, but Android support is generated and maintained in-repo.
   - CI/CD via GitHub Actions handles build, lint, test, and release workflows.

14. **Key architecture diagram boundaries to show**
   - Show the **file system / photo library** as the primary data source.
   - Show the **Tauri bridge** between frontend and Rust backend.
   - Split Rust backend into **file/metadata**, **processing/export**, **cache/background jobs**, and **AI integration**.
   - Show **wgpu/WGSL** as the rendering engine boundary inside the backend.
   - Show **sidecar `.rrdata` persistence** and optional **external ComfyUI service** as the main external integration points.

Main entry points: [`src-tauri/src/lib.rs`](https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/lib.rs) (Backend core), [`src-tauri/src/file_management.rs`](https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/file_management.rs) (File & metadata), [`src/App.tsx`](https://github.com/cybertimon/rapidraw/blob/main/src/App.tsx) (App shell), [`src-tauri/src/raw_processing.rs`](https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/raw_processing.rs) (RAW pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_src_main["App entry<br/>react bootstrap<br/>[main.tsx]"]
  node_src_app["App shell<br/>ui orchestrator<br/>[App.tsx]"]
  node_views_library["Library view<br/>library workspace<br/>[LibraryView.tsx]"]
  node_views_editor["Editor view<br/>editing workspace<br/>[EditorView.tsx]"]
  node_stores[("Zustand stores<br/>state stores")]
  node_hooks["Workflow hooks<br/>integration hooks"]
  node_panels_library["Library panels<br/>library UI"]
  node_panels_editor["Editor panels<br/>editor UI"]
  node_panels_right["Right tools<br/>tool panels"]
  node_managers["Async managers<br/>background UI workers"]
end

subgraph group_backend["Tauri Backend"]
  node_tauri_main["Rust entry<br/>tauri boundary<br/>[main.rs]"]
  node_backend_lib["Backend core<br/>backend modules<br/>[lib.rs]"]
  node_file_meta["File & metadata<br/>ingest/service layer<br/>[file_management.rs]"]
  node_raw_pipeline["RAW pipeline<br/>image pipeline<br/>[raw_processing.rs]"]
  node_gpu_render["GPU render<br/>wgpu pipeline<br/>[gpu_processing.rs]"]
  node_exporting["Export engine<br/>batch export"]
  node_ai_integration["AI tools<br/>ai integration<br/>[ai_connector.rs]"]
  node_cache_jobs["Cache jobs<br/>cache/background<br/>[cache_utils.rs]"]
  node_presets_sidecar["Sidecar data<br/>non-destructive persistence"]
end

subgraph group_platform["Platform & Packaging"]
  node_android_pack["Android build<br/>mobile scaffold"]
  node_desktop_pack["Desktop packaging<br/>packaging config"]
  node_ci_release["CI release<br/>automation<br/>[workflows]"]
end

node_src_main -->|"bootstraps"| node_src_app
node_src_app -->|"shows"| node_views_library
node_src_app -->|"shows"| node_views_editor
node_src_app -->|"binds state"| node_stores
node_src_app -->|"drives flow"| node_hooks
node_views_library -->|"composes"| node_panels_library
node_views_editor -->|"composes"| node_panels_editor
node_views_editor -->|"uses"| node_panels_right
node_views_editor -->|"delegates work"| node_managers
node_hooks -->|"calls commands"| node_tauri_main
node_hooks -->|"syncs state"| node_stores
node_tauri_main -->|"initializes"| node_backend_lib
node_backend_lib -->|"manages"| node_file_meta
node_backend_lib -->|"routes to"| node_raw_pipeline
node_backend_lib -->|"routes to"| node_gpu_render
node_backend_lib -->|"routes to"| node_exporting
node_backend_lib -->|"exposes"| node_ai_integration
node_backend_lib -->|"coordinates"| node_cache_jobs
node_file_meta -->|"persists"| node_presets_sidecar
node_file_meta -->|"feeds"| node_cache_jobs
node_file_meta -->|"loads"| node_raw_pipeline
node_raw_pipeline -->|"produces buffers"| node_gpu_render
node_raw_pipeline -->|"reads metadata"| node_file_meta
node_gpu_render -->|"renders preview"| node_panels_editor
node_exporting -->|"writes settings"| node_presets_sidecar
node_ai_integration -->|"augments"| node_raw_pipeline
node_ai_integration -->|"tags"| node_file_meta
node_ci_release -->|"ships"| node_desktop_pack
node_desktop_pack -->|"packages"| node_tauri_main
node_android_pack -->|"targets"| node_tauri_main

click node_src_main "https://github.com/cybertimon/rapidraw/blob/main/src/main.tsx"
click node_src_app "https://github.com/cybertimon/rapidraw/blob/main/src/App.tsx"
click node_views_library "https://github.com/cybertimon/rapidraw/blob/main/src/components/views/LibraryView.tsx"
click node_views_editor "https://github.com/cybertimon/rapidraw/blob/main/src/components/views/EditorView.tsx"
click node_stores "https://github.com/cybertimon/rapidraw/tree/main/src/store"
click node_hooks "https://github.com/cybertimon/rapidraw/tree/main/src/hooks"
click node_panels_library "https://github.com/cybertimon/rapidraw/tree/main/src/components/panel/library"
click node_panels_editor "https://github.com/cybertimon/rapidraw/tree/main/src/components/panel"
click node_panels_right "https://github.com/cybertimon/rapidraw/tree/main/src/components/panel/right"
click node_managers "https://github.com/cybertimon/rapidraw/tree/main/src/components/managers"
click node_tauri_main "https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/main.rs"
click node_backend_lib "https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/lib.rs"
click node_file_meta "https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/file_management.rs"
click node_raw_pipeline "https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/raw_processing.rs"
click node_gpu_render "https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/gpu_processing.rs"
click node_exporting "https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/export_processing.rs"
click node_ai_integration "https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/ai_connector.rs"
click node_cache_jobs "https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/cache_utils.rs"
click node_presets_sidecar "https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/preset_converter.rs"
click node_android_pack "https://github.com/cybertimon/rapidraw/tree/main/src-tauri/gen/android"
click node_desktop_pack "https://github.com/cybertimon/rapidraw/blob/main/packaging/io.github.CyberTimon.RapidRAW.yml"
click node_ci_release "https://github.com/cybertimon/rapidraw/blob/main/.github/workflows"

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_src_main,node_src_app,node_views_library,node_views_editor,node_stores,node_hooks,node_panels_library,node_panels_editor,node_panels_right,node_managers toneBlue
class node_tauri_main,node_backend_lib,node_file_meta,node_raw_pipeline,node_gpu_render,node_exporting,node_ai_integration,node_cache_jobs,node_presets_sidecar toneAmber
class node_android_pack,node_desktop_pack,node_ci_release toneMint
```

## Components

### Frontend

React/TypeScript UI, state, and workflow coordination.

- [App entry](https://github.com/cybertimon/rapidraw/blob/main/src/main.tsx): react bootstrap · Frontend startup and root composition. · `src/main.tsx`
- [App shell](https://github.com/cybertimon/rapidraw/blob/main/src/App.tsx): ui orchestrator · Top-level app layout, navigation, and view switching. · `src/App.tsx`
- [Library view](https://github.com/cybertimon/rapidraw/blob/main/src/components/views/LibraryView.tsx): library workspace · Folder browsing, filtering, and grid-based asset navigation. · `src/components/views/LibraryView.tsx`
- [Editor view](https://github.com/cybertimon/rapidraw/blob/main/src/components/views/EditorView.tsx): editing workspace · Non-destructive editing workspace and panel layout. · `src/components/views/EditorView.tsx`
- [Zustand stores](https://github.com/cybertimon/rapidraw/tree/main/src/store): state stores · Global app state for library, editor, process, settings, and UI. · `src/store`
- [Workflow hooks](https://github.com/cybertimon/rapidraw/tree/main/src/hooks): integration hooks · Bridges UI state to backend commands, loaders, listeners, and actions. · `src/hooks`
- [Library panels](https://github.com/cybertimon/rapidraw/tree/main/src/components/panel/library): library UI · Folder tree, grid, header, and related browsing controls. · `src/components/panel/library`
- [Editor panels](https://github.com/cybertimon/rapidraw/tree/main/src/components/panel): editor UI · Canvas, toolbar, waveform, filmstrip, and adjustment panels. · `src/components/panel`
- [Right tools](https://github.com/cybertimon/rapidraw/tree/main/src/components/panel/right): tool panels · Controls, crop, masks, metadata, presets, export, and AI panels. · `src/components/panel/right`
- [Async managers](https://github.com/cybertimon/rapidraw/tree/main/src/components/managers): background UI workers · Isolates image loading and processing work from the component tree. · `src/components/managers`

### Tauri Backend

Rust commands, image processing, storage, and platform integration.

- [Rust entry](https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/main.rs): tauri boundary · Tauri runtime boundary exposing backend commands and events. · `src-tauri/src/main.rs`
- [Backend core](https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/lib.rs): backend modules · Application state, settings, caches, file management, and window behavior. · `src-tauri/src/lib.rs`
- [File & metadata](https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/file_management.rs): ingest/service layer · Folder scanning, image loading, EXIF, formats, tagging, and sidecar persistence. · `src-tauri/src/file_management.rs`
- [RAW pipeline](https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/raw_processing.rs): image pipeline · RAW decode, correction, denoise, lens, HDR, panorama, LUT, and adjustment stages. · `src-tauri/src/raw_processing.rs`
- [GPU render](https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/gpu_processing.rs): wgpu pipeline · Performance-critical render path and shader-backed preview generation. · `src-tauri/src/gpu_processing.rs`
- [Export engine](https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/export_processing.rs): batch export · Rendering, conversion, resize, watermark, metadata, and output writing. · `src-tauri/src/export_processing.rs`
- [AI tools](https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/ai_connector.rs): ai integration · Local AI commands, mask generation, tagging, and external connector flows. · `src-tauri/src/ai_connector.rs`
- [Cache jobs](https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/cache_utils.rs): cache/background · Shared caching and background work for thumbnails, previews, and analysis. · `src-tauri/src/cache_utils.rs`
- [Sidecar data](https://github.com/cybertimon/rapidraw/blob/main/src-tauri/src/preset_converter.rs): non-destructive persistence · Preset conversion and .rrdata-style adjustment persistence model. · `src-tauri/src/preset_converter.rs`

### Platform & Packaging

Desktop/mobile packaging, CI, and embedded resources.

- [Android build](https://github.com/cybertimon/rapidraw/tree/main/src-tauri/gen/android): mobile scaffold · Generated Android wrapper, activity, and build integration. · `src-tauri/gen/android`
- [Desktop packaging](https://github.com/cybertimon/rapidraw/blob/main/packaging/io.github.CyberTimon.RapidRAW.yml): packaging config · Tauri configuration, desktop metadata, icons, and release packaging. · `packaging/io.github.CyberTimon.RapidRAW.yml`
- [CI release](https://github.com/cybertimon/rapidraw/blob/main/.github/workflows): automation · Build, lint, test, and release workflows. · `.github/workflows`

## Connections

- App entry → App shell: bootstraps · Root React entry mounts the application shell.
- App shell → Library view: shows · App shell can present the library workspace.
- App shell → Editor view: shows · App shell can present the editor workspace.
- App shell → Zustand stores: binds state · UI reads and updates global workflow state.
- App shell → Workflow hooks: drives flow · App shell uses hooks for navigation and app lifecycle.
- Library view → Library panels: composes · Library view is built from browsing panels.
- Editor view → Editor panels: composes · Editor view is built from editing panels.
- Editor view → Right tools: uses · Editor view hosts right-side editing tools.
- Editor view → Async managers: delegates work · Preview loading and processing are offloaded to managers.
- Workflow hooks → Rust entry: calls commands · Frontend hooks invoke Tauri backend actions and listen for events.
- Workflow hooks → Zustand stores: syncs state · Hooks synchronize backend results into global stores.
- Rust entry → Backend core: initializes · Tauri runtime wires the backend service modules.
- Backend core → File & metadata: manages · Core backend coordinates file operations and metadata services.
- Backend core → RAW pipeline: routes to · Core backend sends images into processing stages.
- Backend core → GPU render: routes to · Core backend prepares GPU-backed preview/render work.
- Backend core → Export engine: routes to · Core backend triggers export and conversion tasks.
- Backend core → AI tools: exposes · Core backend exposes AI and connector functionality.
- Backend core → Cache jobs: coordinates · Core backend owns shared cache and background job orchestration.
- File & metadata → Sidecar data: persists · Editing state is stored through sidecar and preset conversion flows.
- File & metadata → Cache jobs: feeds · Scanning and thumbnails populate caches and background work.
- File & metadata → RAW pipeline: loads · File ingestion hands image data into decode and correction stages.
- RAW pipeline → GPU render: produces buffers · Processed image data is prepared for live preview rendering.
- RAW pipeline → File & metadata: reads metadata · Pipeline consumes EXIF and camera/lens information.
- GPU render → Editor panels: renders preview · Rendered output is displayed in the editor canvas and overlays.
- Export engine → Sidecar data: writes settings · Export and preset flows reuse the non-destructive adjustment model.
- AI tools → RAW pipeline: augments · AI-assisted masking and processing feed into the image pipeline.
- AI tools → File & metadata: tags · Tagging and metadata enrichment are part of AI-assisted workflows.
- CI release → Desktop packaging: ships · CI builds and releases packaged desktop artifacts.
- Desktop packaging → Rust entry: packages · Packaging targets the Tauri application runtime.
- Android build → Rust entry: targets · Generated Android scaffolding wraps the same backend/app core.
