# rawnakhasan/wallpaper-sorter architecture

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

- Interactive diagram: https://gitdiagram.com/rawnakhasan/wallpaper-sorter
- Repository: https://github.com/rawnakhasan/wallpaper-sorter

## Overview

Wallpaper Sorter is a local wallpaper-library organizer: it watches the library and configured intake folders, waits for files to settle, plans sorting decisions, applies filesystem changes, and records them for browsing and undo through a localhost web UI. The graph preserves the documented inbox, library, duplicate, re-sort, tag/settings, activity, origin-data, and thumbnail capabilities. Pipeline-to-engine calls are supported by the pipeline excerpt and SOURCE INDEX; several UI and daemon subsystem links are documented in the README, while unsampled implementation details are not inferred.

Main entry points: [`ui/src/components/AppShell.tsx`](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/components/AppShell.tsx) (Web UI), [`engine/src/pipeline.rs`](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/pipeline.rs) (Sort pipeline), [`core/src/plan.rs`](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/core/src/plan.rs) (Action planner), [`daemon/src/daemon.rs`](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/daemon/src/daemon.rs) (Daemon loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Intake and planning"]
  node_watcher["Folder watcher<br/>[watcher.rs]"]
  node_debounce["File settling<br/>[debounce.rs]"]
  node_config["Tags and settings<br/>[config.rs]"]
  node_matcher["Filename matcher<br/>[matcher.rs]"]
  node_numbering["Numbering rules<br/>[numbering.rs]"]
  node_planner["Action planner<br/>[plan.rs]"]
end

subgraph group_runtime["Sorting runtime"]
  node_daemon["Daemon loop<br/>[daemon.rs]"]
  node_pipeline["Sort pipeline<br/>[pipeline.rs]"]
  node_executor["Filesystem executor<br/>[exec.rs]"]
end

subgraph group_records["Library records"]
  node_scanner["Library scan<br/>[scan.rs]"]
  node_actionlog[("Action log<br/>[log.rs]")]
  node_undo["Undo actions<br/>[undo.rs]"]
  node_hashindex[("Hash index<br/>[index.rs]")]
  node_origins[("Origin records<br/>[origins.rs]")]
end

subgraph group_web["Web interface"]
  node_webserver["Local API server<br/>[web.rs]"]
  node_thumbnails[("Thumbnail cache<br/>[thumbs.rs]")]
  node_ui["Web UI<br/>[AppShell.tsx]"]
  node_api["API client<br/>[api-client.ts]"]
  node_inbox["Inbox actions<br/>[useInboxActions.ts]"]
  node_library["Library actions"]
  node_resort["Re-sort preview<br/>[useResortPage.ts]"]
  node_settings["Tags and settings<br/>[useSettingsPage.ts]"]
  node_activity["Activity and undo<br/>[api.ts]"]
  node_data["Origin data<br/>[useDataPage.ts]"]
  node_duplicates["Duplicate review"]
end

node_user(("Library user"))

node_user -->|"adds files"| node_watcher
node_watcher -->|"reports changes"| node_daemon
node_daemon -->|"settles arrivals"| node_debounce
node_daemon -->|"processes files"| node_pipeline
node_pipeline -->|"reconciles library"| node_scanner
node_pipeline -->|"builds plan"| node_planner
node_planner -->|"classifies names"| node_matcher
node_planner -->|"plans numbering"| node_numbering
node_planner -->|"uses rules"| node_config
node_pipeline -->|"applies plan"| node_executor
node_pipeline -->|"updates hashes"| node_hashindex
node_pipeline -->|"updates records"| node_origins
node_executor -->|"appends actions"| node_actionlog
node_user -->|"uses browser"| node_ui
node_ui -.->|"requests data"| node_api
node_api -->|"sends JSON"| node_webserver
node_webserver -.->|"runs operations"| node_pipeline
node_webserver -->|"serves thumbnails"| node_thumbnails
node_ui -->|"manages arrivals"| node_inbox
node_ui -->|"manages images"| node_library
node_ui -->|"previews resort"| node_resort
node_ui -->|"edits configuration"| node_settings
node_ui -->|"views history"| node_activity
node_ui -->|"browses origins"| node_data
node_ui -->|"reviews duplicates"| node_duplicates
node_activity -->|"requests undo"| node_api
node_inbox -->|"undoes batch"| node_activity
node_library -->|"undoes batch"| node_activity
node_user -->|"starts sorter"| node_daemon

click node_watcher "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/daemon/src/watcher.rs"
click node_debounce "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/daemon/src/debounce.rs"
click node_daemon "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/daemon/src/daemon.rs"
click node_config "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/core/src/config.rs"
click node_matcher "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/core/src/matcher.rs"
click node_numbering "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/core/src/numbering.rs"
click node_planner "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/core/src/plan.rs"
click node_pipeline "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/pipeline.rs"
click node_scanner "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/scan.rs"
click node_executor "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/exec.rs"
click node_actionlog "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/log.rs"
click node_undo "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/undo.rs"
click node_hashindex "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/index.rs"
click node_origins "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/origins.rs"
click node_webserver "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/daemon/src/web.rs"
click node_thumbnails "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/daemon/src/thumbs.rs"
click node_ui "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/components/AppShell.tsx"
click node_api "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/lib/api-client.ts"
click node_inbox "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/features/inbox/hooks/useInboxActions.ts"
click node_library "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/features/library/hooks/useLibraryActions.ts"
click node_resort "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/features/resort/hooks/useResortPage.ts"
click node_settings "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/features/settings/hooks/useSettingsPage.ts"
click node_activity "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/features/activity/api.ts"
click node_data "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/features/data/hooks/useDataPage.ts"
click node_duplicates "https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/features/duplicates/hooks/useDuplicatesPage.ts"

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_watcher,node_debounce,node_config,node_matcher,node_numbering,node_planner,node_user toneBlue
class node_daemon,node_pipeline,node_executor toneAmber
class node_scanner,node_actionlog,node_undo,node_hashindex,node_origins toneMint
class node_webserver,node_thumbnails,node_ui,node_api,node_inbox,node_library,node_resort,node_settings,node_activity,node_data,node_duplicates toneRose
```

## Components

### Intake and planning

- [Folder watcher](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/daemon/src/watcher.rs): `daemon/src/watcher.rs`
- [File settling](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/daemon/src/debounce.rs): `daemon/src/debounce.rs`
- [Tags and settings](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/core/src/config.rs): `core/src/config.rs`
- [Filename matcher](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/core/src/matcher.rs): `core/src/matcher.rs`
- [Numbering rules](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/core/src/numbering.rs): `core/src/numbering.rs`
- [Action planner](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/core/src/plan.rs): `core/src/plan.rs`

### Sorting runtime

- [Daemon loop](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/daemon/src/daemon.rs): `daemon/src/daemon.rs`
- [Sort pipeline](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/pipeline.rs): `engine/src/pipeline.rs`
- [Filesystem executor](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/exec.rs): `engine/src/exec.rs`

### Library records

- [Library scan](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/scan.rs): `engine/src/scan.rs`
- [Action log](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/log.rs): `engine/src/log.rs`
- [Undo actions](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/undo.rs): `engine/src/undo.rs`
- [Hash index](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/index.rs): `engine/src/index.rs`
- [Origin records](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/engine/src/origins.rs): `engine/src/origins.rs`

### Web interface

- [Local API server](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/daemon/src/web.rs): `daemon/src/web.rs`
- [Thumbnail cache](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/daemon/src/thumbs.rs): `daemon/src/thumbs.rs`
- [Web UI](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/components/AppShell.tsx): `ui/src/components/AppShell.tsx`
- [API client](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/lib/api-client.ts): `ui/src/lib/api-client.ts`
- [Inbox actions](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/features/inbox/hooks/useInboxActions.ts): `ui/src/features/inbox/hooks/useInboxActions.ts`
- [Library actions](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/features/library/hooks/useLibraryActions.ts): `ui/src/features/library/hooks/useLibraryActions.ts`
- [Re-sort preview](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/features/resort/hooks/useResortPage.ts): `ui/src/features/resort/hooks/useResortPage.ts`
- [Tags and settings](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/features/settings/hooks/useSettingsPage.ts): `ui/src/features/settings/hooks/useSettingsPage.ts`
- [Activity and undo](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/features/activity/api.ts): `ui/src/features/activity/api.ts`
- [Origin data](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/features/data/hooks/useDataPage.ts): `ui/src/features/data/hooks/useDataPage.ts`
- [Duplicate review](https://github.com/rawnakhasan/wallpaper-sorter/blob/ui-rebuild/ui/src/features/duplicates/hooks/useDuplicatesPage.ts): `ui/src/features/duplicates/hooks/useDuplicatesPage.ts`

### Other components

- **Library user**

## Connections

- Library user → Folder watcher: adds files (evidence: `README.md`)
- Folder watcher → Daemon loop: reports changes (evidence: `README.md`)
- Daemon loop → File settling: settles arrivals (evidence: `README.md`)
- Daemon loop → Sort pipeline: processes files (evidence: `engine/src/pipeline.rs`)
- Sort pipeline → Library scan: reconciles library (evidence: `engine/src/pipeline.rs`)
- Sort pipeline → Action planner: builds plan (evidence: `engine/src/pipeline.rs`)
- Action planner → Filename matcher: classifies names (evidence: `core/src/plan.rs`)
- Action planner → Numbering rules: plans numbering (evidence: `core/src/plan.rs`)
- Action planner → Tags and settings: uses rules (evidence: `core/src/plan.rs`)
- Sort pipeline → Filesystem executor: applies plan (evidence: `engine/src/pipeline.rs`)
- Sort pipeline → Hash index: updates hashes (evidence: `engine/src/pipeline.rs`)
- Sort pipeline → Origin records: updates records (evidence: `engine/src/pipeline.rs`)
- Filesystem executor → Action log: appends actions (evidence: `engine/src/exec.rs`)
- Library user → Web UI: uses browser (evidence: `README.md`)
- Web UI → API client: requests data
- API client → Local API server: sends JSON (evidence: `README.md`)
- Local API server → Sort pipeline: runs operations
- Local API server → Thumbnail cache: serves thumbnails (evidence: `daemon/src/web.rs`)
- Web UI → Inbox actions: manages arrivals (evidence: `README.md`)
- Web UI → Library actions: manages images (evidence: `README.md`)
- Web UI → Re-sort preview: previews resort (evidence: `README.md`)
- Web UI → Tags and settings: edits configuration (evidence: `README.md`)
- Web UI → Activity and undo: views history (evidence: `README.md`)
- Web UI → Origin data: browses origins (evidence: `README.md`)
- Web UI → Duplicate review: reviews duplicates (evidence: `README.md`)
- Activity and undo → API client: requests undo (evidence: `ui/src/features/activity/api.ts`)
- Inbox actions → Activity and undo: undoes batch (evidence: `ui/src/features/inbox/hooks/useInboxActions.ts`)
- Library actions → Activity and undo: undoes batch (evidence: `ui/src/features/library/hooks/useLibraryActions.ts`)
- Library user → Daemon loop: starts sorter (evidence: `README.md`)
