adaptive-multi-protocol-gateway/docs/interactive-apps.md

# Interactive Applications

> Status: draft | Updated 2026-07-05 | Applies to: dynamic app support

AMPG must support real applications without pretending every transport can offer the same
experience. The design goal is graceful capability mapping: expose the safest useful version
of each surface on each protocol, and keep private surfaces private.

## Interaction tiers

`static`
: Rendered files only. Works everywhere.

`forms`
: Server-rendered GET/POST actions with full-page responses. Works on clearnet, Tor, I2P,
  and can be mapped to Gemini input prompts or Reticulum page scripts for simple actions.

`sessions`
: Authenticated account flows. Supported on HTTP transports with strict cookies. Gemini can
  use client certificates or signed links later, but this is not a v1 requirement.

`realtime`
: Rich browser UI, dashboards, live charts, websockets, or client-side state. HTTP transports
  only, and usually clearnet or private Tor/I2P.

`internal`
: Worker APIs, webhooks, private admin APIs, payment callbacks, chain watchers, and service
  health endpoints. AMPG must not publish these automatically.

## Application adapter contract

An application adapter describes what AMPG may expose:

- upstream service and health check.
- OpenAPI spec or route manifest when available.
- route groups with interaction tier, auth requirement, and idempotency behavior.
- form/action schemas for protocol translation.
- public asset and cache policy.
- private route denylist.

Adapters do not bypass the application. They translate constrained protocol input into the
application's public action surface, then render safe responses.

## Protocol mapping

| Tier | Clearnet | Tor/I2P | Gemini | Reticulum |
| --- | --- | --- | --- | --- |
| `static` | yes | yes | yes | yes |
| `forms` | yes | yes, no JS by default | simple single-field prompts | simple scripts/actions |
| `sessions` | yes | yes, strict cookies | later | later |
| `realtime` | yes | optional private surface | no | no |
| `internal` | no public publish | no public publish | no | no |

## Challenge profile: Medusa multi-tenant platform

Source: `../medusa-multi-tenant-platform`.

Why it matters:

- multi-tenant domain routing.
- storefront, tenant admin, backend, worker, database, Redis, S3/MinIO.
- cart, checkout, orders, bookings, blogs, email, payment providers, and webhooks.
- tenant-specific themes and custom domains.

AMPG support target:

- Clearnet: adopt existing Caddy/reverse-proxy deployment.
- Tor/I2P: expose storefront routes with `forms` or `sessions` tier, no JavaScript by default.
- Gemini/Reticulum: expose catalog, blog, policy, product detail, and inquiry/request flows.
- Admin: `internal` unless explicitly bound to a private operator transport.
- Webhooks, payment callbacks, worker queues, health internals: always `internal`.

Required adapter capabilities:

- read tenant/domain registry or accept an exported tenant manifest.
- generate per-tenant protocol targets and daemon plans.
- cap checkout/payment routes by protocol.
- use OpenAPI route metadata where available.
- never expose tenant admin or backend admin by wildcard.

## Challenge profile: evaluetron / ai-gen-bot

Source: `../ai-gen-bot`.

Why it matters:

- OpenAPI-first core.
- customer storefront plus operator console.
- auth, payments, credit ledger, job queue, workers, moderation, and generated artifacts.
- public web channel, Telegram channel, internal worker APIs, and admin APIs.

AMPG support target:

- Clearnet: public storefront and docs.
- Tor/I2P: public storefront with server-rendered account/job flows when enabled.
- Gemini/Reticulum: catalog browsing, deposit instructions, simple generation request, and job
  status lookup only after explicit adapter support.
- Operator console: private clearnet, LAN, mesh, or private onion only.
- Worker/internal routes: never published.

Required adapter capabilities:

- consume `api/openapi.yaml` as the action contract.
- map job creation to idempotent form submissions.
- render job status as polling-friendly pages.
- hide unavailable generators when no worker advertises the required capability.
- preserve the ledger and payment invariants of the upstream app.

## Design constraints learned from the challenge apps

- Public route discovery must start deny-first.
- OpenAPI is useful, but not sufficient; route tiers and privacy intent must be explicit.
- Admin and worker surfaces are separate sites or route groups, not accidental subpaths.
- Gemini and Reticulum need curated actions, not automatic exposure of every POST route.
- Multi-tenant apps need generated protocol targets per tenant, with shared daemon adapters.

## Reusable checklist

- [ ] Classify every route group by interaction tier.
- [ ] Deny private/admin/internal routes before enabling protocols.
- [ ] Prefer OpenAPI or route manifests over HTML scraping for actions.
- [ ] Provide safe alternates for constrained transports.
- [ ] Verify no worker, webhook, payment callback, or admin route is publicly published.