From 7199431a99166961f8fdfa23c5066736d87a301d Mon Sep 17 00:00:00 2001 From: jwinterm Date: Tue, 7 Jul 2026 09:55:47 -0400 Subject: [PATCH] Add public visual guide --- README.md | 1 + docs/architecture.md | 3 + docs/visual-guide.md | 203 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 207 insertions(+) create mode 100644 docs/visual-guide.md diff --git a/README.md b/README.md index e92b86c..4bb8eb2 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,7 @@ API remains internal even when the public site is available on Tor or I2P. - [Domain onboarding](docs/domain-onboarding.md) - [Fixture manifests](docs/fixture-manifests.md) - [State contract](docs/state-contract.md) +- [Visual guide](docs/visual-guide.md) - [Interaction capabilities](docs/interaction-capabilities.md) - [Interactive applications](docs/interactive-apps.md) - [Wownero integration](docs/wownero-integration.md) diff --git a/docs/architecture.md b/docs/architecture.md index 699f524..010d818 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -6,6 +6,9 @@ AMPG is a compiler plus an ingress manager. The compiler turns one site into a protocol-neutral content graph, then renders protocol-specific outputs. The ingress manager connects those outputs to daemons selected by the operator. +For diagrams of the build flow, deploy spine, and common network topologies, see the +[Visual guide](visual-guide.md). + ## System shape ```text diff --git a/docs/visual-guide.md b/docs/visual-guide.md new file mode 100644 index 0000000..c59c93f --- /dev/null +++ b/docs/visual-guide.md @@ -0,0 +1,203 @@ +# Visual Guide + +> Status: draft | Updated 2026-07-07 | Applies to: AMPG operators and contributors + +This guide shows the core AMPG flows and common deployment topologies. Diagrams use +Mermaid so they render in GitHub Markdown and can later be reused by a public docs site. + +## Build Flow + +AMPG starts from one canonical site and renders transport-appropriate outputs. Rich web +output can stay rich on clearnet, while constrained or privacy-oriented transports get +safer defaults. + +```mermaid +flowchart LR + source["Source site
static HTML, Markdown, or generated output"] + graph["AMPG content graph"] + clearnet["clearnet
HTML/CSS/assets"] + tor["Tor
privacy HTML"] + i2p["I2P
privacy HTML"] + gemini["Gemini
Gemtext"] + ipfs["IPFS
static tree"] + reticulum["Reticulum
Micron"] + manifest["fixture manifest
routes and expected transports"] + + source --> graph + graph --> clearnet + graph --> tor + graph --> i2p + graph --> gemini + graph --> ipfs + graph --> reticulum + clearnet --> manifest + tor --> manifest + i2p --> manifest + gemini --> manifest + ipfs --> manifest + reticulum --> manifest +``` + +## Deployment Spine + +Live deploy work is split into narrow stages. Each stage has a dry-run form first, and +live stages require explicit confirmation. + +```mermaid +flowchart TD + init["init site"] + build["build outputs"] + plan["install-plan
review package, state, supervisor steps"] + packages["deploy apply --stage packages
install selected daemon packages"] + approve["approvals approve
record reviewed artifact digests"] + state["deploy apply --stage state
copy approved config into AMPG state"] + supervisor["deploy apply --stage supervisor
install AMPG-named service files"] + start["deploy apply --stage start
start AMPG-owned services"] + addresses["deploy apply --stage addresses
capture daemon-written public addresses"] + health["deploy apply --stage health
verify published fixtures"] + + init --> build --> plan --> packages --> approve --> state --> supervisor --> start --> addresses --> health +``` + +## Ownership Boundaries + +AMPG tries to keep operator-owned services, AMPG-owned generated state, and +daemon-written identity material distinct. + +```mermaid +flowchart LR + operator["Operator-owned
DNS, router, existing reverse proxy, adopted daemons"] + ampg["AMPG-owned
generated outputs, reviewed artifacts, state registry"] + daemon["Daemon-written
onion hostname, I2P destination, keys, logs"] + public["Public routes
clearnet, Tor, I2P, Gemini, IPFS, Reticulum"] + + operator -- may be adopted by policy --> ampg + ampg -- starts or configures managed service --> daemon + daemon -- writes transport identity --> ampg + ampg -- publishes selected outputs --> public +``` + +## VPS Multi-Transport + +A normal VPS is the cleanest full-stack topology. AMPG can adopt existing daemons or +manage missing ones, while clearnet DNS and TLS remain operator-controlled by default. + +```mermaid +flowchart TB + dns["DNS provider
A/AAAA/CNAME records"] + internet["public internet"] + vps["VPS host"] + ampg["AMPG"] + outputs["/var/www/ampg/site outputs"] + nginx["nginx or Caddy
clearnet ingress"] + tor["Tor daemon
onion service"] + i2p["i2pd
server tunnel"] + gemini["Gemini daemon"] + users["Visitors and AMPB checks"] + + dns --> internet --> vps + vps --> ampg --> outputs + outputs --> nginx + outputs --> tor + outputs --> i2p + outputs --> gemini + nginx --> users + tor --> users + i2p --> users + gemini --> users +``` + +## Home Server Behind A Router + +Behind-router clearnet publishing may need port forwarding, IPv6, Dynamic DNS, a reverse +tunnel, or DNS-01 certificate validation. Tor and I2P can often avoid inbound clearnet +port forwarding. + +```mermaid +flowchart LR + visitor["Visitor"] + dns["DNS or Dynamic DNS"] + router["Home router
NAT and firewall"] + host["Laptop or mini server"] + ampg["AMPG"] + clearnet["clearnet web server"] + tor["Tor onion service"] + i2p["I2P server tunnel"] + + visitor --> dns --> router --> clearnet + router --> host + host --> ampg + ampg --> clearnet + ampg --> tor + ampg --> i2p + visitor -. no router port forward required for many cases .-> tor + visitor -. no router port forward required for many cases .-> i2p +``` + +## Android Or Termux Server + +An old phone can be useful for mobile-server experiments. AMPG plans user-space daemons, +Termux package installs, and service scripts, while battery policy, storage, and public +reachability remain device-owned. + +```mermaid +flowchart TB + phone["Android phone
Termux"] + ampg["AMPG CLI"] + pkg["pkg install
tor, i2pd, nginx"] + state["Termux state
AMPG config, keys, logs"] + services["termux-services
AMPG-named daemons"] + transports["Tor/I2P/Gemini routes"] + checks["health checks
fixture URLs"] + + phone --> ampg + ampg --> pkg + ampg --> state + state --> services + services --> transports + transports --> checks +``` + +## Single-Transport Deployments + +AMPG should also work when the operator wants only one selected transport. This is useful +for I2P-only, Tor-only, Gemini-only, or Reticulum-focused deployments. + +```mermaid +flowchart LR + source["existing site"] + ampg["AMPG"] + selected["selected transport only"] + daemon["adopted or managed daemon"] + public["published route"] + + source --> ampg --> selected --> daemon --> public +``` + +## Browser Test Loop + +AMPG writes fixture manifests so a companion browser or checker can verify that each +route uses the expected transport profile. + +```mermaid +sequenceDiagram + participant Site as Source site + participant AMPG as AMPG + participant Manifest as Fixture manifest + participant AMPB as AMPB/browser checker + participant Transport as Selected transport + + Site->>AMPG: build selected outputs + AMPG->>Manifest: write route expectations + AMPB->>Manifest: load fixtures + AMPB->>Transport: request fixture URL through expected profile + Transport-->>AMPB: return generated output + AMPB-->>AMPG: report pass or failure +``` + +## Public Docs Site Path + +The first public docs site should be generated from the public Markdown docs in this +repository. A GitHub Pages build can later reuse these Mermaid diagrams with MkDocs, +mdBook, or another static docs generator. Private strategy notes, deployment inventory, +and host-specific material should stay under private docs and outside any Pages build.