82 lines
6 KiB
Markdown
82 lines
6 KiB
Markdown
# Modules and NATS message contracts
|
||
|
||
Master map of every service in the Zapier ↔ middleware ↔ chain ↔ WORM-archive path.
|
||
|
||
Zapier cloud **never** connects to NATS. Internal services do: middleware workers, archives, account-balance, zappier-edge billing, CS, sales, and accounting.
|
||
|
||
## Who talks to whom (HTTPS vs NATS)
|
||
|
||
```text
|
||
[Zapier Platform app] HTTPS [zappier-edge] HTTPS [middleware-http]
|
||
| | NATS verae.billing.* |
|
||
| v |
|
||
[customer portal] [account-balance] NATS JetStream
|
||
[CS :3011] queue account-balance (NS1 loopback :4222)
|
||
[sales :3012] ^ |
|
||
[accounting :3013] | request-reply |
|
||
+-------------------------------+
|
||
+------------------+------------------+-------------+
|
||
| | |
|
||
[job-poller] [webhook-deliver] [archive-aggregator]
|
||
| |
|
||
| HTTPS | NATS query/reply
|
||
[verae-chain-client] |
|
||
[archive-worm × N]
|
||
bloom miss = silence
|
||
```
|
||
|
||
## Module catalog
|
||
|
||
| Module | Repo (Forgejo) | Runtime | Listens | Sends |
|
||
|--------|----------------|---------|---------|-------|
|
||
| zapier-platform-app | `verae-zapier-app` | Zapier cloud | User Zap steps | HTTPS to zappier-edge |
|
||
| zappier-edge | `zappier-edge` | Public HTTPS :3000 | Zapier, portal, admin | HTTPS to middleware; NATS billing after authz |
|
||
| access-authz | `verae-access-authz` | :3020 + NATS | `verae.access.authz.check` | allow/deny |
|
||
| access-web | `verae-access-web` | :3021 | customer browser | billing statement/reload |
|
||
| access-api | `verae-access-api` | :3022 | x-api-key | statement; HTTPS to middleware |
|
||
| access-leaf | `verae-access-leaf` | :3023 | S2S leaf | archive/jobs only |
|
||
| access-zapier | `verae-access-zapier` | :3024 | Zapier HTTPS | jobs.watch after authz |
|
||
| account-balance | `zappier-account-balance` | :3010 + NATS | `verae.billing.*` | statement/adjust replies |
|
||
| customer-service | `zappier-customer-service` | :3011 | CS staff HTTP | NATS balance.adjust / statement.get |
|
||
| sales-pricing | `zappier-sales-pricing` | :3012 | Sales HTTP | NATS statement.get; HTTPS to edge for multipliers |
|
||
| accounting-export | `zappier-accounting-export` | :3013 | Accounting HTTP | reads invoices; NATS statement |
|
||
| middleware-http | `verae-middleware` | Public HTTPS :3100 | zappier-edge | NATS jobs.watch; HTTP to chain; wait on jobs.events |
|
||
| job-poller | `verae-job-poller` | Worker | `verae.zapier.jobs.watch` | `verae.zapier.jobs.events`; HTTP GET chain status |
|
||
| webhook-deliver | `verae-webhook-deliver` | Worker | `verae.zapier.webhooks.deliver` + events | HTTPS POST Zapier REST Hook |
|
||
| request-splitter | `verae-request-splitter` | In middleware | HTTP body / multipart | chain hash; `verae.archive.put` |
|
||
| archive-aggregator | `verae-archive-aggregator` | Worker / in wait | `includeAttached` on wait | `verae.archive.query`; reads `verae.archive.reply.<id>` |
|
||
| archive-worm | `verae-archive-worm` | N copies | `verae.archive.query`, `verae.archive.put` | `verae.archive.reply.<id>` if bloom hits |
|
||
| tree-node | `verae-tree-node` | N copies (WORM role) | `verae.archive.query`, `verae.archive.put` kind `tree` | `verae.archive.reply.<id>` if bloom hits |
|
||
| zapier-simulator | `verae-zapier-simulator` | Local HTTP :3847 | operator browser | in-process replay of all addresses |
|
||
| zapier-user-docs | `zapier-user-docs` | Static | — | catalog `/user-docs/` |
|
||
| verae-chain-client | `verae-chain-client` | Library | — | HTTPS `api.veraetime.net` or MOCK |
|
||
| fleet | `verae-fleet` | Local HTTP :3850 | operator | keepFloor + SSH hosts |
|
||
| overview | `overview` | Static | — | high-level map |
|
||
| nats-process | `verae-nats-process` | Template worker | `verae.example.process.in` | `.out` / `.reply.*` |
|
||
| docs-master | `zapier-docs-master` | Static | — | published on zapier.georgelambert.org |
|
||
|
||
## Addresses (subjects)
|
||
|
||
| Address | Kind | Payload (required fields) |
|
||
|---------|------|---------------------------|
|
||
| `verae.zapier.jobs.watch` | JetStream work queue | `tenantId`, `jobId`, `tokenRef`, `enqueuedAt`, `attempt`, `maxAttempts`, `intervalMs`, `traceId` |
|
||
| `verae.zapier.jobs.events` | JetStream events | `event` (`timestamp.completed\|failed\|timeout`), `tenantId`, `jobId`, `status`, `traceId`, `emittedAt` |
|
||
| `verae.zapier.webhooks.deliver` | JetStream work queue | `hookId`, `tenantId`, `targetUrl`, `event`, `payload`, `attempt`, `traceId` |
|
||
| `verae.zapier.usage` | optional | `tenantId`, `action`, `amount`, `at` |
|
||
| `verae.billing.statement.get` | request-reply | `customerId` → prepaid, credits, usage, payments |
|
||
| `verae.billing.balance.adjust` | request-reply | `customerId`, `cents`, `reason`, `agent` |
|
||
| `verae.billing.usage.recorded` | pub | meter events from zappier-edge |
|
||
| `verae.billing.payment.recorded` | pub | portal reload / invoice paid |
|
||
| `verae.billing.credit.applied` | pub | CS goodwill |
|
||
| `verae.access.authz.check` | request-reply | `{ plane, subject, principal }` → `{ allow, reason }` |
|
||
| `verae.access.web.billing.statement.get` | ingress | web plane only; mapped after authz |
|
||
| `verae.access.api.*` | ingress | customer API plane |
|
||
| `verae.access.zapier.*` | ingress | Zapier plane |
|
||
| `verae.access.leaf.in` | ingress | S2S leaf; never billing |
|
||
| `verae.archive.put` | JetStream | `sha256`, `tenantId`, `kind` (`publicMeta\|privateMeta\|file\|tree`), `record`, `traceId` |
|
||
| `verae.archive.query` | pub to **all** archives | `correlationId`, `sha256`, `tenantId`, `kinds[]`, `traceId` |
|
||
| `verae.archive.reply.<correlationId>` | replies | `archiveId`, `sha256`, `records[]`, `traceId` |
|
||
|
||
## Completed job JSON (back to Zapier)
|
||
|
||
See `docs/02-architecture/archive-nats.md`. Seal receipts from chain; extra receipts and `files[]` from archive aggregation when `includeAttached` is true.
|