Add dev-overview: designed vs running NATS routes and Zapier-Verae path.
Some checks failed
offline / test (push) Has been cancelled

Independent Forgejo repo maps every verae.* address, endpoint I/O, job
monitor loop, and remaining billing/archive wiring.
This commit is contained in:
George Lambert 2026-09-14 13:25:04 -04:00
commit 86b421db05

View file

@ -0,0 +1,76 @@
# Designed vs running NATS routes
**Designed** = named in docs (`modules-and-nats.md`, `MESSAGE-FLOWS.md`, per-package `NATS.md`) or in code (`subjects.js`, fleet JSON).
**Running** = a process on NS1 is subscribed or publishing it **today**, and (for durable work) a JetStream stream exists.
Cluster name `verae`. Internal URL: three LXC on `vmbr1`. Public edge is a **leaf**, not a second cluster.
Legend: **JS** = JetStream stream; **RR** = core request-reply; **pub** = core or JS fire-and-forget; **Q** = queue group.
## JetStream streams (running)
Created by `verae-nats-cluster/scripts/ensure-streams.sh` (and middleware `ensureStreams` for the first three).
| Stream | Subjects | Replicas | Storage | Who consumes |
|--------|----------|----------|---------|--------------|
| `ZAPIER_JOBS` | `verae.zapier.jobs.watch` | 3 | file | job-poller (in middleware process) |
| `ZAPIER_EVENTS` | `verae.zapier.jobs.events` | 3 | file | middleware wait + webhook router; optional exclusive `jobs-events` |
| `ZAPIER_WEBHOOKS` | `verae.zapier.webhooks.deliver` | 3 | file | webhook-deliver (in middleware process) |
| `ZAPIER_USAGE` | `verae.zapier.usage` | 3 | file | **no durable consumer running** (`USAGE_WRITER` is named only) |
| `VERAE_ARCHIVE` | `verae.archive.>` | 3 | file | worm + tree on LXC 510 (keep); aggregator **not** fleet-enabled |
## Address inventory
| Address | Kind | Designed | Running | Notes |
|---------|------|----------|---------|-------|
| `verae.zapier.jobs.watch` | JS work Q `job-poller` | yes | **yes** | middleware publishes; in-process poller consumes |
| `verae.zapier.jobs.events` | JS events | yes | **yes** | poller publishes; wait() subscribes; webhook worker routes |
| `verae.zapier.webhooks.deliver` | JS work Q `webhook-deliver` | yes | **yes** | middleware worker in same Node process as HTTP |
| `verae.zapier.usage` | JS optional | yes | stream **yes**, consumer **no** | middleware entitlement is **local files**, not this subject |
| `verae.internal.jobs.events` | core republish | yes (`jobs-events` exclusive) | **partial** | only if `JOBS_EVENTS_EXCLUSIVE=1` |
| `verae.billing.statement.get` | RR | yes | **yes** | account-balance |
| `verae.billing.balance.get` | RR | yes | **yes** | account-balance |
| `verae.billing.balance.adjust` | RR | yes | **yes** | CS credits, portal reload |
| `verae.billing.usage.recorded` | pub | yes | **partial** | designed from zappier-edge meter; confirm publisher on live edge |
| `verae.billing.payment.recorded` | pub | yes | **partial** | portal reload / invoice |
| `verae.billing.credit.applied` | pub | yes | **partial** | CS goodwill |
| `verae.billing.customer.put` | RR/pub | yes (account-balance `subjects.js`) | **unclear** | books write |
| `verae.access.authz.check` | RR Q `access-authz` | yes | **yes** | fleet keepFloor |
| `verae.access.authz.deny` | pub audit | yes | **yes** (on deny) | |
| `verae.access.web.*` | ingress | yes | **yes** | access-web after HTTP |
| `verae.access.api.*` | ingress | yes | **yes** | |
| `verae.access.zapier.*` | ingress | yes | **yes** | HTTPS plane, not Zapier NATS |
| `verae.access.leaf.in` / `verae.access.leaf.*` | ingress | yes | **yes** | no billing |
| `verae.access.staff.*` | ingress | yes | **yes** | CS/sales/accounting |
| `verae.identity.bind` | RR Q `identity` | yes | **yes** (fleet enabled) | |
| `verae.identity.lookup` | RR Q `identity` | yes | **yes** | |
| `verae.archive.put` | JS (`VERAE_ARCHIVE`) | yes | **partial** | splitter is **in-process** in middleware; worm/tree on 510 consume |
| `verae.archive.query` | broadcast (no Q) | yes | **partial** | live aggregator hook **TBD** in middleware (simulator has it) |
| `verae.archive.reply.<id>` | replies on bloom hit | yes | **partial** | worm/tree on 510 can reply; aggregator not fleet-enabled |
| `verae.splitter.in` | future | yes (docs) | **no** | splitter stays a library |
| `verae.example.process.in` / `.out` / `.reply.*` | template | yes | **no** | `verae-nats-process` is a model, not a live worker |
| `bench.*` | lab only | n/a | ephemeral | speed studies; not product |
## Fleet overlay vs in-process
`overlays/ns1/fleet.json` (2026-09-14):
| Service | fleet `enabled` | Actual lab |
|---------|-----------------|------------|
| middleware-http | true | **running**; also starts job-poller + webhook workers in-process when `NATS_ENABLED` |
| job-poller | **false** | covered by middleware, not a second fleet spawn |
| webhook-deliver | **false** | same |
| archive-aggregator | **false** | **not** running as a fleet worker |
| archive-worm / tree-node | **false** on host fleet | **running on LXC 510** via `verae-keep` `units.px-worker.json` (1 worm + 1 tree) |
| account-balance, access-*, identity, jobs-events, CS/sales/acct, staff-iam/session | true | keepFloor |
| zapier-simulator | true, keepFloor false | optional |
| nats | managed false | 3-node cluster + leftover host loopback |
## Docs that name routes (do not invent extras)
- `packages/docs-master/modules-and-nats.md`, `MESSAGE-FLOWS.md`
- `packages/overview/03-nats-cluster.md`, `06-address-routing.md`
- `packages/verae-ops/06-linking-services.md`
- Each package `NATS.md`
- `verae-nats-cluster/scripts/ensure-streams.sh`
- Public edge: `verae-nats-cluster/conf/public-edge.conf.tmpl` (leaf, not a new subject family)