Start here

Orifold is a native macOS PDF workspace: Swift 5.9+, 100% SwiftUI, four local PDF engines plus a signing pipeline, 752 tests, and no networking beyond the user-initiated trusted-timestamp request. This page orients you before you open the tree.

Read these first, in this order

What is Orifold? — the product in one screen.
Why Orifold? — the trade-offs made on purpose.
Architecture overview — the unidirectional flow and staged export pipeline.
The engines — PDFKit, PDFium, qpdf, Vision, and signing.
Build from source — get it compiling.
Developer FAQ — the questions everyone asks.

Module map

Orifold/
  App/             Entry point, command wiring, keyboard-shortcut registry
  DesignSystem/    Visual tokens and styling
  Document/        macOS document package read/write
  Engine/          Load, repair, convert, OCR, compress, encrypt, sanitize, forms, export, Recently Viewed
  Models/          Workspace, page, annotation, comment, export, decoration, comfort, recent-file
  Pet/             Gami & Ori companions + hint placement
  Resources/       Metadata, entitlements, assets, Localizable.xcstrings (6 languages)
  Signing/         Digital-ID providers, CMS/PAdES construction, timestamping, trust, appearance
  ViewModels/      Workspace state, document ops, search, export, undo
  Views/           SwiftUI interface
Packages/          Vendored engines — PDFiumBinary, QPDFBinary (universal static libs)
Tests/             The release-gate suites

The risk map — touch these carefully

Area	Why it’s sensitive
Export pipeline (`Engine/`, `ViewModels/`)	A staged sequence gated by a qpdf structural check. Break the order or the gate and exports silently lose data or fail to write.
Encryption & sanitize	Real AES-256 and content-stripping. Bugs here are security bugs, not cosmetics.
Signing (`Signing/`)	Byte-exact ByteRange/CMS construction. A one-byte offset error produces an invalid signature.
Text-layer preservation	The import normalizer keeps text layers PDFKit would drop. Regressions bring back the “edit lands on top” bug.
The local-only boundary	Only the two sandbox file entitlements plus app-scope bookmarks. Never add networking beyond user-initiated TSA timestamp requests.
Localization coverage	A test enforces all 6 languages. New user-facing strings must land in `Localizable.xcstrings`.

Ori's note

Ori’s note: understand the export pipeline before you touch anything that feeds it. Its validation gate is the last line between a good file and a corrupt one — and it fails closed on purpose.

The onboarding promise

If swift test passes on your machine, you’re set up. That’s the whole bar.