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.
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 indexflowchart 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.searchTextis the title and the text folded withLibrary.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 whosedeletedAtis older thanLibrary.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.