SPB Git

Repository Public License

storage.md 6.7 KB

# Storage

Documents are plain files in the app's container, written by DocumentStore (Packages/ORIXKit/Sources/ORIXKit/Storage/DocumentStore.swift). A SwiftData store indexes them for the library (Storage/Library.swift). There is no cloud database and no synchronization.

# Layout

DocumentStore.defaultRoot() is Application Support/ORIXScan, a location that is not visible to the user and is included in device backups.

text
ORIXScan/
├── Documents/<uuid>/
│   ├── manifest.json          source of truth, replaced atomically
│   ├── pages/<uuid>.<ext>     original captures, never modified
│   ├── pdf/<uuid>.pdf         imported PDFs; pages reference them by index
│   ├── ocr/<page>.json        recognized text per page
│   └── cache/                 rendered previews (safe to delete)
├── Staging/<uuid>/            documents being created
├── Exports/<uuid>/            temporary export files
└── Library.store              SwiftData index
flowchart LR
    subgraph Truth["Source of truth (files)"]
        M["manifest.json"]
        P["pages/ and pdf/"]
        O["ocr/"]
    end
    subgraph Derived["Derived, rebuildable"]
        C["cache/"]
        I["Library.store<br/>DocumentRecord"]
        S["Spotlight entries"]
    end
    subgraph Library["Library-only state"]
        F["FolderRecord, favourites, deletedAt"]
        W["WorkflowRecord"]
    end
    M --> I
    O --> I
    P --> C
    I --> S
    I --- F

# Manifest

DocumentManifest (Model/Document.swift) holds the title, creation and modification dates, PDF metadata and the ordered pages. Each PageRecord has an identifier, a PageSource (.image(file:) or .pdf(file:pageIndex:)), its size and a PageEdit. Reordering, rotating, cropping, filtering, duplicating and deleting pages are all changes to this file; the captures are not rewritten.

DocumentStore.save(_:) encodes the manifest and writes it with Data.write(options: .atomic), so a reader sees the previous or the new version and never a partial file. A manifest that cannot be decoded is reported as ORIXError.corruptedManifest; a missing one as documentNotFound.

# Staged creation and recovery

A new document is built as a DocumentStore.Draft under Staging/: beginDraft(title:), then addImage / addPDF, then commit, which writes the manifest and moves the whole directory into Documents/ in one step. Nothing is visible in the library before that move. commit refuses a draft with no page (emptyDocument). merge and derive (duplicate, split, extract) use the same mechanism and leave their sources untouched.

recoverAfterLaunch(), called from AppModel.start(), removes whatever an interrupted session left behind: every directory in Staging/, every directory in Exports/, and stray .tmp- files in document directories.

# Originals and shared files

Captured images are stored byte for byte (addImage writes the data it receives; the pixel size is read with ImageIO without decoding). A file ImageIO cannot read is removed and reported as unreadableImage.

duplicatePage copies the page record and its recognition but not the image: both pages reference the same original. When a page is deleted or retaken, removeFilesIfUnreferenced deletes the original only if no remaining page uses it. deletePages refuses to remove every page of a document.

# Library index

Three SwiftData models (Library.schema):

Model Content
DocumentRecord id (unique), title, dates, isFavorite, deletedAt, page count, byte size, kind, hasText, folded searchText, snippet, optional folder
FolderRecord id (unique), name, creation date, inverse relationship to its documents (delete rule: nullify)
WorkflowRecord id (unique), name, creation date, the Workflow encoded as JSON

LibraryIndex (main actor) keeps the index in step with the files:

  • refresh(_:) rebuilds a record from the manifest, the document's text and its size on disk. searchText is the title and the text folded with Library.fold (case, diacritics and width insensitive).
  • reconcile(now:), run at launch, adds records for documents found on disk without one, drops records whose files are gone, and permanently deletes documents whose deletedAt is older than Library.retentionDays (30 days).

Because records are derived from the files, the document entries can be rebuilt if the store is lost. Folder membership, favourites and the Recently Deleted state exist only in the index. User workflows also live only there.

Filtering and sorting are done in memory by Library.query(_:scope:filter:search:sort:ascending:) over the fetched records; title sorting uses localizedStandardCompare, so "Scan 2" precedes "Scan 10".

# Recently Deleted

Deleting a document sets deletedAt on its record (LibraryIndex.moveToTrash); its files stay in place. Restoring clears the date. deletePermanently removes the directory and the record. Expired documents are removed by reconcile at launch.

# Caches

DocumentProcessor.cachedPreviewURL writes preview JPEGs to cache/, named by page identifier, PageEdit.cacheKey and size, so an edit produces a new file and an unchanged page is served from disk. The key is an FNV-1a hash and is stable across launches. ThumbnailCache in the app adds an NSCache of decoded images, emptied on memory warnings (AppModel.releaseMemory). clearAllCaches() deletes every preview; they are regenerated on demand. Cache files are excluded from the size shown for a document.

# File protection

On iOS the root directory, and each document directory at commit, is given FileProtectionType.completeUntilFirstUserAuthentication. Files are encrypted at rest and become readable after the first unlock following a restart. This class was chosen so that recognition started in the foreground can finish if the device locks while it runs.

# Low storage

ensureSpace(for:) compares the bytes about to be written, plus a 50 MB reserve (DocumentStore.storageReserve), with the volume's available capacity and throws ORIXError.insufficientStorage before writing. It is called before adding or inserting images and PDFs, before saving a manifest, before copying a document and before exporting. The app shows "Not Enough Storage"; the operation has not started, so nothing is lost.

# Exports

Each export gets its own directory from makeExportDirectory() under Exports/, so files keep their natural names (Title.pdf) without colliding. A failed or cancelled PDF export removes its directory. Everything left in Exports/ is deleted at the next launch.

Files main
Menu

Theme