Architecture

noy-db is a zero-knowledge, offline-first, encrypted document store: one hub package (@noy-db/hub) that does all encryption and querying, surrounded by satellite packages for storage, unlock, export, and framework integration. This section is the reference layer for how that system is put together — for readers who need the shape of the system itself, not just its API. It distills the noy-db repository's own architecture notes (the nested-cores frame and the classification guide), and its pages mirror the real packages/hub/src/ tree, level by level — start here for the frame, then follow the tree down.

The containing architecture — nested cores

Four words carry everything below. The enclave is the self-contained crypto interior: the encryption functions, the keys, and the data format, behind a frozen interface. The kernel is the always-on core that holds the enclave — a vault (an encrypted database instance), its collections (the typed record sets inside it), the query engine, the keyring (the structure that wraps each collection's data keys), and the service bus (the internal event bus opt-in services listen on). The hub is the @noy-db/hub package: the kernel plus opt-in service layers. The families are the satellite packages, named by preposition — to-* storage backends, on-* unlock methods, at-* sealing hosts, in-* framework bindings, by-* sync transports, as-* exporters.

The whole product is one composition rule applied at four scales: a minimal core, an opt-in periphery, and a frozen seam between them, with a mechanical guard holding the seam. Each level is the next level's core.

The widest scale, level 3, zooms out past the noy-db package itself to the separate, independently-versioned repositories built around it, each binding one of noy-db's frozen seams rather than reaching into its internals:

• klum-db is a control-plane repository that orchestrates a fleet of noy-db vaults — federation, cross-vault query, and custody — by binding the /cargo subpath.
• noy-db-to is a repository of extended storage adapters: the cloud, SQL, and remote-filesystem backends (to-postgres, to-aws-s3, to-sqlite, …) that don't ship in the core, bound to /to at a pinned version range.
• noy-db-ui is a UI repository — a framework-agnostic, schema-driven list/search engine plus a Nuxt binding — that reads a collection's shape through collection.describe().
• noy-db-docs is this documentation site: it consumes published versions of all of the above and publishes nothing itself.

The guard column names real CI checks (scripts/check-architecture.mjs in the noy-db repo). Four of its terms deserve a definition:

• A barrel is a folder's single index.ts re-export file — the folder's entire public surface in one module. The enclave barrel (capsule/enclave-aes/index.ts) is the frozen contract the rest of the kernel consumes, and the seam a sister project replaces wholesale (see Enclave).
• A ratchet is a check with a checked-in per-file violation count: the count may never rise, and any genuine reduction must be recorded in the baseline — so pre-existing violations can only shrink toward zero, never silently grow.
• A line ceiling is a per-file line budget on the always-on kernel files: when a file would grow past its ceiling, the new capability must move into an opt-in service instead of enlarging the core.
• Golden-frozen subpaths are import paths whose export surface is snapshotted in a checked-in JSON file that a test compares against the real exports — the contract changes only deliberately, never by accident (see Ports). NO_X stubs are the inert placeholder implementations (NO_HISTORY, NO_BLOBS, …) substituted when a service is not opted into, letting the real code tree-shake out of the bundle.

Three invariants make the recursion more than a diagram:

• The one-way law, with one deliberate arrow-flip. At levels 1–3 the periphery binds the core's frozen contract and the core never imports outward. At level 0 the arrow flips: the spine consumes the enclave's frozen barrel — because the crypto is the innermost core, protected from everything, including the kernel itself.
• The trust gradient. Every seam crossing sheds capability, monotonically: enclave (raw keys) → kernel (DEK — the collection's data-encryption key — handles
  • plaintext) → services (plaintext, opt-in, scoped) → families (ciphertext-only, or post-decrypt as a consumer) → sister repos (published surface only) → docs (published versions only). Docs are the terminus of both gradients — this site documents pinned, published versions of each upstream package, never unreleased code.
• Isolation hardens outward. The same seam idea, implemented with progressively stronger mechanisms: tree-shaking + NO_X stubs (level 1) → package boundary + golden-frozen subpaths (level 2) → repo boundary + npm peer ranges (level 3) → version-pinned sync state for the ring that holds no code at all.

At every level the economics are identical: pay only for the rings you opt into — an unused service tree-shakes out, an unused family is a package you never install, a multi-vault control plane you don't need is a repo you never touch.

The model — the containment view

The four equations above, read spatially, are a nest of containment: enclave ⊂ kernel ⊂ hub ⊂ noy-db ⊂ product family.

family — the satellites: to- in- on- as- by- at-   (separate packages)

hub  (@noy-db/hub)
├─ kernel — the always-on, mandatory core: vault · collection · query · keyring · bus
│    └─ enclave — self-contained, frozen-interface, swappable:
│                 encryption functions + keys + data format
└─ layers — optional, tree-shaken; each a  with-<name>/  folder + a  with<Name>()  factory
     · service — an in-vault capability (history, blobs, aggregate, crdt, …)
     · cargo   — the layer that manages pods  (used by klum)
     · pod     — serialize a vault ⇄ a pod  (the saved / at-rest / transportable artifact)

Containment: enclave ⊂ kernel ⊂ hub; layers sit beside the kernel inside the hub; family is outside the hub. [layers] is an organizational grouping today — it is the seam where services may later harden into a real runtime plug-in interface.

The real source tree

The pages in this section mirror packages/hub/src/ in the noy-db repo, one page per level:

Definitions

Who binds what

Next

Kernel → — the always-on core, mirroring kernel/.

Or jump into the Orientation map to pick capabilities and land on the exact pages you need.