Add NATS account-balance SoT and statement review for customers, CS, and sales
Some checks are pending
offline / test (push) Waiting to run
Some checks are pending
offline / test (push) Waiting to run
Internal billing now uses verae.billing.* request-reply and pubs. zappier-account-balance tracks prepaid, credits, usage, and payments. Portal, admin, CS, and sales all review the same statement. Independent Forgejo repos stay split via push-module-repos.
This commit is contained in:
parent
a1a5b957fd
commit
ac38676645
135 changed files with 3078 additions and 130 deletions
|
|
@ -11,8 +11,9 @@ Verae Time proves a SHA-256 existed at a given time. Zapier lets customers regis
|
|||
| Plane | What | Network |
|
||||
|-------|------|---------|
|
||||
| Zapier cloud | `verae-zapier-app`, `verae-activate` | HTTPS to zappier-edge |
|
||||
| Commercial edge | `zappier-edge` portal, admin, `x-api-key`, Stripe meter | Public HTTPS |
|
||||
| CS / sales / accounting | `zappier-customer-service`, `zappier-sales-pricing`, `zappier-accounting-export` | Loopback/private HTTP into zappier-edge admin |
|
||||
| Commercial edge | `zappier-edge` portal, admin, `x-api-key`, Stripe meter | Public HTTPS; NATS billing pubs/requests |
|
||||
| Account balance | `zappier-account-balance` prepaid SoT | NATS `verae.billing.*` + HTTP `:3010` |
|
||||
| CS / sales / accounting | `zappier-customer-service`, `zappier-sales-pricing`, `zappier-accounting-export` | Private HTTP; NATS statement/adjust |
|
||||
| Middleware HTTP | `/zapier/v1/*` job id + wait | Public HTTPS from edge only |
|
||||
| NATS cluster | JetStream subjects under `verae.*` | Private; loopback or SSH tunnel |
|
||||
| Workers | poller, webhook-deliver, aggregator | NATS + HTTPS to chain or Zapier hooks |
|
||||
|
|
@ -22,6 +23,6 @@ Verae Time proves a SHA-256 existed at a given time. Zapier lets customers regis
|
|||
|
||||
## Request in one sentence
|
||||
|
||||
A Zap step POSTs to zappier-edge (`x-api-key`); edge meters the call and, when `ZAPPIER_UPSTREAM` is set, forwards timestamp/receipt/hash to middleware `/zapier/v1`. Middleware splits hash vs files, writes the hash (or Merkle root) to the chain, publishes `verae.zapier.jobs.watch`, and either returns `jobId` or waits on `verae.zapier.jobs.events`. Customer-service credits, sales per-customer multipliers, invoices, payment history, and QuickBooks export sit on zappier-edge (department APIs on :3011–:3013). Attached metadata and bulk-summary **leaves** are found later by broadcasting `verae.archive.query` to every archive/tree node.
|
||||
A Zap step POSTs to zappier-edge (`x-api-key`); edge meters the call and, when `ZAPPIER_UPSTREAM` is set, forwards timestamp/receipt/hash to middleware `/zapier/v1`. Middleware splits hash vs files, writes the hash (or Merkle root) to the chain, publishes `verae.zapier.jobs.watch`, and either returns `jobId` or waits on `verae.zapier.jobs.events`. Meter events, CS credits, and portal reloads go over NATS `verae.billing.*` to **account-balance** (source of truth). Customers review the same statement in the portal; CS (`:3011`) and sales (`:3012`) review it on their department UIs. Attached metadata and bulk-summary **leaves** are found later by broadcasting `verae.archive.query` to every archive/tree node.
|
||||
|
||||
See [diagrams](08-diagrams.md).
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@ Each runtime piece is its **own git repo** on Forgejo (`git.georgelambert.org`,
|
|||
| **verae-nats-process** | `packages/verae-nats-process` | **Template** for a new addressed NATS process |
|
||||
| **master-zapier-plan-draft** | workspace root | Combined snapshot (`main` and `master`) |
|
||||
| **zappier-edge** | `packages/zappier` | Metered HTTPS, portal, admin, Stripe; **proxies Verae calls to middleware** |
|
||||
| **zappier-account-balance** | `packages/zappier-account-balance` | NATS source of truth for prepaid balances |
|
||||
| **zappier-customer-service** | `packages/zappier-customer-service` | CS goodwill credits onto prepaid balances |
|
||||
| **zappier-sales-pricing** | `packages/zappier-sales-pricing` | Sales per-customer tier / multiplier |
|
||||
| **zappier-accounting-export** | `packages/zappier-accounting-export` | QuickBooks IIF + accounting CSV |
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ All durable messaging for this product is **NATS JetStream**, not Zapier queues
|
|||
|
||||
## Cluster
|
||||
|
||||
Three `nats-server -js` nodes form the Verae cluster (routes between them, JetStream replication). Clients (middleware, poller, aggregator, WORM, tree nodes, and any new process cloned from `verae-nats-process`) connect with a **cluster URL list**, for example:
|
||||
Three `nats-server -js` nodes form the Verae cluster (routes between them, JetStream replication). Clients (middleware, poller, aggregator, WORM, tree nodes, account-balance, zappier-edge billing, CS/sales/accounting, and any new process cloned from `verae-nats-process`) connect with a **cluster URL list**, for example:
|
||||
|
||||
```text
|
||||
nats://127.0.0.1:4222,nats://127.0.0.1:4223,nats://127.0.0.1:4224
|
||||
|
|
@ -20,7 +20,7 @@ Today’s NS1 box (`NS1.GEORGELAMBERT.ORG`, `70.88.205.138`) already runs JetStr
|
|||
|
||||
| Allowed | Forbidden |
|
||||
|---------|-----------|
|
||||
| verae-middleware, fleet workers, WORM, tree nodes, `verae-nats-process` clones | Zapier cloud, browsers, zappier-edge |
|
||||
| verae-middleware, fleet workers, WORM, tree nodes, account-balance, zappier-edge billing, CS/sales/accounting, `verae-nats-process` clones | Zapier cloud, customer browsers (they use HTTPS portal/CS/sales UIs) |
|
||||
|
||||
## Address families already in use
|
||||
|
||||
|
|
@ -30,6 +30,9 @@ Today’s NS1 box (`NS1.GEORGELAMBERT.ORG`, `70.88.205.138`) already runs JetStr
|
|||
| `verae.zapier.jobs.events` | events | wait + webhooks |
|
||||
| `verae.zapier.webhooks.deliver` | work queue | HTTPS to Zapier REST Hook |
|
||||
| `verae.zapier.usage` | optional | metering |
|
||||
| `verae.billing.statement.get` | request-reply | portal, CS, sales, admin |
|
||||
| `verae.billing.balance.adjust` | request-reply | CS credits, portal reload |
|
||||
| `verae.billing.usage.recorded` | pub | zappier-edge meter |
|
||||
| `verae.archive.put` | JetStream | splitter / merkle builder |
|
||||
| `verae.archive.query` | **broadcast** (no queue group) | every WORM and tree node |
|
||||
| `verae.archive.reply.<correlationId>` | replies | **only on bloom hit** |
|
||||
|
|
|
|||
|
|
@ -9,12 +9,15 @@ SVG files in [`diagrams/`](diagrams/). The same shapes are repeated below in mer
|
|||
```mermaid
|
||||
flowchart LR
|
||||
Z[Zapier cloud apps] -->|HTTPS x-api-key| E[zappier-edge]
|
||||
CS[customer-service] --> E
|
||||
SA[sales-pricing] --> E
|
||||
AC[accounting-export QuickBooks] --> E
|
||||
Cust[customer portal] -->|HTTPS statement| E
|
||||
CS[customer-service] -->|NATS statement/adjust| N[NATS 3-node cluster]
|
||||
SA[sales-pricing] -->|NATS statement| N
|
||||
AC[accounting-export] -->|NATS statement| N
|
||||
E -->|NATS billing| N
|
||||
BAL[account-balance] -->|reply verae.billing.*| N
|
||||
E -->|HTTPS metered| M[verae-middleware]
|
||||
M -->|HTTPS| C[Verae chain]
|
||||
M -->|JetStream| N[NATS 3-node cluster]
|
||||
M -->|JetStream| N
|
||||
N --> P[job-poller]
|
||||
N --> W[webhook-deliver]
|
||||
N --> A[archive-aggregator]
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue