adaptive-multi-protocol-gateway/docs/architecture.md

Architecture

Status: draft | Updated 2026-07-11 | Applies to: AMPG core

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.

System shape

source site
  -> source adapter
  -> content graph
  -> render profiles
  -> output roots
  -> daemon adapters
  -> clearnet / Tor / I2P / Gemini / IPFS / Reticulum

Source adapters

static-html

Reads an existing static site tree. AMPG preserves the clearnet version, parses HTML into a content graph, rewrites local links, and extracts text for Gemini and Micron renderers. This is the default path for the Wownero pilot.

markdown

Reads Markdown plus frontmatter. This is the cleanest authoring model for new sites.

ssg-output

Reads the built output of another static site generator. AMPG does not own that generator; it adapts the generated files.

Source quality

AMPG gets better results from semantic, accessible source documents. Authors should use one h1, ordered heading levels, meaningful link text, alt text for images, and ordinary flowing document structure before decorative layout. This keeps clearnet accessible and gives constrained renderers a clean outline for Gemtext, Micron, and other text-first targets.

ampg audit reports source-quality warnings. The audit is advisory by default and can be made strict in CI with --fail-on-warn.

Content graph

The internal graph is intentionally small:

• Site: domain, aliases, selected protocols, source metadata.
• Page: route, title, language, headings, body blocks, links, assets.
• Asset: path, media type, size, dimensions, privacy policy.
• Link: target, relation, transport compatibility.

Renderers should not scrape each other. They read the content graph and write their own output.

Render profiles

clearnet

High-fidelity output. Static HTML sources are copied by default. Markdown sources render to full HTML and may include CSS, JavaScript, web fonts, and rich media.

privacy-html

Tor and I2P default. Removes JavaScript, tracking pixels, external fonts, third-party embeds, remote assets, and stateful browser storage assumptions. CSS is local and small.

gemtext

Gemini output. Converts headings, paragraphs, lists, code blocks, and links to .gmi. Inline links become block links near the paragraph by default.

clearnet for IPFS

Static web output suitable for a local IPFS gateway or later pinning. IPFS is treated as content-addressed distribution, not an anonymity layer.

micron

Reticulum/Nomad output. Produces terminal-oriented Micron markup with small pages, plain links, and no heavy media by default.

Daemon adapters

Daemon adapters provide a common interface:

• detect: find existing services, ports, config files, and health endpoints.
• plan: decide whether to adopt, manage, or fail.
• render_config: produce config snippets and complete managed configs.
• apply: write approved managed config and start or reload services.
• health: verify the selected transport can serve the generated output.
• manifest: emit AMPB route/profile expectations for generated fixtures.

Adapters must be conservative. They do not modify non-AMPG config without showing a plan first, and managed config lives under AMPG-owned state directories.

Fixture manifests are the AMPG-to-AMPB boundary. They declare the published URL, expected transport, logical context, and transport-context isolation result. They do not prescribe browser tabs, processes, or local daemon ownership; those decisions remain inside AMPB.

Signed service manifests are the service-to-client identity boundary. An application-owned route manifest supplies publication policy, while a service manifest represents approved public policy plus deployed transport addresses. AMPG currently validates manifests and calculates their digests; applications or hardened external signers own private-key operations. A shared service identity binds endpoints but never merges browser origins or transport contexts. See Signed service manifests.

Platform providers

Platform providers decide what daemon management means on the current host. AMPG detects systemd Linux, user-space Linux, macOS user launchd, Termux-style Android, and unknown platforms. A provider can allow managed daemons without allowing system config writes.

Operators can override detection for dry runs:

python3 -m ampg --config gateway.toml doctor --platform linux-systemd
python3 -m ampg --config gateway.toml doctor --platform android-termux

This keeps the same gateway config portable across a VPS, laptop, old phone, or manual render-only environment while making daemon ownership decisions explicit.

Deploy plan

ampg deploy plan is the operator-friendly layer over build, doctor, install-plan, approvals, address capture, and apply dry-run. It emits stage rows with ready, todo, review, blocked, or skipped status and short next-step commands. It is read-only.

