George Lambert
b4150c8250
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.
132 lines
3.9 KiB
Markdown
132 lines
3.9 KiB
Markdown
# 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
|