# Verae × Zapier System Documentation Map **Source root:** `/SSD2/sites/zapier.georgelambert.org` on `70.88.205.138` (NS1.GEORGELAMBERT.ORG) **Public catalog:** https://zapier.georgelambert.org/ **Mapped:** 2026-10-03 **Scope:** Documentation tree only (not live `/opt/verae/zappier-edge` runtime audit) --- ## 1. Docs structure ### Site layout | Path | Role | |------|------| | `/SSD2/sites/zapier.georgelambert.org/` | Published catalog (Caddy) | | `README.md` | Monorepo entry; composition of zappier + middleware + Zapier app | | `TODO.md` | Middleware phase gates 0–15 | | `docs/` | Numbered product/architecture books + modules/models | | `docs-master/` | Per-module SUMMARY + NATS contracts + MESSAGE-FLOWS | | `overview/` | System overview book (01–11) + diagrams | | `packages/` | ~41 independent module packages (README + PDF each) | | `live/` | Screenshots of public doors | | `user-docs/` | Customer-facing guides | | `simulator/` | Static simulator UI copy | | `sphinx/` | Sphinx HTML build of modules/models | | `research/` | Vendor Zapier research | ### `docs/` tree ``` docs/ 00-sources/ workspace-brief, provenance, getting-started-research, FUNCTIONS/PLATFORM/MCP refs, veraetime-openapi.yaml, LOGIN/MONGO/RESTART 01-product/ features-a-m, api-gap-analysis, billing-and-keys, zapier-billing-research 02-architecture/ overview, composition, modules-and-nats, nats-subjects, nats-gateway, archive-nats, fleet, tree-nodes 03-zapier/ auth, operations, README 04-activate/ SETUP-ZAPIER-DEVELOPER api/ middleware-openapi.yaml developer/ debugging + modules/ models/ data model sheets (+ models-pdf/) modules/ per-source-module API sheets (+ modules-pdf/) plans/ phase-gates.md sphinx/ RST/MD sources for Sphinx OPEN.md, WORK-LOG.md ``` ### `docs-master/` - `README.md`, `composition.md`, `modules-and-nats.md`, `archive-nats.md` - `MESSAGE-FLOWS.md`, `HOST-DEPS.md`, `CATALOG-HOST.md` - `modules//{SUMMARY,NATS}.md` for each package ### `overview/` | Doc | Topic | |-----|--------| | `01-system.md` | Planes, hard rule (Zapier never NATS) | | `02-modules-and-repos.md` | Forgejo repos | | `03-nats-cluster.md` | 3-server JetStream | | `04-uptime.md` | Replica floors | | `05-network-failures.md` | Reconnect / silence | | `06-address-routing.md` | New functions = new subjects | | `07-external-resources.md` | Chain / storage | | `08-diagrams.md` | SVG + mermaid | | `09-expansion-template.md` | verae-nats-process | | `10-docs-sync.md` | Catalog sync | | `11-hostnames.md` | Ports, DNS, public doors | | `NATS.md`, `SUMMARY.md`, `INDEX.md` | Shortcuts | ### `plans/` - Single plan book: `docs/plans/phase-gates.md` (gates 0–15; mirrors root `TODO.md`) --- ## 2. Key document summaries ### Architecture / overview **`docs/02-architecture/overview.md`** - Connect Zapier to Verae without exposing JWTs, forcing Zapier to poll, or coupling billing to the chain API. - Components: `verae-zapier` (Zapier cloud), middleware HTTPS, NATS JetStream, workers, `api.veraetime.net`. - Flows: async create → `jobs.watch` → poll → `jobs.events` → webhook; wait path; auth `/auth/me`. - Flags: `NATS_ENABLED`, `MOCK_VERAE`, `DEBUG_VERAE`. - Still describes public auth as middleware `zmw_` Bearer (pre-composition framing). **`docs/02-architecture/composition.md`** - Target path: Zapier → zappier `/v1/*` (`x-api-key`) → middleware `/zapier/v1/*`. - Ownership split: billing/portal = zappier; stamp/NATS/hooks = middleware; nouns = verae-zapier. - Zapier never talks to NATS or live Verae; payment invoices ≠ timestamp receipts. **`docs/02-architecture/modules-and-nats.md`** - Master module table (edge, middleware, poller, webhook, splitter, aggregator, WORM, tree-node, fleet, simulator). - Subjects: `verae.zapier.jobs.{watch,events}`, `webhooks.deliver`, `verae.archive.{put,query,reply.*}`. - Zapier cloud never on NATS. **`docs/02-architecture/nats-subjects.md`** - Streams: `ZAPIER_JOBS`, `ZAPIER_EVENTS`, `ZAPIER_WEBHOOKS`, optional `ZAPIER_USAGE`. - Payload schemas + ack/Nak semantics for poller and webhook deliver. - Prefer `tokenRef` over JWT in messages; NATS private + auth. **`docs/02-architecture/archive-nats.md` / `fleet.md` / `tree-nodes.md`** - Off-chain WORM + Merkle leaf proofs; bloom miss = silence. - Fleet replica floors (worm/tree min 3); operator console `:3850`. **`overview/01-system.md`** - Planes: Zapier, web, API, leaf, staff, authz, commercial edge, account-balance, CS/sales/acct, middleware, NATS, workers, archives, chain, fleet. - One-sentence request path through meter → stamp → watch/events → billing NATS. **`overview/11-hostnames.md`** - NS1 `70.88.205.138`; LXC 510 worker; NATS LXC 511–513 at `10.10.10.21–23`. - Full service→port→DNS table (portal/api/zap/staff/iam/mw/fleet/git/catalog). - zappier-edge on `127.0.0.1:13000` (tunnel); note that host `:3000` is “another app”. - NATS never public; public token edge documented separately in nats-cluster package. **`overview/NATS.md` / `03-nats-cluster.md`** - Central 3-server JetStream; new functions = new addresses; Zapier never connects. ### STATUS / decisions / NATS lab **`packages/zapier-decisions/STATUS.md` (2026-09-12)** - Working lab on NS1; public doors 8/8 OK; keep+fleet up; test 3-node JetStream on `vmbr1`. - Product streams replicas=3: `ZAPIER_JOBS`, `ZAPIER_EVENTS`, `ZAPIER_WEBHOOKS`, `ZAPIER_USAGE`, `VERAE_ARCHIVE`. - Clients use `nats://10.10.10.21:4222,...`; host loopback `:4222` unused by clients. - Open: Zapier Platform push; `MOCK_VERAE=false`; nkeys/mTLS; lan-134; reboot ownership. - Mock path submit→jobId→wait→receipt proven; live chain seal not proven. **Decisions (`packages/zapier-decisions/decisions/`)** - **D001** — Account-balance (`books.json`) is sole prepaid writer; edge `balanceCents` is cache. - **D002** — `veraeUserId` join key; public credential = zappier API key; JWT = `tokenRef` server-side. - **D003** — Access planes are only public HTTP doors (`:3021–3025`); edge on loopback `:3000`. - **D004** — Leaf cannot touch billing (policy allow-list). - **D005** — HTTP spawn local-first; `lan-134` disabled. - **D006** (2026-10-03) — Business SoT → **libSQL**; JetStream = work queues only; **core NATS** for `verae.ts.completed` / `verae.ts.receipt`; Go timestamping DBs stay local; lab `billing.db`/`zappier.db`/`books.json` are single-host stand-ins. **`docs-master/MESSAGE-FLOWS.md`** - Async stamp, wait, idempotent hash, `includeAttached`, multipart, batch Merkle, simulator replay. **`docs/plans/phase-gates.md` / `TODO.md`** - Gates 0–12 largely passed in source/mock; 13–15 (live Verae, private Zapier push, hardening) open. - Root README still says “9 and 12+ open” in places — stale vs gate logs. **`docs/OPEN.md`** - Needs human: Zapier login/push; live Verae gaps (hash lookup etc.); PDF artwork; LTS/share not live; NATS public bind left loopback (superseded by cluster/token edge notes elsewhere). --- ## 3. Packages (`packages/`) — what each does | Package | Role (from README) | |---------|-------------------| | **overview** | High-level system book; Zapier never NATS; address routing | | **docs-master** | Per-module SUMMARY/NATS; MESSAGE-FLOWS; catalog host move | | **dev-overview** | Designed vs running NATS fabric map; credentials cheat sheet | | **ui-docs** | Operator/staff/portal screenshot walkthrough + UI-REVIEW.pdf | | **zapier-decisions** | STATUS, LOG, TODO, D001–D006, NATS bench reports | | **zapier-user-docs** | Customer guide: signup → stamp → lookup → tree proofs | | **zappier** (Forgejo: zappier-edge) | Metered API, portal, admin, Stripe, invoices, rate card | | **zappier-account-balance** | Prepaid SoT (`books.json`); NATS `verae.billing.*` | | **zappier-customer-service** | CS credits/review UI `:3011` | | **zappier-sales-pricing** | Per-customer pricing UI `:3012` | | **zappier-accounting-export** | QuickBooks IIF / CSV export `:3013` | | **zappier-identity** | Bind/lookup `veraeUserId` ↔ customer (`:3026`) | | **verae-zapier-middleware** | `/zapier/v1/*`, NATS workers, mock/live chain client `:3100` | | **verae-zapier** | Full Zapier Platform app (creates/searches/triggers) | | **verae-activate** | Tiny “Add Numbers” push-first Zapier app | | **verae-zapier-simulator** | In-process Zapier+trace console `:3847` | | **verae-access-authz** | Default-deny `verae.access.authz.check` `:3020` | | **verae-access-web** | Browser portal plane `:3021` | | **verae-access-api** | Direct customer API plane `:3022` | | **verae-access-leaf** | S2S leaf plane `:3023` (no billing) | | **verae-access-zapier** | Zapier HTTPS front door `:3024` | | **verae-access-staff** | Staff plane UI `:3025` | | **verae-staff-iam** | Staff users/roles/audit `:3028` | | **verae-staff-session** | Shared staff cookie login `:3027` | | **verae-staff-ui** | Shared review HTML template | | **verae-request-splitter** | Hash vs archive puts (in-process today) | | **verae-archive-worm** | Bloom WORM off-chain store | | **verae-archive-aggregator** | Fan-out query + merge replies | | **verae-tree-node** | Merkle leaf proof WORM (`kind=tree`) | | **verae-jobs-events** | Mailbox for `jobs.events` `:3030` (passthrough today) | | **verae-fleet** | Replica floors, spawn, operator console `:3850` | | **verae-keep** | Crash restart unless paused (`:3860`/`:3861`) | | **verae-ops** | Docker/Proxmox/metal install + linking runbooks | | **verae-bootstrap** | Clone all Forgejo modules + host-deps | | **verae-deploy** | Tag checkout + npm ci on target hosts | | **verae-proxmox** | LXC worker (510) provision | | **verae-nats-cluster** | LXC 511–513 JetStream cluster scripts | | **verae-nats-accounts** | Leaf allow-list + future nkeys sketch | | **verae-nats-process** | Template for new addressed workers | | **verae-uptime** | Off-box HTTPS door probes `:3870` | | **verae-backup** | Tar snapshots under `/SSD2/backups/verae/` | --- ## 4. Extracted system facts (as documented) ### Services & ports (NS1 lab catalog) | Service | Port | Bind (docs) | Public door / DNS | |---------|------|-------------|-------------------| | Docs catalog | 443 | Caddy | **zapier.georgelambert.org** | | Forgejo | 443 / SSH **2223** | Caddy | **git.georgelambert.org** | | Fleet console | 3850 | 0.0.0.0 | fleet.zapier.georgelambert.org | | Portal (access-web) | 3021 | 0.0.0.0 | portal.zapier… | | Customer API | 3022 | 0.0.0.0 | api.zapier… | | Leaf | 3023 | 0.0.0.0 | leaf.zapier… | | Zapier plane | 3024 | 0.0.0.0 | **zap.zapier.georgelambert.org** | | Staff plane | 3025 | 0.0.0.0 | staff.zapier… | | Authz | 3020 | 0.0.0.0 | internal | | Identity | 3026 | 0.0.0.0 | id.zapier… | | Staff session | 3027 | 0.0.0.0 | login.zapier… | | Staff IAM | 3028 | 0.0.0.0 | iam.zapier… | | Account-balance | 3010 | 0.0.0.0 | books.zapier… | | CS / Sales / Acct | 3011 / 3012 / 3013 | 0.0.0.0 | cs / sales / acct | | Middleware | 3100 | 0.0.0.0 | mw.zapier… | | jobs.events mailbox | 3030 | 0.0.0.0 | events.zapier… | | zappier-edge (admin) | **13000** (loopback) or **:3000** in older docs | 127.0.0.1 | tunnel only | | Keep / watch | 3860 / 3861 | 127.0.0.1 | — | | Simulator | 3847 | optional | sim.zapier… | | Uptime status | 3870 | 127.0.0.1 | — | | Workers | 13200–13602 | 127.0.0.1 | — | | NATS clients | 4222 | private `10.10.10.21–23` | never public product path | | NATS cluster routes | 6222 | vmbr1 | never public | | NATS monitor | 8222 | loopback on nodes | — | | Optional public NATS edge | 4222 / WSS | token-gated on 138 | nats.zapier… (not for Zapier) | **Also documented elsewhere (live product, not this catalog’s primary story):** `zap.verae.ai` / `zappier-edge.service` on `:3040` under `/opt/verae/zappier-edge` — see Conflicts. ### NATS subjects & streams **JetStream product streams (replicas=3):** `ZAPIER_JOBS`, `ZAPIER_EVENTS`, `ZAPIER_WEBHOOKS`, `ZAPIER_USAGE`, `VERAE_ARCHIVE` | Subject | Kind | Purpose | |---------|------|---------| | `verae.zapier.jobs.watch` | JS work | Poll chain status | | `verae.zapier.jobs.events` | JS events | Terminal job outcomes → waiters/webhooks | | `verae.zapier.webhooks.deliver` | JS work | POST Zapier REST Hook | | `verae.zapier.usage` | optional JS | Usage export | | `verae.archive.put` | JS | Off-chain put | | `verae.archive.query` | broadcast | Bloom query | | `verae.archive.reply.` | reply | Hit-only | | `verae.billing.statement.get` | req-reply | Statement | | `verae.billing.balance.get` | req-reply | Balance | | `verae.billing.balance.adjust` | req-reply | Credits/reloads | | `verae.billing.usage.recorded` | pub | Meter | | `verae.billing.payment.recorded` | pub | Payments | | `verae.billing.credit.applied` | pub | CS credits | | `verae.access.authz.check` | req-reply | Allow/deny | | `verae.access.{web,api,zapier,leaf}.*` | ingress | Plane fronts | | `verae.identity.bind` / `.lookup` | req-reply | Identity map | | `verae.ts.completed` / `verae.ts.receipt` | **core NATS** (D006 / standing rule) | Job-complete notify — **not** JetStream | Client URL (lab): `nats://10.10.10.21:4222,nats://10.10.10.22:4222,nats://10.10.10.23:4222` ### Databases / data stores (documented) | Store | Owner | Contents | |-------|-------|----------| | **`books.json`** | zappier-account-balance (D001) | Prepaid, credits, usage, payments (lab SoT) | | **`zappier.db`** | zappier-edge | Auth/sessions/admin (also older monolith docs) | | **`billing.db`** | live edge / D006 note | Customers, usage_entries (+ hash chain), rates, invoices (138 stand-in) | | **libSQL (target)** | D006 | Shared business SoT across 3–5 hosts | | Middleware file JSON / `data/` | middleware | Tenants, webhooks, blobs (MVP; Postgres/Redis Phase 15) | | WORM / tree blobs | archive-worm, tree-node | Off-chain metadata/files/leaf proofs | | JetStream store | nats-a/b/c | Durable work/events/archive streams | | Keep/fleet runtime | `~/verae-*-runtime` | Intent + spawned unit state | | Backups | `/SSD2/backups/verae/` | Tar snapshots (not private keys) | | Go `blockchain.db` | timestamping-svc | **Do not relocate** (D006) | ### Public doors (D003) - Browser → `:3021` / portal.zapier… - Customer API → `:3022` / api.zapier… - Zapier → `:3024` / zap.zapier… - Leaf → `:3023` - Staff → `:3025` (+ iam/login) - Catalog → zapier.georgelambert.org - Git → git.georgelambert.org - Edge admin/Stripe/identity stay loopback (not a public door) ### Identity model (D002 + access planes) - **Public credential:** zappier API key (`x-api-key`); portal signup/regen. - **Middleware legacy:** `zmw_` / `zmt_` Bearer (internal / pre-composition). - **Chain auth:** Verae login → JWT held as `tokenRef` server-side; never in Zapier. - **Join key:** `veraeUserId` (`vu_…`) via `zappier-identity` bind/lookup. - **Staff:** `verae-staff-iam` roles (owner, cs, sales, accounting, operator, …) + session cookie. - **Planes:** zapier / web / api / leaf / staff — each must pass `authz.check` before internal subjects; leaf cannot bill. ### Userflows (documented) 1. **Signup** → portal → API key (Free). 2. **Connect Zap** → HTTPS access-zapier / edge with API key. 3. **Create Timestamp (async)** → meter → middleware → chain → `jobs.watch` → 202 `{jobId}` → poll → `jobs.events` → REST Hook. 4. **Create and Wait** → same, HTTP holds until event or timeout → `pending`+`jobId`. 5. **Idempotent SHA-256** → original seal / `existing: true`. 6. **Attachments / includeAttached** → archive.put + query/merge. 7. **Batch Merkle** → root on chain; leaves on tree-nodes; lookup via `kinds=["tree"]`. 8. **CS credit / portal reload / sales pricing / accounting export** via `verae.billing.*`. 9. **Simulator** replays 1–7 in-process with fault injection. --- ## 5. Conflicts / outdated claims | Topic | Claim A | Claim B | Notes | |-------|---------|---------|-------| | Wiring status | Root README: packages “imported, **not yet wired**” | STATUS: working lab, doors 8/8, NATS cluster live | README composition blurb is stale | | Public auth | Overview / verae-zapier: Bearer **`zmw_`** | Composition / D003 / billing docs: **`x-api-key`** via zappier | Transition incomplete in docs | | Prepaid SoT | D001: **`books.json`** via account-balance | Live edge memory / D006: **`billing.db`** + **`zappier.db`**; target **libSQL** | Three eras coexist in writing | | Edge port | D003 / ops: **`:3000`** loopback | Hostnames: **`:13000`**; “`:3000` is another app” | Also live **`zap.verae.ai:3040`** outside this catalog | | Public Zap host | Catalog: **zap.zapier.georgelambert.org** | Product memory: **zap.verae.ai** | Dual branding / cutover | | NATS location | Many docs: loopback `:4222` | STATUS / nats-cluster: **10.10.10.21–23**; loopback unused by clients | Hostnames table still lists loopback NATS | | Job-complete bus | Architecture: **`verae.zapier.jobs.events` on JetStream** | D006 + standing rule: **`verae.ts.*` on core NATS only** | Naming + persistence conflict; do not JetStream job-complete notify | | Gate progress | README: phases **9 and 12+ open** | phase-gates gate logs: **9 and 12 pass** | Stale README sentence | | MOCK / live | STATUS: still **MOCK_VERAE** | Some defaults printed as `MOCK_VERAE=false` | Live seal not proven | | NATS accounts | D004 sketches accounts | STATUS: cluster **without** nkeys; isolation = vmbr1 | Expected | | Metering owner | Middleware `PLAN_LIMITS` in older overview | Composition: metering on **zappier** only | Correct direction = composition | | Hash lookup | Features a–m: mock done | Live OpenAPI: **no** hash route; client 501 | Gap documented | | docs-master diagram | Still shows “NS1 loopback :4222” for JetStream | Cluster cut-over done | Update modules-and-nats diagram | --- ## 6. Source-of-truth files (prefer these) | Concern | Prefer | |---------|--------| | Current lab status | `packages/zapier-decisions/STATUS.md` | | Accepted architecture decisions | `packages/zapier-decisions/decisions/D00*.md` (esp. **D003**, **D006**) | | System planes / hard rules | `overview/01-system.md` | | Hostnames & ports | `overview/11-hostnames.md` | | NATS streams (Zapier jobs/webhooks/archive) | `docs/02-architecture/nats-subjects.md` + STATUS streams list | | Billing subjects | `docs-master/modules-and-nats.md` + `packages/zappier-account-balance/README.md` | | Message userflows | `docs-master/MESSAGE-FLOWS.md` | | Composition ownership | `docs/02-architecture/composition.md` | | Product features a–m | `docs/01-product/features-a-m.md` | | Ops bring-up | `packages/verae-ops/GETTING-STARTED.md` (+ PDF) | | Module catalog | `docs-master/README.md` + `packages/*/README.md` | | Phase implementation order | `docs/plans/phase-gates.md` / `TODO.md` | | Customer narrative | `packages/zapier-user-docs/` | | Designed vs running NATS | `packages/dev-overview/` | **Standing overrides outside this tree (operator rules / memory):** - Never JetStream for timestamp job-complete (`verae.ts.completed` / `verae.ts.receipt`). - Live commercial edge on 138: `/opt/verae/zappier-edge`, `billing.db` + `zappier.db`, service `:3040`, public `zap.verae.ai`. - D006: migrate business data to shared **libSQL** before multi-host split. --- ## 7. Quick system map (ASCII) ```text [Zapier cloud: verae-zapier / activate] HTTPS only | +------------------+------------------+ | | access-zapier :3024 (alt) zappier-edge /v1 | | +---------> middleware :3100 <--------+ | \ chain HTTPS \-- NATS JetStream (jobs/webhooks/archive) api.veraetime.net | or MOCK_VERAE workers: poller, webhook, aggregator, worm×N, tree×N Browser :3021 API :3022 Leaf :3023 Staff :3025 \ | / authz.check :3020 | billing.* ---- account-balance (books → libSQL) identity.* --- zappier-identity fleet :3850 / keep :3860 (ops) catalog: zapier.georgelambert.org ``` --- *End of documentation map. Absolute path of this report: `/tmp/zapier-system-docs-map.md`*