SPB Git

Repository Public License

persistence.md 7.0 KB 133 lines markdown

1<!-- ORIX Clean / File: docs/architecture/persistence.md / Author: Simon-Pierre Boucher / Contact: contact@spboucher.ai -->2# Persistence34ORIX Clean persists very little: volume samples, watched-folder samples, the cleanup log and saved workflows,5in one SQLite file, plus a handful of interface preferences in the user defaults. Scan results are never6written to disk. Source: `Persistence/HistoryStore.swift`.78## Design decisions910| Decision | Rationale |11|---|---|12| Plain SQLite through the C API (`import SQLite3`) | The schema is five small tables. The store lives in the core Swift package and is tested there without an application host. No model versioning or migration machinery is needed |13| Not SwiftData | SwiftData would tie persistence to the application target and add a migration layer for a schema this small |14| Scan results in memory only | A tree is a snapshot that goes stale immediately; storing file names and sizes on disk would create a private index of the user's files with no benefit over rescanning |15| JSON blobs for reports and workflows | They are `Codable` values read back whole; no query needs their fields |1617## Location1819`HistoryStore.defaultPath()` returns `~/Library/Application Support/ORIX Clean/history.sqlite`. The directory20is created on first open. The database runs in WAL mode, so `history.sqlite-wal` and `history.sqlite-shm`21appear next to it while it is open. Passing `nil` as the path opens an in-memory store; the application does22this when launched with `-ORIXStore memory` (UI tests, screenshots).2324## Schema2526```mermaid27flowchart TD28    subgraph DB[history.sqlite]29        VS[volume_samples: ts, volume, name, total, available]30        FS[folder_samples: ts, path, logical, allocated, files]31        W[watched: path]32        OP[operations: id, ts, json]33        DOC[documents: kind, id, json]34    end35    Timer[15 minute timer, scans, cleanups] --> VS36    Watch[Watch a folder, scan of a watched root] --> W37    Watch --> FS38    Engine[DeletionReport after each cleanup] --> OP39    Actions[Saved workflows] --> DOC40    VS --> History[History chart, Trend.bytesPerDay, recommendations]41    FS --> History42    OP --> Log[Cleanup log, Put Back]43```4445| Table | Columns | Key or index | Written by |46|---|---|---|---|47| `volume_samples` | `ts REAL`, `volume TEXT`, `name TEXT`, `total INTEGER`, `available INTEGER` | index on `(volume, ts)` | `record(volume:at:minimumInterval:)` |48| `folder_samples` | `ts REAL`, `path TEXT`, `logical INTEGER`, `allocated INTEGER`, `files INTEGER` | index on `(path, ts)` | `record(folder:measurement:at:)` |49| `watched` | `path TEXT` | primary key | `watch`, `unwatch` |50| `operations` | `id TEXT`, `ts REAL`, `json BLOB` | primary key `id` | `save(_ report:)` with `INSERT OR REPLACE` |51| `documents` | `kind TEXT`, `id TEXT`, `json BLOB` | primary key `(kind, id)` | `saveDocument`, `deleteDocument` |5253All tables are created with `CREATE TABLE IF NOT EXISTS` when the store opens. Timestamps are seconds since541970. `volume` is the volume UUID, or its path when it has none. `operations.json` is a JSON-encoded55`DeletionReport`; the only `documents.kind` in use is `workflow`.5657## What is recorded, and when5859```mermaid60sequenceDiagram61    participant M as AppModel62    participant V as Volumes63    participant S as HistoryStore64    M->>V: mounted volumes65    loop each local volume66        M->>S: record volume sample67        S->>S: skip if last sample is under 15 min old and within 1 MB68    end69    M->>S: volumeSamples for the startup volume70    M->>S: monitoringStart71    Note over M,S: runs at launch, every 15 minutes, after each scan and cleanup, and when History opens72```7374- **Volume samples.** `AppModel.refreshEnvironment` records one sample per non-network volume. The store drops75  a sample when the previous one for that volume is less than `minimumInterval` (900 s) old and the available76  space changed by less than 1 MB. Samples exist only for periods when the application was open; the History77  view and the trends report state this, and `monitoringStart()` gives the date of the first sample.78- **Folder samples.** A watched folder is measured when it is added, when the user asks to measure watched79  folders, and when a scan's root is a watched path.80- **Operations.** Every `DeletionReport` is saved after a cleanup and saved again when a record is marked81  restored. `operations(limit:)` returns the 200 most recent by default.82- **Workflows.** User-defined Actions; built-in ones are code and are not stored.8384`Trend.bytesPerDay` computes a least-squares slope of used space over the samples and returns nil with fewer85than 3 samples or less than 6 hours between the first and the last.8687## What is not in the database8889| Data | Where it lives |90|---|---|91| Scan tree, file names, file sizes | Memory, for the lifetime of the scan |92| Duplicate and similar-image results | Memory |93| Cleanup selection (basket) | Memory |94| Appearance, list density, map palette, size kind, package contents toggle, onboarding flag | User defaults of the application (`appearance`, `density`, `mapPalette`, `sizeKind`, `showPackageContents`, `onboarded`) |95| Exported reports | Wherever the user saves them |9697The cleanup log does contain file paths: each `DeletionRecord` stores the original path, the Trash path,98sizes, status and detail text. Watched-folder paths and workflow scan paths are stored as well.99100## Concurrency101102One connection, opened with `SQLITE_OPEN_FULLMUTEX`, and an `NSLock` around every prepared statement. Each103write is a single statement. Text and blob bindings use `SQLITE_TRANSIENT`, so SQLite copies them.104105## Invariants106107- The store never contains more than what the tables above describe; there is no table for scan content.108- A report id is unique: saving a report with an existing id replaces it.109- `watched.path` is unique; watching twice is a no-op.110- Samples are append-only apart from "Erase History".111112## Failure handling113114- If the store cannot be opened, `AppModel.store` is nil and the application runs without history; nothing115  else depends on it.116- A statement that fails to prepare returns an empty result; write errors are not surfaced to the user.117- A JSON blob that no longer decodes is skipped when reading operations or documents.118119## Erasing120121Settings > Privacy & Access > Erase History calls `eraseAll()`, which deletes all rows of `volume_samples`,122`folder_samples` and `operations` after a confirmation dialog. It does not delete the `watched` list or saved123workflows, and it does not remove the database file. Deleting the `ORIX Clean` folder in Application Support124while the application is closed removes everything.125126## Not handled127128- No schema version and no migration path; a future schema change will need one.129- No retention limit, pruning or `VACUUM`: samples accumulate at up to one per volume per 15 minutes of use.130- No encryption beyond what the user's disk provides.131- `record(volume:)` loads all samples of the volume to find the last one, which is linear in history length.132- `VolumeSample.id` is the timestamp alone; it is unique per volume, which is how the application uses it.133
Files main
Menu

Theme