Initial import of overview from zapier monorepo

08-diagrams.md

@@ -0,0 +1,66 @@
+# 8. Architectural diagrams
+
+SVG files in [`diagrams/`](diagrams/). The same shapes are repeated below in mermaid for Forgejo preview.
+
+## 8.1 End-to-end (HTTPS vs NATS)
+
+![System](diagrams/system.svg)
+
+```mermaid
+flowchart LR
+  Z[Zapier cloud] -->|HTTPS plane=zapier| AZ[access-zapier]
+  Web[customer browser] -->|HTTPS plane=web| AW[access-web]
+  API[customer API] -->|HTTPS plane=api| AA[access-api]
+  Leaf[S2S leaf] -->|verae.access.leaf.in| AL[access-leaf]
+  AZ --> Authz[access-authz]
+  AW --> Authz
+  AA --> Authz
+  AL --> Authz
+  CS[staff CS/sales] --> Authz
+  Authz -->|allow| N[NATS cluster]
+  BAL[account-balance] --> N
+  AZ -->|HTTPS| M[verae-middleware]
+  M --> N
+  N --> P[job-poller]
+  N --> R[WORM]
+  N --> T[tree-node]
+  P --> C[Verae chain]
+  M --> C
+```
+
+## 8.2 NATS.IO 3-server cluster
+
+![Cluster](diagrams/nats-cluster.svg)
+
+```mermaid
+flowchart TB
+  subgraph cluster [Verae NATS.IO JetStream]
+    N1[nats-server A :4222 loopback]
+    N2[nats-server B]
+    N3[nats-server C]
+    N1 <--> N2
+    N2 <--> N3
+    N3 <--> N1
+  end
+  MW[middleware + workers] -->|cluster URL list| cluster
+  F[fleet SSH hosts] -->|workers only| cluster
+```
+
+## 8.3 Uptime and failure
+
+![Uptime](diagrams/uptime.svg)
+
+```mermaid
+flowchart TD
+  H[health /health] -->|fail| R[restart instance]
+  P[pause] -->|not available| F[keepFloor spawn]
+  S[SSH host down] -->|spawn failed| O[place on next machine]
+  Q[archive.query broadcast] -->|bloom miss| SIL[silence]
+  Q -->|hit| REP[archive.reply.id]
+```
+
+## 8.4 New address = new process
+
+![Routing](diagrams/routing.svg)
+
+See [09-expansion-template.md](09-expansion-template.md).