mirror of
https://github.com/Such-Software/adaptive-multi-protocol-gateway.git
synced 2026-10-17 07:31:32 +02:00
100 lines
3.7 KiB
Markdown
100 lines
3.7 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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.
|