Expand dev-overview: transport ports, sources, billing publishers, finish list

Document designed vs running NATS subjects and cluster TCP/leaf/public
endpoints, per-address I/O, Zapier→Verae job path, and unwired modules.
This commit is contained in:
George Lambert 2026-09-14 13:32:51 -04:00
commit 1c728c5513

View file

@ -16,17 +16,17 @@ Modules and addresses that are designed but **not fully connected, not running a
| Module | Running? | NATS | Gap |
|--------|----------|------|-----|
| middleware HTTP + in-process job-poller + webhook-deliver | **yes** | watch/events/deliver | live Verae + Zapier push |
| account-balance | **yes** | billing RR | edge may not publish `usage.recorded` on every Zap |
| account-balance | **yes** | billing RR + `usage.recorded` sub | prove 402 from books on a Zap when prepaid is 0 |
| zappier-edge | **yes** | `usage.recorded` / `payment.recorded` / `credit.applied` / `customer.put` **if `NATS_URL`** | confirm live process env; Stripe live |
| access-* + authz | **yes** | authz + ingress | — |
| identity | **yes** (fleet) | bind/lookup | confirm portal always binds `veraeUserId` |
| jobs-events mailbox `:3030` | **yes** (fleet) | events counter | exclusive consumer off unless `JOBS_EVENTS_EXCLUSIVE=1` |
| CS / sales / accounting | **yes** | statement/adjust | staff UX |
| zappier-edge | **yes** | billing after authz | meter → NATS; Stripe live |
| archive-worm + tree-node | **yes on LXC 510** (keep) | `archive.put/query/reply` | only **1+1** copies; fleet overlay `enabled: false` for extra replicas |
| archive-aggregator | **no** as fleet worker | query/reply | enable overlay **or** finish in-process hook (`includeAttached` TBD in middleware) |
| request-splitter | library in middleware | `archive.put` | `verae.splitter.in` not used |
| `ZAPIER_USAGE` / `USAGE_WRITER` | stream yes | `verae.zapier.usage` | no consumer; middleware usage is local files |
| fleet job-poller / webhook-deliver **extra** copies | overlay **false** | same subjects | only enable if you want SSH-spread replicas **instead of** in-process (do not double-consume without queue groups — in-process already uses queue names) |
| fleet job-poller / webhook-deliver **extra** copies | overlay **false** | same subjects | only enable if you want SSH-spread replicas **instead of** in-process (same queue names) |
## Designed, not a live worker
@ -36,32 +36,45 @@ Modules and addresses that are designed but **not fully connected, not running a
| `verae-activate` | none (HTTPS Zapier) | optional tiny app; needs Zapier login |
| `verae-zapier` (full app) | HTTPS | push after login |
| simulator | in-process fake NATS | local `:3847`; not production |
| `verae-nats-accounts` | nkeys policy | not flipped |
## Billing triggers and event logging (aux)
## Aux (no product subjects, or HTTP only)
| Signal | Designed | Finish |
|--------|----------|--------|
| Timestamp/verify meter | `verae.billing.usage.recorded` + optional `verae.zapier.usage` | Publish from edge/middleware `recordUsage`; consume into account-balance; 402 from books not only local quota |
| Portal reload | `payment.recorded` + `balance.adjust` | confirm both fire on Stripe/test reload |
| CS credit | `balance.adjust` + `credit.applied` | running for adjust; confirm applied pub |
| Authz deny audit | `verae.access.authz.deny` | running on deny; no SIEM sink |
| Job lifecycle log | `jobs.events` | running; mailbox counts only — add structured log/export if needed |
| Archive put/query | `VERAE_ARCHIVE` | 510 worm/tree; aggregator not in wait path |
| Keep/fleet | no NATS | HTTP health only — fine |
| Uptime | HTTPS GET | no NATS |
| Backup | disk/JS snapshot | no live event subject |
| Public NATS edge | leaf, token | **do not** use from Zapier; rotate token; consider nkeys |
| Module | NATS | Notes |
|--------|------|-------|
| `verae-keep` | none | HTTP health; restarts units |
| `verae-fleet` | none | catalog + keepFloor |
| `verae-uptime` | none | off-box HTTPS GET of public doors |
| `verae-backup` | none | disk / JetStream snapshot; no live event subject |
| `verae-bootstrap` / `verae-deploy` / `verae-proxmox` / `verae-ops` | none | install/link |
| staff-iam / staff-session / staff-ui | none | HTTP cookies |
| public NATS edge | leaf, token | **do not** use from Zapier; rotate token; later nkeys LEAF vs INTERNAL |
## Billing triggers and event logging
| Signal | Designed | Running | Finish |
|--------|----------|---------|--------|
| Timestamp/verify meter (edge) | `verae.billing.usage.recorded` | **code path exists** (`zappier/src/app.ts` `onUsage`) | Confirm `NATS_URL` on live edge; 402 from account-balance when prepaid empty |
| Middleware quota | local files `recordUsage` | **yes** | Either publish `usage.recorded` too or drop duplicate quota |
| Optional JS meter | `verae.zapier.usage` + `USAGE_WRITER` | stream only | Wire or delete |
| Portal reload | `payment.recorded` + `balance.adjust` | coded | confirm both fire on Stripe/test reload |
| CS credit | `balance.adjust` + `credit.applied` | coded | confirm applied pub on live |
| Customer upsert | `customer.put` | coded | — |
| Authz deny audit | `verae.access.authz.deny` | running on deny | **no SIEM sink** |
| Job lifecycle log | `jobs.events` | running | mailbox counts only — add structured log/export if needed |
| Archive put/query | `VERAE_ARCHIVE` | 510 worm/tree | aggregator not in wait path |
| Public edge | leaf | running | rotate token; do not expose `:6222` |
## Ordered finish for message routing
1. **Do not double-start** job-poller: either in-process **or** fleet copies, same queue `job-poller`.
2. Wire **usage**: `recordUsage` → `verae.billing.usage.recorded` (and/or `verae.zapier.usage` + `USAGE_WRITER`).
2. Confirm edge **`NATS_URL`** so `usage.recorded` actually lands; then 402 from books. Unify or drop middleware local `recordUsage`.
3. Enable **archive-aggregator** (or in-process equivalent) so `includeAttached` and tree proofs work on wait/status.
4. Raise worm/tree **replica floors** on 510/more CTs if archive HA is required (fleet overlay min 3).
5. Operator: Zapier `push` + `MOCK_VERAE=false`.
6. Prove: Zap create → `jobs.watch` → live `GET /api/status` → `jobs.events` → wait body + REST Hook.
7. nkeys/mTLS after every client has creds; then lock down the public edge to accounts (LEAF vs INTERNAL).
8. Optional: exclusive `jobs-events` mailbox; SIEM on `authz.deny` and `jobs.events`; `verae.splitter.in` if splitter is split out.
8. Optional: exclusive `jobs-events` mailbox; SIEM on `authz.deny` and `jobs.events`; `verae.splitter.in` if splitter is split out; `USAGE_WRITER` or delete `ZAPIER_USAGE`.
## What is already enough for a mock Zap