Skip to content

Operating Modes

Where things live. Where make happens. How the AFS, KLS, and OPS flow between actors.

The same product runs in five different topologies. What varies is where each store lives and who runs the build. The code paths converge.


  • AFS — the analytical framework. Git repo. All YAML, SQL, contracts, dbt models. Authored by people; make adds the extracted inputs and the build log.
  • KLS — the knowledge store. DuckDB file. Built from the AFS by make. Read-only once built.
  • OPS — the operational store. A per-tenant SQLite/WAL file, or a Cloudflare D1 in the always-on cloud modes. Notes, bookmarks, bell resolutions, selectors, desks, preferences. Mutable, and it lives next to the user.

The OPS has no arrow into the AFS. It is a side store JinDesk reads and writes — never a feedback path into the build. It outlives every KLS and is never rebuilt: restore it from a backup rather than regenerating it.


make is the single build entrypoint. It gathers its inputs, commits them to git, and only then builds the KLS — in that order, with every side effect on the far side of the commit.

make is the security boundary. Whoever controls make controls the analytical truth. The input phases run inside make but commit their outputs to the AFS before the build reads them, which means:

  • Every build is reproducible from the AFS commit it was built on.
  • Everything that went into the build is in git — auditable, reversible.
  • The build portion of make consumes only the AFS, nothing else. No network calls, no OPS access.

The AFS commit produced at the end of each build captures the whole run in its history.

Terminal window
jin inspect # read-only view of the extraction surface
jin inspect --contract # full pipeline.yml contract (purpose, source, output, expected)
jin inspect --check # verify SHA-256 hashes without running extraction

inspect never runs extraction — for that, use jin make.


Everything on one machine. The developer’s laptop.

  • Who runs make: the developer, on the same machine
  • Auth: none (god mode). Git identity from local git config
  • Git: local. Push the AFS to a remote when ready — or never

KLS and OPS on the data owner’s machine. JinDesk in the cloud, reaching both through the tunnel.

  • Who runs make: the data owner, locally
  • Auth: stealth (none) or an identified session
  • Git: the owner pushes the AFS; remote viewers never touch git
  • One OPS — on the owner’s machine. Everyone reads and writes the same OPS through the tunnel; the cloud stores nothing. Your data, your machine extends to operational state too

This is the primary mode for sensitive data. See the P2P2P concept page.

KLS uploaded to R2. JinDesk and the OPS (a D1 per tenant) in the cloud.

  • Who runs make: the developer, locally. Then jin ship builds, uploads the KLS, and refreshes the running instances — or jin sync converges everything, both directions
  • Auth: required for all cloud users
  • The refresh matters: uploading to R2 changes nothing by itself. A running instance is still serving the KLS it downloaded on boot, so publishing ends with a per-tenant, ETag-conditional refresh — only the tenants that actually changed are swapped
  • OPS — one D1 per tenant. The strongest isolation available: a cross-tenant query is impossible, not merely discouraged
  • Why: always-on, low-latency, shareable by URL. The trade-off: the KLS leaves the site

KLS built locally and stays. The OPS follows it home. No KLS upload.

  • Who runs make: the owner, locally
  • Why: compliance — the analytical data can’t leave the site
  • The OPS follows the KLS (local by default), reached through the tunnel as in Mode 2. It may live in the cloud as a D1 only where policy allows
  • Auth: required for cloud users

The difference from Mode 2 is intent, not wiring: Mode 2 chooses local because the data is sensitive; Mode 4 is required to by policy.

make runs in the cloud. No local machine needed.

  • Who runs make: a cloud worker — a long-lived daemon on a cloud machine, or a one-shot container
  • It is the same make. The worker does not reimplement the build; it shells out to jin make and streams that run’s events back as they happen, so a cloud build is subject to exactly the same input/build split as a laptop one
  • Trigger: a run request to the worker, a schedule, or a push
  • Buckets instead of a working copy: the runner can pull and push every store — the AFS included — from object storage, so this topology needs no git remote at all
  • Auth: a bearer token on every worker endpoint but the liveness check

A deployed server is not a read-only consumer of R2 — it can build. Mode 3 describes the common topology today, not a limit on what a server is.


The OPS serves two roles. All of it stays in the OPS.

RoleContentRetention
MemoryNotes, bookmarksLong-term
MemoryBell resolutions, selectors, desksLong-term
MemoryAcknowledgments, roster, preferencesLong-term
MessengerRecents (navigation journal)Short-term, rotated
MessengerSession state (current filters, scroll)Session-only

Authored notes still reach the KLS, by a separate path: they are written as AFS YAML and baked at build time. That is authoring. A note created in JinDesk stays in the OPS.

One OPS per tenant. Not local plus cloud — one instance, one truth. Where it lives is a deployment decision:

ModeOPS lives…Reached by…
LocalThe developer’s machineJinDesk on localhost
Proxy / Semi-CloudThe owner’s machine — the cloud is only a tunnelJinDesk through the proxy
Cloud / Make-as-a-ServiceThe cloud — one D1 per tenantJinDesk directly

Nobody needs git to use JinDesk. Git is the AFS’s transport and provenance layer, not the runtime: it carries the framework between machines and records what each build was made from. Notes, bookmarks and selectors never go near it.


FactorLocalProxyCloudSemi-CloudMake-as-Service
KLS locationLocalLocalCloud (R2)LocalCloud (R2)
OPS locationLocalLocal (via tunnel)Cloud (D1)Local (via tunnel)Cloud (D1)
Who runs makeDeveloperOwnerDeveloperOwnerCloud worker
Operational complianceBestBestKLS in cloudKLS localFull cloud
CollaborationSingle userMulti-user (session)Multi-user (always on)Multi-userMulti-user
Internet requiredNoYesYesYesYes
Git knowledge neededAuthor onlyAuthor onlyAuthor onlyAuthor onlyAuthor only
Setup complexityTrivialOne commandR2 credentialsProxy + policy callWorker + credentials
Viewer login—Optional (stealth)RequiredRequiredRequired

Recommendation: start with Local (Mode 1) and Proxy (Mode 2) for sensitive data. Move to Cloud (Mode 3) for non-sensitive. Make-as-a-Service (Mode 5) is the shape for scale.


The cut inside make — between gathering the inputs and building from them — is the security boundary, and it is drawn across a git commit.

  • The input phases have side effects: they pull from source systems, write into the AFS, and commit.
  • The build phases have none: they read the AFS and write the KLS. That’s it. No network calls, no OPS access.

Everything that feeds a build is in git — auditable, reproducible, reversible. The OPS is the collaboration layer: it doesn’t need git, it doesn’t need make, it’s where people work. Everything else is infrastructure.


jazzisnow jinflow is a jazzisnow product
v0.65.0 · built 2026-11-13 10:20 UTC