marchon/overview
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial import of overview from zapier monorepo

Browse source
This commit is contained in:
George Lambert 2026-09-11 14:24:23 -04:00
commit 4b09a268ab
21 changed files with 605 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

104
README.md Normal file
View file

@ -0,0 +1,104 @@
# Verae Time × Zapier — system overview
High-level description of the whole system: what it is, which **independent git repositories** implement it, how it stays up, how it behaves when the local network fails, and how it talks to the **central Verae NATS.IO 3-server cluster**. New work is added by **new address routing**, not by teaching Zapier about NATS.
**This repo:** https://git.georgelambert.org/marchon/overview
**Live catalog (PDF by default):** https://zapier.georgelambert.org/ · [Markdown indexes](https://zapier.georgelambert.org/index-md.html)
**Clone:** `ssh://git@git.georgelambert.org:2223/marchon/overview.git`
## Table of contents
1. [System](01-system.md) — what runs where; Zapier never speaks NATS
2. [Modules and repositories](02-modules-and-repos.md) — every independent Forgejo repo
3. [NATS.IO 3-server cluster](03-nats-cluster.md) — JetStream, subjects, who may connect
4. [Uptime](04-uptime.md) — replica floors, restart, SSH spread
5. [Local network failures](05-network-failures.md) — reconnect, silence, pending, failover
6. [Address routing](06-address-routing.md) — how to add unplanned functions
7. [External resources](07-external-resources.md) — searches, storage, chain
8. [Architectural diagrams](08-diagrams.md) — SVG + mermaid
9. [Expansion template](09-expansion-template.md) — `verae-nats-process`
10. [Documentation index](INDEX.md) — pointer into all other docs
## One-screen picture
![System context](diagrams/system.svg)
Zapier → HTTPS `zappier-edge` → HTTPS `verae-middleware` → **NATS cluster** → workers, WORM archives, tree nodes. Chain HTTPS is `api.veraetime.net` (or MOCK). Fleet keeps minimum copies, including tree nodes.
## Independent repositories (Forgejo)
| Repo | Role |
|------|------|
| [overview](https://git.georgelambert.org/marchon/overview) | This document |
| [verae-nats-process](https://git.georgelambert.org/marchon/verae-nats-process) | **Model** for a new addressed process |
| [master-zapier-plan-draft](https://git.georgelambert.org/marchon/master-zapier-plan-draft) | Monorepo snapshot |
| [zappier-edge](https://git.georgelambert.org/marchon/zappier-edge) | Metered public HTTPS |
| [verae-middleware](https://git.georgelambert.org/marchon/verae-middleware) | Zapier HTTP + NATS workers |
| [verae-zapier-app](https://git.georgelambert.org/marchon/verae-zapier-app) | Zapier Platform app |
| [verae-activate](https://git.georgelambert.org/marchon/verae-activate) | Activate-now app |
| [verae-request-splitter](https://git.georgelambert.org/marchon/verae-request-splitter) | Hash vs attachments |
| [verae-archive-worm](https://git.georgelambert.org/marchon/verae-archive-worm) | Bloom WORM node |
| [verae-archive-aggregator](https://git.georgelambert.org/marchon/verae-archive-aggregator) | Archive reply merge |
| [verae-tree-node](https://git.georgelambert.org/marchon/verae-tree-node) | Merkle leaf proofs |
| [verae-fleet](https://git.georgelambert.org/marchon/verae-fleet) | Replica floor + SSH hosts |
| [verae-zapier-simulator](https://git.georgelambert.org/marchon/verae-zapier-simulator) | Trace console |
| [zapier-user-docs](https://git.georgelambert.org/marchon/zapier-user-docs) | Signup → lookup |
| [zapier-docs-master](https://git.georgelambert.org/marchon/zapier-docs-master) | Per-module SUMMARY + NATS |
Clone any of them: `git clone ssh://git@git.georgelambert.org:2223/marchon/<name>.git` (SSH port **2223**).
## Operator console (loopback)
Fleet, message **Trace**, and **Docs** share one shell at http://127.0.0.1:3850/ (`verae-fleet`). Not public. See [CONSOLE.pdf](https://zapier.georgelambert.org/packages/verae-fleet/docs/CONSOLE.pdf).
![Fleet tab](screenshots/console-fleet.png)
![Trace tab](screenshots/console-trace.png)
![Docs tab](screenshots/console-docs.png)
## Where to read next
Start at the top. Architecture is second. Everything else is reference.
### 1. High-level (non-technical)
| Document | What it is |
|----------|------------|
| **This overview** | Whole system in one place |
| [Modules and repositories](02-modules-and-repos.md) | Short names of every independent repo |
| [zapier-docs-master](https://git.georgelambert.org/marchon/zapier-docs-master) | One-line SUMMARY + NATS per module |
| [zapier-user-docs](https://git.georgelambert.org/marchon/zapier-user-docs) | Signup → register a hash → lookup |
### 2. Architecture
| Document | What it is |
|----------|------------|
| [NATS 3-server cluster](03-nats-cluster.md) | Who may connect; private URLs |
| [Uptime](04-uptime.md) | Replica floors, restart, SSH hosts |
| [Local network failures](05-network-failures.md) | Reconnect, bloom silence, failover |
| [Address routing](06-address-routing.md) | Unplanned functions as new subjects |
| [External resources](07-external-resources.md) | Chain, WORM, tree-node search |
| [Diagrams](08-diagrams.md) | SVG + mermaid |
| [Fleet](https://zapier.georgelambert.org/docs/02-architecture/fleet.pdf) | Operator replica control |
| [Module NATS map](https://zapier.georgelambert.org/docs/02-architecture/modules-and-nats.pdf) | Address table |
| [Archive / bloom](https://zapier.georgelambert.org/docs/02-architecture/archive-nats.pdf) | Multipart and multi-receipt |
| [Tree nodes](https://zapier.georgelambert.org/docs/02-architecture/tree-nodes.pdf) | Bulk Merkle leaves |
| [Composition](https://zapier.georgelambert.org/docs/02-architecture/composition.pdf) | zappier + middleware HTTPS |
### 3. Remaining documentation
| Document | What it is |
|----------|------------|
| [Documentation index](INDEX.md) | A–Z and catalog URLs |
| [Expansion template](09-expansion-template.md) / [verae-nats-process](https://git.georgelambert.org/marchon/verae-nats-process) | Copy this to add an address |
| [Operator console](https://zapier.georgelambert.org/packages/verae-fleet/docs/CONSOLE.pdf) | Screenshots of Fleet / Trace / Docs |
| [Simulator](https://git.georgelambert.org/marchon/verae-zapier-simulator) | Standalone trace (also inside the console) |
| [Zapier developer setup](https://zapier.georgelambert.org/docs/04-activate/SETUP-ZAPIER-DEVELOPER.pdf) | CLI / login / push |
| Live catalog | https://zapier.georgelambert.org/ (PDF) · [Markdown indexes](https://zapier.georgelambert.org/index-md.html) |
---
## Credits
Design: **Scott Lindsey**, **George Lambert**, **NATS.IO**, and **Grok-Code** by [Grok.com](https://grok.com).