# onefolderapp/onefolder architecture

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

- Interactive diagram: https://gitdiagram.com/onefolderapp/onefolder
- Repository: https://github.com/onefolderapp/onefolder

## Overview

##### Project type and purpose
- This is an Electron-based desktop application (“OneFolder”) for browsing and editing photo metadata in place (no separate DB), using React/MobX for the UI, Node/Electron for filesystem & native calls, WebAssembly for performance-sensitive tasks, and ExifTool for metadata I/O.

##### File structure
- Top-level:
- src/main.ts – Electron main (Node) process entry
- src/renderer.tsx + src/frontend – React renderer process
- src/ipc – message definitions + bridging code between main & renderer
- src/backend – background schedulers & file watchers in main process
- src/api – shared TypeScript abstractions for file/metadata operations
- wasm/… – Rust-based modules compiled to WebAssembly for image decoding & layout
- src/frontend/workers – Web Workers wrapping WASM and heavy tasks (thumbnail gen, hashing, folder watcher)
- resources/exiftool – bundled ExifTool CLI for native metadata operations
- Config & build: webpack.dev.js / webpack.prod.js, electron-builder in package.json
- Tests span backend, utils, and front-end components.

##### README for additional insights
- Architecture hints: Electron + React + MobX, ExifTool for metadata, Annotorious + TensorFlow.js for face annotation, WebAssembly for performance.

##### Detail but avoid over-splitting
- Essential layers: UI components, Stores, IPC, Main process services, Workers, WASM, ExifTool, File System
- Do not drown the viewer in every React component—group by “UI Layer” or “ContentView, Outliner, Settings”
- Call out specialized modules (e.g. FaceDetection, ThumbnailGen) individually

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% UI Layer
  subgraph "UI Layer"
    direction TB
    ReactApp["React App"]:::ui
    MainLayout["Main Layout (Containers)"]:::ui
    UIComponents["UI Components"]:::ui
    Annotorious["Annotorious Wrapper"]:::external
    TFJS["TensorFlow.js Models"]:::external
    ReactApp --> MainLayout
    MainLayout --> UIComponents
    UIComponents --> Annotorious
    UIComponents --> TFJS
  end

  %% State Layer
  subgraph "State Layer"
    direction TB
    MobXStores["MobX Stores"]:::state
  end

  %% API & IPC Client
  subgraph "API & IPC Client"
    direction TB
    APIClient["API Abstractions"]:::api
    IPCClient["IPC Client"]:::ipc
    APIClient --> IPCClient
  end

  %% Renderer Entry
  RendererEntry["Renderer Entry\n(src/renderer.tsx)"]:::renderer
  ReactApp -->|renders from| RendererEntry
  IPCClient -->|sends IPC| IPCRendererChannel

  %% Web Workers
  subgraph "Web Workers" 
    direction TB
    ThumbnailWorker["ThumbnailGenerator Worker"]:::worker
    VisualWorker["VisualSimilarity Worker"]:::worker
    FolderWorker["FolderWatcher Worker"]:::worker
    HEICWorker["HEIC Loader Worker"]:::worker
    PSDWorker["PSD Loader Worker"]:::worker
  end
  UIComponents -->|offloads tasks to| ThumbnailWorker
  UIComponents --> VisualWorker
  UIComponents --> FolderWorker
  UIComponents --> HEICWorker
  UIComponents --> PSDWorker

  %% WASM Modules
  subgraph "WebAssembly Modules"
    direction TB
    EXRDecoder["EXR Decoder WASM"]:::wasm
    MasonryLayout["Masonry Layout WASM"]:::wasm
  end
  ThumbnailWorker --> EXRDecoder
  FolderWorker --> MasonryLayout

  %% IPC Channel
  IPCRendererChannel["IPC Channel"]:::ipc
  IPCRendererChannel -->|to main| IPCMainHandlers

  %% Electron Main Process
  subgraph "Electron Main Process"
    direction TB
    MainEntry["Main Entry\n(src/main.ts)"]:::mainProcess
    IPCMainHandlers["IPC Handlers\n(src/ipc/main.ts)"]:::ipc
    BackendScheduler["Backup Scheduler & File Watcher\n(src/backend/backup-scheduler.ts)"]:::mainProcess
    BackendCore["Backend Core Services\n(src/backend/backend.ts)"]:::mainProcess
    ExifToolCLI["ExifTool CLI"]:::cli
    FileSystem["File System"]:::storage
    MainEntry --> IPCMainHandlers
    IPCMainHandlers --> BackendCore
    BackendScheduler --> BackendCore
    BackendCore -->|reads/writes via| ExifToolCLI
    BackendCore -->|direct FS ops| FileSystem
    ExifToolCLI --> FileSystem
    FileSystem --> BackendCore
    IPCMainHandlers -->|responds via| IPCRendererChannel
  end

  %% Click Events
  click MainEntry "https://github.com/onefolderapp/onefolder/blob/master/src/main.ts"
  click RendererEntry "https://github.com/onefolderapp/onefolder/blob/master/src/renderer.tsx"
  click IPCMainHandlers "https://github.com/onefolderapp/onefolder/blob/master/src/ipc/main.ts"
  click IPCClient "https://github.com/onefolderapp/onefolder/blob/master/src/ipc/renderer.ts"
  click MobXStores "https://github.com/onefolderapp/onefolder/blob/master/src/frontend/stores/RootStore.ts"
  click ReactApp "https://github.com/onefolderapp/onefolder/blob/master/src/frontend/App.tsx"
  click MainLayout "https://github.com/onefolderapp/onefolder/blob/master/src/frontend/containers/Main.tsx"
  click UIComponents "https://github.com/onefolderapp/onefolder/tree/master/src/frontend/components/"
  click ThumbnailWorker "https://github.com/onefolderapp/onefolder/blob/master/src/frontend/workers/thumbnailGenerator.worker.ts"
  click VisualWorker "https://github.com/onefolderapp/onefolder/blob/master/src/frontend/workers/visualSimilarity.worker.ts"
  click FolderWorker "https://github.com/onefolderapp/onefolder/blob/master/src/frontend/workers/folderWatcher.worker.ts"
  click HEICWorker "https://github.com/onefolderapp/onefolder/blob/master/src/frontend/workers/heicReader.worker.ts"
  click PSDWorker "https://github.com/onefolderapp/onefolder/blob/master/src/frontend/workers/psdReader.worker.ts"
  click EXRDecoder "https://github.com/onefolderapp/onefolder/blob/master/wasm/packages/exr/exr_decoder.js"
  click MasonryLayout "https://github.com/onefolderapp/onefolder/blob/master/wasm/packages/masonry/index.js"

  %% Styles
  classDef ui fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
  classDef state fill:#D5F5E3,stroke:#196F3D,color:#145A32
  classDef api fill:#FCF3CF,stroke:#B7950B,color:#7D6608
  classDef ipc fill:#E8DAEF,stroke:#6C3483,color:#4A235A
  classDef renderer fill:#FADBD8,stroke:#C0392B,color:#641E16
  classDef mainProcess fill:#DADADA,stroke:#566573,color:#1C2833
  classDef cli fill:#FDEDEC,stroke:#922B21,color:#641E16
  classDef storage fill:#EBF5FB,stroke:#1A5276,color:#154360
  classDef worker fill:#F9E79F,stroke:#B9770E,color:#7D6608
  classDef wasm fill:#E8F8F5,stroke:#117A65,color:#0E6251
  classDef external fill:#F5EEF8,stroke:#633974,color:#4A235A
```
