# logicdx342/shelflife architecture

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

- Interactive diagram: https://gitdiagram.com/logicdx342/shelflife
- Repository: https://github.com/logicdx342/shelflife

## Overview

1. **Overall shape:** ShelfLife is a desktop application built as a **Tauri shell** around a **Svelte frontend** and a **Rust backend**. The frontend handles navigation and state presentation, while the Rust side owns filesystem monitoring, rule evaluation, persistence, and any action that can change files.

2. **User-facing surface:** The Svelte app is organized into pages for **dashboard**, **review queue**, **dropzone**, **browser**, **rules**, **audit**, and **settings**. Shared shell components such as the sidebar, title bar, and status bar frame these views. The UI is heavily componentized and uses a local component library built from shadcn-style Svelte primitives.

3. **Frontend data boundary:** Frontend code talks to the backend through `src/lib/api/*` wrappers for **config**, **files**, **rules**, **dropzone**, and **triage**. Reactive stores in `src/lib/stores/*` hold the current file set, rule set, audit trail, and notifications, while `liveSnapshots` suggests the UI is fed from live backend snapshots rather than directly inspecting the filesystem.

4. **Core domain model:** The backend models center on **tracked files**, **rules**, **dropzones**, **audit events**, **configuration**, **runtime state**, **origin/source metadata**, and **previews**. The key product concept is file lifecycle state: files move through freshness/decay states, can be pinned, and can be projected into preview mode before any destructive action.

5. **Filesystem monitoring pipeline:** The `engine` module is the operational core. It includes a **watcher** for OS file events, **quiescence** handling to avoid acting on files still changing, **freshness** tracking, and **path/reconciliation** logic to keep the runtime view aligned with the real filesystem.

6. **Rule processing pipeline:** Rules are interpreted by a dedicated rules subsystem (`conditions`, `evaluator`, `explanation`, `regex_cache`) and an execution layer under `engine` (`rule_projection`, `rule_execution`, `rule_refresh`). This separation indicates a deliberate split between **deciding what would happen**, **explaining why**, and **performing the action**.

7. **Safety and preview flow:** New rules begin in **preview** mode, so the app can calculate affected files without applying changes. That preview path is backed by the rule projection/explanation pieces, which feed the rule editor and test-result UI before a rule is activated.

8. **Background runtime and scheduling:** The `runtime` module contains scheduling and reconciliation logic, including a **rule scheduler** and a **mock runtime** for non-production scenarios. This suggests the app has a long-lived background control loop that periodically re-evaluates file state and rule eligibility, rather than only reacting to explicit user actions.

9. **Persistence and history:** The `storage` layer persists **rules**, **tracked files**, and **audit records**. The audit log is not just a UI feature; it is a durable subsystem that records file actions so users can review past behavior and undo supported operations.

10. **External side effects:** When the backend decides to act, it moves files to the **system trash/recycle bin** rather than deleting them outright. That behavior is central to the architecture: the backend is the only layer permitted to perform these side effects, which keeps the UI safe and non-destructive.

11. **Dropzone and triage workflow:** The presence of dedicated dropzone models, commands, and a dropzone-specific route indicates a separate intake path for newly arrived files. Triage commands likely move files from incoming handling into tracked/reviewed states, bridging raw filesystem events and rule-managed lifecycle.

12. **App lifecycle and system integration:** `tray.rs`, `main.rs`, and Tauri capability files show the app is designed to live in the background with system-level access constrained through Tauri permissions. The app is therefore a **resident desktop service with a UI**, not just a page-based application.

13. **What to draw as the main boundaries:** The clearest diagram should show:
- **Svelte UI layer** for dashboards, rules, audit, and settings  
- **Tauri command boundary** as the only frontend/backend bridge  
- **Rust orchestration layer** for watching, scheduling, reconciling, and rule execution  
- **Local persistence** for rules, tracked files, and audit history  
- **Filesystem/system-trash side effects** as the final external boundary

14. **Supporting but non-central pieces:** The repo also includes localization tooling, CI/release workflows, and a lightweight test/mock setup, but these support development and packaging rather than changing the runtime architecture.

