marchon/master-zapier-plan-draft
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Split NATS modules: splitter, WORM bloom archive, aggregator, docs-master
Some checks are pending
offline / test (push) Waiting to run
Details

Browse source 
Each module has SUMMARY.md and NATS.md (who sends/receives, subject
addresses, payload). Tests: splitter 3, worm 3, aggregator 2.
Forgejo repos pushed separately; this commit keeps them in the monorepo.
This commit is contained in:
George Lambert 2026-09-11 12:33:40 -04:00
parent ca693366dc
commit 8f9707a3b7
39 changed files with 893 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

52
docs/02-architecture/modules-and-nats.md Normal file
View file

@ -0,0 +1,52 @@
# Modules and NATS message contracts
Master map of every service in the Zapier ↔ middleware ↔ chain ↔ WORM-archive path.
Zapier cloud **never** connects to NATS. Only middleware workers and archives do.
## Who talks to whom (HTTPS vs NATS)
```text
[Zapier Platform app] HTTPS [zappier-edge] HTTPS [middleware-http]
|
NATS JetStream (NS1 loopback :4222) |
+------------------+------------------+-------------+
| | |
[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 |
| 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 |
| verae-chain-client | `verae-chain-client` | Library | — | HTTPS `api.veraetime.net` or MOCK |
| 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.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.