Milestone 0: import zappier billing, Verae middleware, and Zapier research

Compose-ready workspace: packages/zappier (rate card, portal, Stripe), packages/verae-zapier-middleware (timestamp + NATS), packages/verae-zapier (CLI app), vendor/zapier-platform, and research/zapier vendor corpus. Gate 0 structure checks pass. Product code and research are not yet wired.
2026-09-09 02:37:36 -04:00 · 2026-09-09 02:37:36 -04:00 · b4150c8250
commit b4150c8250
1364 changed files with 6814366 additions and 0 deletions
--- a/docs/02-architecture/overview.md
+++ b/docs/02-architecture/overview.md
@ -0,0 +1,132 @@
+# Architecture Overview
+
+## Purpose
+
+Connect Zapier automations to Verae blockchain timestamping without:
+
+- exposing raw Verae JWTs to end users,
+- requiring Zapier to poll async jobs,
+- coupling billing/plans to the core timestamping API,
+- running multi-instance middleware with in-memory only job queues.
+
+## Components
+
+### 1. `verae-zapier` (Zapier Platform CLI app)
+
+**Runs on:** Zapier’s cloud when a Zap step executes.
+
+**Responsibilities:**
+
+- Custom auth field `api_key` (middleware-issued `zmw_…` keys).
+- Map Zapier actions/searches/triggers to middleware HTTPS routes.
+- Attach `Authorization: Bearer <api_key>` on every request.
+- Translate middleware `402` / `403` into user-visible Zapier errors.
+
+**Does not:**
+
+- Call `api.veraetime.net` directly.
+- Speak NATS.
+- Enforce plan quotas (middleware does).
+
+### 2. `verae-zapier-middleware` HTTP edge
+
+**Runs on:** Your infrastructure (public HTTPS).
+
+**Responsibilities:**
+
+- Tenant identity and API keys.
+- Auth bridge: API key → Verae login → JWT (server-side).
+- Entitlement checks and usage metering.
+- Synchronous API surface under `/zapier/v1/*`.
+- REST Hook subscribe/unsubscribe storage.
+- Publish async work to NATS when `NATS_ENABLED=true`.
+
+### 3. NATS + JetStream
+
+**Runs on:** Private network with middleware.
+
+**Responsibilities:**
+
+- Durable work queue for job status polling.
+- Event stream for terminal job states.
+- Work queue for Zapier webhook HTTP delivery with retries.
+
+### 4. Workers
+
+**Runs on:** Same deploy as middleware or separate worker processes.
+
+| Worker | Consumes | Calls |
+|--------|----------|-------|
+| Job poller | `verae.zapier.jobs.watch` | `GET /api/status/{jobId}` on Verae |
+| Event router | `verae.zapier.jobs.events` | Enqueues webhook deliveries |
+| Webhook deliver | `verae.zapier.webhooks.deliver` | `POST` Zapier `targetUrl` |
+
+### 5. `api.veraetime.net` (Verae Timestamping Service)
+
+**Source of truth** for login, timestamp jobs, status, and verification.
+
+OpenAPI: production Swagger / `Verae-Swagger.yaml`.
+
+## Request flows
+
+### A. Create Timestamp (async)
+
+```text
+Zapier → POST /zapier/v1/timestamp
+Middleware: authenticate, checkEntitlement, POST /api/timestamp
+Middleware: publish jobs.watch → return 202 { jobId }
+Worker: poll status until terminal → publish jobs.events
+Event router: match webhooks → publish webhooks.deliver
+Webhook worker: POST hooks.zapier.com/...
+```
+
+### B. Create Timestamp and Wait
+
+```text
+Zapier → POST /zapier/v1/timestamp/wait
+Middleware: create + wait for jobs.events (or in-process wait if NATS off)
+→ return StatusResponse (completed/failed) or pending+jobId on timeout
+```
+
+### C. Auth connection test
+
+```text
+Zapier → GET /zapier/v1/auth/me  Authorization: Bearer zmw_…
+Middleware: resolve API key → tenant → optional validate Verae token
+→ { tenantId, plan, usage, ... }
+```
+
+## Feature flags
+
+| Flag | Effect |
+|------|--------|
+| `NATS_ENABLED=false` | In-process job poller; still full HTTP API (Phase 6 path) |
+| `NATS_ENABLED=true` | JetStream workers; no in-process poller |
+| `MOCK_VERAE=true` | No live Verae; deterministic mock jobs for tests |
+| `DEBUG_VERAE=…` | Runtime failure tracing (see debugging.md) |
+
+## Security boundaries
+
+```text
+Public Internet
+  ├─ Zapier → Middleware HTTPS only
+  └─ Middleware → Zapier webhook HTTPS only
+
+Private
+  ├─ Middleware ↔ NATS
+  └─ Middleware/Workers → api.veraetime.net HTTPS
+```
+
+Never expose NATS ports to the public internet.
+
+## Scaling model
+
+- **HTTP edge:** scale replicas behind a load balancer (stateless except shared store).
+- **NATS consumers:** queue groups — adding workers increases poll/deliver throughput.
+- **Store:** file JSON is MVP single-node; Postgres/Redis required for multi-node (Phase 15).
+
+## Related documents
+
+- [nats-subjects.md](nats-subjects.md) — subjects, streams, payload schemas
+- [../plans/phase-gates.md](../plans/phase-gates.md) — test gates
+- [../../TODO.md](../../TODO.md) — full implementation order