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.

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)

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

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

Zapier → GET /zapier/v1/auth/me  Authorization: Bearer zmw_…
Middleware: resolve API key → tenant → optional validate Verae token
→ { tenantId, plan, usage, ... }

Feature flags

Security boundaries

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 — subjects, streams, payload schemas
• ../plans/phase-gates.md — test gates
• ../../TODO.md — full implementation order