SPB Git

Repository Public License

storage.md 6.7 KB 140 lines markdown

1<!--2ORIX Scan3File: docs/architecture/storage.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Storage910Documents are plain files in the app's container, written by `DocumentStore`11(`Packages/ORIXKit/Sources/ORIXKit/Storage/DocumentStore.swift`). A SwiftData store indexes them for the library12(`Storage/Library.swift`). There is no cloud database and no synchronization.1314## Layout1516`DocumentStore.defaultRoot()` is `Application Support/ORIXScan`, a location that is not visible to the user and is included17in device backups.1819```text20ORIXScan/21├── Documents/<uuid>/22│   ├── manifest.json          source of truth, replaced atomically23│   ├── pages/<uuid>.<ext>     original captures, never modified24│   ├── pdf/<uuid>.pdf         imported PDFs; pages reference them by index25│   ├── ocr/<page>.json        recognized text per page26│   └── cache/                 rendered previews (safe to delete)27├── Staging/<uuid>/            documents being created28├── Exports/<uuid>/            temporary export files29└── Library.store              SwiftData index30```3132```mermaid33flowchart LR34    subgraph Truth["Source of truth (files)"]35        M["manifest.json"]36        P["pages/ and pdf/"]37        O["ocr/"]38    end39    subgraph Derived["Derived, rebuildable"]40        C["cache/"]41        I["Library.store<br/>DocumentRecord"]42        S["Spotlight entries"]43    end44    subgraph Library["Library-only state"]45        F["FolderRecord, favourites, deletedAt"]46        W["WorkflowRecord"]47    end48    M --> I49    O --> I50    P --> C51    I --> S52    I --- F53```5455## Manifest5657`DocumentManifest` (`Model/Document.swift`) holds the title, creation and modification dates, PDF metadata and the ordered58`pages`. Each `PageRecord` has an identifier, a `PageSource` (`.image(file:)` or `.pdf(file:pageIndex:)`), its size and a59`PageEdit`. Reordering, rotating, cropping, filtering, duplicating and deleting pages are all changes to this file; the60captures are not rewritten.6162`DocumentStore.save(_:)` encodes the manifest and writes it with `Data.write(options: .atomic)`, so a reader sees the63previous or the new version and never a partial file. A manifest that cannot be decoded is reported as64`ORIXError.corruptedManifest`; a missing one as `documentNotFound`.6566## Staged creation and recovery6768A new document is built as a `DocumentStore.Draft` under `Staging/`: `beginDraft(title:)`, then `addImage` / `addPDF`, then69`commit`, which writes the manifest and moves the whole directory into `Documents/` in one step. Nothing is visible in the70library before that move. `commit` refuses a draft with no page (`emptyDocument`). `merge` and `derive` (duplicate, split,71extract) use the same mechanism and leave their sources untouched.7273`recoverAfterLaunch()`, called from `AppModel.start()`, removes whatever an interrupted session left behind: every directory74in `Staging/`, every directory in `Exports/`, and stray `.tmp-` files in document directories.7576## Originals and shared files7778Captured images are stored byte for byte (`addImage` writes the data it receives; the pixel size is read with ImageIO79without decoding). A file ImageIO cannot read is removed and reported as `unreadableImage`.8081`duplicatePage` copies the page record and its recognition but not the image: both pages reference the same original. When82a page is deleted or retaken, `removeFilesIfUnreferenced` deletes the original only if no remaining page uses it.83`deletePages` refuses to remove every page of a document.8485## Library index8687Three SwiftData models (`Library.schema`):8889| Model | Content |90|---|---|91| `DocumentRecord` | `id` (unique), title, dates, `isFavorite`, `deletedAt`, page count, byte size, kind, `hasText`, folded `searchText`, `snippet`, optional `folder` |92| `FolderRecord` | `id` (unique), name, creation date, inverse relationship to its documents (delete rule: nullify) |93| `WorkflowRecord` | `id` (unique), name, creation date, the `Workflow` encoded as JSON |9495`LibraryIndex` (main actor) keeps the index in step with the files:9697- `refresh(_:)` rebuilds a record from the manifest, the document's text and its size on disk. `searchText` is the title and98  the text folded with `Library.fold` (case, diacritics and width insensitive).99- `reconcile(now:)`, run at launch, adds records for documents found on disk without one, drops records whose files are100  gone, and permanently deletes documents whose `deletedAt` is older than `Library.retentionDays` (30 days).101102Because records are derived from the files, the document entries can be rebuilt if the store is lost. Folder membership,103favourites and the Recently Deleted state exist only in the index. User workflows also live only there.104105Filtering and sorting are done in memory by `Library.query(_:scope:filter:search:sort:ascending:)` over the fetched records;106title sorting uses `localizedStandardCompare`, so "Scan 2" precedes "Scan 10".107108## Recently Deleted109110Deleting a document sets `deletedAt` on its record (`LibraryIndex.moveToTrash`); its files stay in place. Restoring clears111the date. `deletePermanently` removes the directory and the record. Expired documents are removed by `reconcile` at launch.112113## Caches114115`DocumentProcessor.cachedPreviewURL` writes preview JPEGs to `cache/`, named by page identifier, `PageEdit.cacheKey` and116size, so an edit produces a new file and an unchanged page is served from disk. The key is an FNV-1a hash and is stable117across launches. `ThumbnailCache` in the app adds an `NSCache` of decoded images, emptied on memory warnings118(`AppModel.releaseMemory`). `clearAllCaches()` deletes every preview; they are regenerated on demand. Cache files are119excluded from the size shown for a document.120121## File protection122123On iOS the root directory, and each document directory at commit, is given124`FileProtectionType.completeUntilFirstUserAuthentication`. Files are encrypted at rest and become readable after the first125unlock following a restart. This class was chosen so that recognition started in the foreground can finish if the device126locks while it runs.127128## Low storage129130`ensureSpace(for:)` compares the bytes about to be written, plus a 50 MB reserve (`DocumentStore.storageReserve`), with the131volume's available capacity and throws `ORIXError.insufficientStorage` before writing. It is called before adding or132inserting images and PDFs, before saving a manifest, before copying a document and before exporting. The app shows133"Not Enough Storage"; the operation has not started, so nothing is lost.134135## Exports136137Each export gets its own directory from `makeExportDirectory()` under `Exports/`, so files keep their natural names138(`Title.pdf`) without colliding. A failed or cancelled PDF export removes its directory. Everything left in `Exports/` is139deleted at the next launch.140
Files main
Menu

Theme