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.

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

4.2 KiB Raw Blame History