Main entry points: [`src-tauri/src/engine`](https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/engine) (Engine core), [`src/routes`](https://github.com/logicdx342/shelflife/tree/main/src/routes) (App pages), [`src-tauri/src/commands`](https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/commands) (Tauri commands), [`src-tauri/src/storage`](https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/storage) (Storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_routes["App pages<br/>Svelte routes"]
  node_shell["Shell chrome<br/>UI shell<br/>[Sidebar.svelte]"]
  node_ui["UI kit<br/>component library"]
  node_api["API wrappers<br/>Tauri bridge"]
  node_stores["App stores<br/>reactive state"]
  node_live["Live snapshots<br/>snapshot feed<br/>[liveSnapshots.ts]"]
end

subgraph group_backend["Rust Backend"]
  node_commands["Tauri commands<br/>backend boundary"]
  node_engine["Engine core<br/>orchestration"]
  node_watcher["Watcher<br/>fs events<br/>[watcher.rs]"]
  node_quiescence["Quiescence<br/>stabilization<br/>[quiescence.rs]"]
  node_recon["Reconciliation<br/>state sync<br/>[reconciliation.rs]"]
  node_ruleflow["Rule flow<br/>rule pipeline<br/>[rule_execution.rs]"]
  node_rules["Rules engine<br/>evaluation"]
  node_runtime["Scheduler<br/>background loop"]
  node_models["Domain models<br/>state model"]
  node_storage["Storage<br/>persistence"]
  node_dropzone["Dropzone intake<br/>workflow<br/>[dropzone.rs]"]
  node_lifecycle["Tray app<br/>desktop lifecycle<br/>[main.rs]"]
end

subgraph group_external["External Boundaries"]
  node_fs[("Filesystem<br/>external system")]
  node_trash[("System trash<br/>external system")]
end

node_routes -->|"framed by"| node_shell
node_routes -->|"renders with"| node_ui
node_routes -->|"calls"| node_api
node_routes -->|"reads state"| node_stores
node_stores -->|"subscribed to"| node_live
node_api -->|"bridges to"| node_commands
node_commands -->|"drives"| node_engine
node_engine -->|"uses"| node_watcher
node_engine -->|"uses"| node_quiescence
node_engine -->|"uses"| node_recon
node_engine -->|"runs"| node_ruleflow
node_ruleflow -->|"evaluates via"| node_rules
node_runtime -->|"schedules"| node_engine
node_runtime -->|"rechecks"| node_rules
node_dropzone -->|"exposed by"| node_commands
node_dropzone -->|"feeds"| node_engine
node_engine -->|"reads/writes"| node_models
node_storage -->|"persists"| node_models
node_storage -->|"stores"| node_rules
node_storage -->|"supports undo via"| node_trash
node_engine -->|"observes"| node_fs
node_lifecycle -->|"hosts"| node_commands
node_lifecycle -->|"starts"| node_engine

click node_routes "https://github.com/logicdx342/shelflife/tree/main/src/routes"
click node_shell "https://github.com/logicdx342/shelflife/blob/main/src/lib/components/Sidebar.svelte"
click node_ui "https://github.com/logicdx342/shelflife/tree/main/src/lib/components/ui"
click node_api "https://github.com/logicdx342/shelflife/tree/main/src/lib/api"
click node_stores "https://github.com/logicdx342/shelflife/tree/main/src/lib/stores"
click node_live "https://github.com/logicdx342/shelflife/blob/main/src/lib/live/liveSnapshots.ts"
click node_commands "https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/commands"
click node_engine "https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/engine"
click node_watcher "https://github.com/logicdx342/shelflife/blob/main/src-tauri/src/engine/watcher.rs"
click node_quiescence "https://github.com/logicdx342/shelflife/blob/main/src-tauri/src/engine/quiescence.rs"
click node_recon "https://github.com/logicdx342/shelflife/blob/main/src-tauri/src/engine/reconciliation.rs"
click node_ruleflow "https://github.com/logicdx342/shelflife/blob/main/src-tauri/src/engine/rule_execution.rs"
click node_rules "https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/rules"
click node_runtime "https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/runtime"
click node_models "https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/models"
click node_storage "https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/storage"
click node_dropzone "https://github.com/logicdx342/shelflife/blob/main/src-tauri/src/dropzone.rs"
click node_lifecycle "https://github.com/logicdx342/shelflife/blob/main/src-tauri/src/main.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_routes,node_shell,node_ui,node_api,node_stores,node_live toneBlue
class node_commands,node_engine,node_watcher,node_quiescence,node_recon,node_ruleflow,node_rules,node_runtime,node_models,node_storage,node_dropzone,node_lifecycle toneAmber
class node_fs,node_trash toneMint
```

## Components

### Frontend

Svelte UI, local state, and API wrappers

- [App pages](https://github.com/logicdx342/shelflife/tree/main/src/routes): Svelte routes · Primary navigation surfaces for dashboard, queue, dropzone, browser, rules, audit, and settings · `src/routes`
- [Shell chrome](https://github.com/logicdx342/shelflife/blob/main/src/lib/components/Sidebar.svelte): UI shell · Layout framing such as sidebar, title bar, and status bar · `src/lib/components/Sidebar.svelte`
- [UI kit](https://github.com/logicdx342/shelflife/tree/main/src/lib/components/ui): component library · Shared shadcn-style primitives and reusable view components · `src/lib/components/ui`
- [API wrappers](https://github.com/logicdx342/shelflife/tree/main/src/lib/api): Tauri bridge · Frontend command wrappers for config, files, rules, dropzone, and triage · `src/lib/api`
- [App stores](https://github.com/logicdx342/shelflife/tree/main/src/lib/stores): reactive state · Client-side stores for files, rules, audit, and notifications · `src/lib/stores`
- [Live snapshots](https://github.com/logicdx342/shelflife/blob/main/src/lib/live/liveSnapshots.ts): snapshot feed · Live backend-fed state updates for the UI · `src/lib/live/liveSnapshots.ts`

### Rust Backend

Tauri commands, orchestration, rules, runtime, and storage

- [Tauri commands](https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/commands): backend boundary · Invoked from the frontend as the controlled command surface · `src-tauri/src/commands`
- [Engine core](https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/engine): orchestration · Filesystem monitoring, reconciliation, rule execution, and projection · `src-tauri/src/engine`
- [Watcher](https://github.com/logicdx342/shelflife/blob/main/src-tauri/src/engine/watcher.rs): fs events · Observes operating-system file events · `src-tauri/src/engine/watcher.rs`
- [Quiescence](https://github.com/logicdx342/shelflife/blob/main/src-tauri/src/engine/quiescence.rs): stabilization · Delays action until files stop changing · `src-tauri/src/engine/quiescence.rs`
- [Reconciliation](https://github.com/logicdx342/shelflife/blob/main/src-tauri/src/engine/reconciliation.rs): state sync · Keeps runtime view aligned with the real filesystem · `src-tauri/src/engine/reconciliation.rs`
- [Rule flow](https://github.com/logicdx342/shelflife/blob/main/src-tauri/src/engine/rule_execution.rs): rule pipeline · Projection, explanation, refresh, and execution of rules · `src-tauri/src/engine/rule_execution.rs`
- [Rules engine](https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/rules): evaluation · Conditions, evaluator, explanation, and regex cache · `src-tauri/src/rules`
- [Scheduler](https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/runtime): background loop · Long-lived runtime coordination and rule scheduling · `src-tauri/src/runtime`
- [Domain models](https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/models): state model · Tracked files, rules, dropzones, audit, preview, config, runtime, and origin metadata · `src-tauri/src/models`
- [Storage](https://github.com/logicdx342/shelflife/tree/main/src-tauri/src/storage): persistence · Durable rules, tracked files, and audit history · `src-tauri/src/storage`
- [Dropzone intake](https://github.com/logicdx342/shelflife/blob/main/src-tauri/src/dropzone.rs): workflow · Dedicated intake and triage path for arriving files · `src-tauri/src/dropzone.rs`
- [Tray app](https://github.com/logicdx342/shelflife/blob/main/src-tauri/src/main.rs): desktop lifecycle · Resident desktop entrypoint and system tray integration · `src-tauri/src/main.rs`

### External Boundaries

Filesystem and system integration

- **Filesystem**: external system · Watched local files and folders
- **System trash**: external system · Final non-destructive file side effect

## Connections

- App pages → Shell chrome: framed by · Pages are wrapped in shared application chrome
- App pages → UI kit: renders with · Views are built from shared primitives and reusable components
- App pages → API wrappers: calls · User actions are translated into backend commands
- App pages → App stores: reads state · Pages consume local reactive state
- App stores → Live snapshots: subscribed to · Stores are fed from live backend snapshots
- API wrappers → Tauri commands: bridges to · Frontend wrappers invoke the Tauri command boundary
- Tauri commands → Engine core: drives · Commands enter the Rust orchestration layer
- Engine core → Watcher: uses · The core engine listens for filesystem events
- Engine core → Quiescence: uses · The core engine waits for file activity to settle
- Engine core → Reconciliation: uses · The core engine reconciles runtime state with disk
- Engine core → Rule flow: runs · The engine evaluates, projects, refreshes, and executes rules
- Rule flow → Rules engine: evaluates via · Rule execution depends on the rules subsystem
- Scheduler → Engine core: schedules · Background runtime repeatedly re-evaluates state and eligibility
- Scheduler → Rules engine: rechecks · Scheduler consults rule evaluation logic
- Dropzone intake → Tauri commands: exposed by · Dropzone workflow is surfaced through commands
- Dropzone intake → Engine core: feeds · Incoming files are triaged into the engine's lifecycle
- Engine core → Domain models: reads/writes · Operational state is represented by shared domain models
- Storage → Domain models: persists · Durable records are stored using domain types
- Storage → Rules engine: stores · Rule definitions are persisted durably
- Storage → System trash: supports undo via · File actions use the system trash instead of permanent deletion
- Engine core → Filesystem: observes · The runtime is anchored to the live filesystem
- Tray app → Tauri commands: hosts · The desktop app hosts the command surface and tray integration
- Tray app → Engine core: starts · The app boots the background orchestration layer