Architecture

Status: draft | Updated 2026-07-05 | 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.

System shape

source site
  -> source adapter
  -> content graph
  -> render profiles
  -> output roots
  -> daemon adapters
  -> clearnet / Tor / I2P / Gemini / 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.

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.
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.

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.

Interaction boundary

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

static: files only.
forms: server-rendered actions and full-page responses.
sessions: authenticated flows with strict session policy.
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.

3.7 KiB Raw Blame History