Clearnet reachability

ampg dns plan handles the public web edge for clearnet deployments. Static hosts use A/AAAA records. Dynamic or behind-router hosts can use Dynamic DNS, provider-specific apex aliases, API-updated records, port forwarding, IPv6, reverse tunnels, or DNS-01 certificate validation. Provider and router automation should remain opt-in.

Activation plan

ampg apply --dry-run turns daemon status and generated config artifacts into an ordered activation sequence. Each enabled protocol gets output, artifact, daemon, and health steps, plus an address step when AMPG must capture or confirm a generated transport identity. With --write-artifacts, it also prints copies from approved artifacts into managed state and planned supervisor start/reload actions. The command emits an AMPG_APPLY_PREFLIGHT verdict across activation, state-copy, and supervisor rows. Blocked or unapproved preflight items stop mutation before any live apply path can touch services.

ampg deploy apply --stage packages is the narrow live stage for package installation. It runs only structured package-manager commands for selected managed daemons. Adopted or external daemons do not require package apply.

ampg deploy apply --stage state is the narrow live stage for managed state. It reads the same approved artifact plan, refuses missing, stale, or unapproved inputs, and copies only approved generated daemon config into AMPG-owned state.

ampg deploy apply --stage supervisor installs approved AMPG-named supervisor files after the state files they reference exist. It does not start or reload services.

ampg deploy apply --stage start runs structured platform start commands for AMPG-named services after state and supervisor files exist. Address capture and health verification remain separate stages.

ampg deploy apply --stage addresses records daemon-written public addresses after the transport has produced them. It writes only the AMPG address registry; health verification remains a separate stage.

ampg deploy apply --stage health runs published fixture checks through the selected transport after addresses are configured or captured. It reports pass/fail and does not mutate deployment state.

The dry-run command is intentionally stricter than doctor: missing generated output is blocked during activation, because AMPG must not point a transport at an unbuilt output root.

Install plan

ampg install-plan translates managed daemon decisions into package, state, config, supervisor, and health-check steps. It does not install packages, create directories, or start services. The output is a reviewable bridge between daemon ownership decisions and the staged live apply commands.

With --write-artifacts, install-plan writes managed config and supervisor files under the configured plan_root; those files are review artifacts, not installed service state. ampg approvals approve records reviewed artifact digests under gateway.state_dir. Generated managed-daemon configs point runtime state at gateway.state_dir.

Tor and I2P HTTP publishing include the transport daemon and the loopback web-serving layer in the install plan, because the hidden service or tunnel must have a local HTTP target.

Health plan

ampg health-plan turns fixture manifests into post-start verification checks. Published mode targets real transport URLs. Preview mode rewrites checks to loopback HTTP preview endpoints so local generated output can be verified before live daemons exist.

Missing generated output blocks health checks. Placeholder transport addresses are reported for review, because the operator must capture the real onion, I2P destination, or other transport identity before published checks are exact.

Interaction boundary

v1 is static-first, but the architecture reserves a path for interactive applications. Interactivity is declared per route group:

• static: files only.
• interactive-lite: deterministic games, status lookups, quote forms, and other flows without account state or payment confirmation.
• identity: authenticated sessions, wallet sign-in, or signed capability links.
• transactional: server-confirmed orders, deposits, invoices, donations, or payment intents.
• realtime: rich browser/admin interfaces; HTTP transports only.
• internal: workers, webhooks, private admin APIs; never published automatically.

Dynamic support comes through application adapters that expose action metadata. HTTP transports can use normal forms or reverse proxies. Gemini uses status-code input prompts for simple actions. Reticulum uses page scripts or Micron action links. The core compiler must remain useful when no application adapter is configured.

Reusable checklist

• Add a source adapter only when it can produce the content graph.
• Add a renderer only when it reads the graph directly.
• Add a daemon adapter only with detect, plan, render_config, apply, and health.
• Keep privacy defaults stricter than clearnet defaults.