Operating Modes

Where things live. Where make happens. How AFS, KLS, and SIS 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.

---

The Three Stores

• AFS — the analytical framework. Git repo. All YAML, SQL, contracts, published notes/bookmarks. Written by humans and by pre-make.
• KLS — the knowledge store. DuckDB file. Built from the AFS by make. Read-only once built.
• SIS — the system information store. DuckDB file. Notes, bookmarks, audit, preferences. Mutable. Lives next to the user.

---

The Two-Phase Pipeline

The pipeline has two distinct phases:

1. pre-make (preparation) — gathers inputs from external systems AND from SIS, writes them to the AFS, commits to git.
2. make (build) — reads only from AFS, writes only to KLS. A pure function.

Why the split?

make is the security boundary. Whoever controls make controls the analytical truth. Keeping it side-effect-free means:

• Every build is reproducible from the AFS commit it was built on.
• make has no network access, no SIS access, no external fetches.
• Everything that went into the build is in git — auditable, reversible.

pre-make has all the side effects. It touches the outside world (DLZ, source systems, APIs) and talks to the SIS. When it commits, the AFS carries the full preparation in its history.

The jinflow pre-make command

jinflow pre-make                               # extract + publish SIS content (default tenant)
jinflow pre-make millesime.domaine_zufferey    # specific tenant
jinflow pre-make --notes-only                  # just publish SIS content
jinflow pre-make --extract-only                # just extract sources

Internally, pre-make:

1. Connects to the SIS (local file or cloud API, depending on mode)
2. Fetches notes → writes to afs/notebook/*.yaml
3. Fetches bookmarks → writes to afs/bookmarks/*.yaml
4. Extracts and syncs source data → raw/
5. git commit -m "pre-make: sync sources + publish SIS content"

The key: pre-make knows where the SIS is. In local mode, it reads the file. In cloud mode, it calls the Explorer API. The developer doesn’t care.

---

The Five Modes

Mode 1 — Local

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 to GitHub when ready

Mode 2 — Proxy (P2P2P)

KLS on the data owner’s machine. Explorer in the cloud. One SIS in the cloud.

• Who runs make: the data owner, locally
• Auth: stealth (none) or GitHub OAuth for identified sessions
• Git: owner pushes AFS; remote users never touch git
• One SIS: lives in the cloud. Everyone — owner, CFO, analyst — reads and writes the same SIS

See: P2P2P concept page.

Mode 3 — Cloud (R2)

KLS uploaded to R2. Explorer and SIS in the cloud.

• Who runs make: the developer, locally. Then jinflow cloud sync pushes KLS to R2
• Auth: GitHub OAuth for all cloud users
• Why: always-on, low-latency, shareable via URL. The tradeoff: data leaves the site

Mode 4 — Semi-Cloud

KLS stays local. SIS in the cloud. No KLS upload.

• Who runs make: the developer, locally
• Why: compliance — analytical data can’t leave the site, but user activity (SIS) is fine in the cloud
• Auth: GitHub OAuth for cloud users

Mode 5 — Make-as-a-Service

make runs in the cloud. No local machine needed.

• Who runs make: a cloud service (GitHub Actions, Fly.io Machine, Cloudflare Worker)
• Trigger: git push to AFS, scheduled cron, or manual (jinflow make --remote)
• Auth: GitHub for developers (push triggers build). OAuth for Explorer users

This is the endgame. The developer never runs make locally. They push AFS changes; the cloud pre-makes and builds; the Explorer serves the result.

---

The SIS — Messenger and Memory

The SIS serves two roles:

Role	Content	Retention	Published to AFS?
Memory	Notes, bookmarks	Long-term	Yes (pre-make → YAML)
Memory	Audit trail, acknowledgments, preferences	Long-term	No (SIS-only)
Messenger	Recents (navigation journal)	Short-term, rotated	No (ephemeral)
Messenger	Session state (current filters, scroll)	Session-only	No (ephemeral)

One SIS per tenant. Not local + cloud. One instance, one truth. Location is a deployment decision:

Mode	SIS lives…	Accessed by…
Local	Developer’s machine	Explorer (localhost)
Proxy / Semi-Cloud / Cloud	Cloud (Explorer server or R2)	Explorer (cloud) + pre-make (remote fetch)
Make-as-a-Service	Cloud	Explorer + cloud pre-make (direct)

Nobody needs git to create notes. Git is only needed to run pre-make, which publishes SIS content to the AFS. make then reads from AFS, not SIS.

---

Decision Matrix

Factor	Local	Proxy	Cloud	Semi-Cloud	Make-as-Service
Data location	Local	Local	Cloud (R2)	Local (KLS) / Cloud (SIS)	Cloud
Who runs make	Developer	Owner	Developer	Developer	Cloud worker
Hospital compliance	✅ Best	✅ Best	❌ KLS in cloud	✅ KLS local	❌ Full cloud
Collaboration	Single user	Multi-user (session)	Multi-user (always on)	Multi-user	Multi-user
Internet required	No	Yes	Yes	Yes	Yes
Git knowledge needed	Author only	Author only	Author only	Author only	Author only
Setup complexity	Trivial	One command	R2 credentials	Proxy + cloud SIS	CI/CD + deploy keys
Viewer login	—	Optional (stealth)	Required	Required	Required

Recommendation: Start with Local (Mode 1) + Proxy (Mode 2) for sensitive data. Move to Cloud (Mode 3) for non-sensitive. Make-as-a-Service (Mode 5) is the long-term vision for scale.

---

The Cut

The cut between pre-make and make is the security boundary.

• pre-make has side effects: writes to AFS, touches SIS, pulls from DLZ, commits to git.
• make has none: reads AFS, writes KLS. That’s it.

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

---

Related

• Pipeline Overview — the layer-by-layer transformation
• Deploy Guide — how to stand each mode up in practice
• P2P2P concept — deep dive on Mode 2
• Make guide — day-to-day usage