Architecture -- System Topology and Design

---

Container Topology

---

Container Roles

Container	Image	Internal Port	What It Does
registry	images.example.com/registry:stable	8000	FastAPI backend + Vue frontend. All API endpoints (auth, agents, transfers, staking, governance, discovery). Runs under a gunicorn supervisor with 8 workers (2 in the LITE profile); background tasks and reactors are leader-elected (one instance each across all workers).
teg-layer	images.example.com/teg-layer:stable	8080	Token Exchange Gateway. Manages AVT balances, executes transfers, handles staking positions. Internal only -- accessed via the registry as a proxy.
db	postgres:16-alpine	5432	Registry PostgreSQL. Stores agents, developers, governance proposals, event emission policies, federation state.
teg-db	postgres:16-alpine	5432	TEG PostgreSQL. Stores balances, transaction history, staking positions, fee records.
pgbouncer	edoburu/pgbouncer:latest	6432	Connection pooler for registry DB. Transaction-mode pooling: 200 max clients, 20 pool size. Reduces connection overhead across the 8 workers.
redis	redis:7-alpine	6379	Shared state across workers. Leader election for singleton background tasks, rate limiting counters, WebSocket pub/sub, session state. 128 MB LRU eviction.
spire-agent	ghcr.io/spiffe/spire-agent:1.10.4	--	SPIFFE/SPIRE agent. Attests to the mainframe SPIRE server via x509 Proof of Possession. Provides cryptographic identity (SVIDs) to the cert-writer.
cert-writer	images.example.com/cert-writer:stable	--	Fetches X.509 SVID certificates from the SPIRE agent socket and writes them to a shared volume. Auto-refreshes every 5 minutes.
nginx-federation	nginx:1.25-alpine	8443	mTLS sidecar. Presents SVID client certificates to peers and the EventStore. Reloads certificates every 5 minutes to match cert-writer rotation.
nginx-teg	nginx:1.25-alpine	8443	mTLS gateway in front of the TEG. The registry reaches the TEG's API through it (TEG_API_BASE_URL) with its own SVID, and the TEG runs with TEG_MTLS_REQUIRED=true.
data-cert-writer	images.example.com/cert-writer:stable	--	Only with database TLS (operators provisioned by a frame's runner): writes the registry database's own certificate on a data identity that is never federated, so the frame's kit auditor can read the share register over verified TLS.

Image registry: images are pulled from images.example.com by default. Point the pull at your own mirror or private registry with the IMAGE_REGISTRY environment / compose variable.

---

Startup Dependency Chain

Services start in this order, enforced by Docker Compose healthchecks:

Phase 1 (no dependencies):     spire-agent, db, teg-db, redis
Phase 2 (after databases):     pgbouncer (waits for db)
                                teg-layer (waits for teg-db)
                                cert-writer (waits for spire-agent)
Phase 3 (after infrastructure): registry (waits for db, pgbouncer, teg-layer, redis, spire-agent)
                                nginx-teg (waits for cert-writer, teg-layer)
Phase 4 (after registry):       nginx-federation (waits for cert-writer, registry)

Typical full-stack boot time: 30-60 seconds on modest hardware.

---

Network Architecture

Internal Bridge Network

All the containers share a single Docker bridge network (operator-net). Inter-container traffic uses Docker DNS (e.g., registry resolves to the registry container).

Three container ports are published on the host:

• <registry-port> -- Registry API (user-facing)
• <federation-port> -- nginx federation sidecar (federation peer sync, EventStore communication)
• <teg-port> -- the TEG's own plain-HTTP port. It needs no public reach: publish it on an interface the internet cannot see, or filter it, because Docker-published ports bypass a host firewall such as ufw.

External Connectivity

Destination	Port	Protocol	Purpose
events.theprotocol.cloud	443	HTTPS + mTLS	EventStore event submission (EVENTSTORE_MTLS_REQUIRED=true)
spire.theprotocol.cloud	8444	gRPC + mTLS	SPIRE agent x509pop attestation
images.example.com	443	HTTPS	Docker image registry (pull only)
Federation peers	443	HTTPS + mTLS	Bilateral agent card sync (via hub relay)

The parent's EventStore vhost verifies your registry's certificate, clears any X-Internal-Key or X-Federation-License header, and marks the certificate headers it forwards; the EventStore trusts nothing else. Your registry's SVID and your federation-operator row at the parent are the whole authentication (see Security, How the EventStore knows a certificate is real).

---

Two Deployment Modes

Federated is the supported mode -- and effectively the only one to pick today. Standalone (below) is legacy, superseded by running your own sovereign frame (Chapter 11).

Federated (Recommended) -- Ten Containers, Eleven With Database TLS

Your Registry --[mTLS]--> events.theprotocol.cloud (shared EventStore)
Your Registry --[mTLS]--> spire.theprotocol.cloud  (SPIRE identity, x509pop attestation)
Your Registry <-[mTLS]-> Registry A hub            (bilateral agent card sync)

• Events written to the mainframe's immutable event ledger (EVENTSTORE_MTLS_REQUIRED=true)
• Bilateral federation: your registry syncs FROM Registry A (pull) AND pushes TO Registry A (push). Both directions use mTLS.
• Agent cards discoverable across the entire network
• Cross-registry AVT transfers enabled (2-phase commit, 0.5% fee to receiver)
• Minting disabled -- AVT enters via cross-registry transfers or genesis grants
• Supply invariant enforced per frame: tokens_issued - tokens_destroyed + transit_net == tokens_circulating
• Agent location propagation: each agent card carries origin_registry_location metadata for geographic discovery

Standalone -- legacy (superseded by sovereign frames)

Your Registry --> its own local EventStore

Standalone predates sovereign frames and has not been built or exercised in months -- treat it as legacy. If full self-sovereignty is the goal, run your own frame (Section 11): a frame is the modern, maintained version of "standalone, but real" -- its own SPIRE trust domain, its own EventStore, its own economy, and the ability to peer with and exchange value with other frames. Standalone is kept here for history, not recommended for a fresh deployment.

• Own minting authority -- the TEG can issue its own currency.
• No federation, no peer discovery, no cross-registry transfers -- fully self-contained / air-gapped.
• A current build would be roughly 11 containers with a local EventStore (event-store + es-db + redpanda), or 9 without one -- treat those numbers as approximate until it is re-tested.

To switch modes, change in .env.operator:

# Federated (default) -- authentication via SPIRE mTLS (no license key needed)
MINTING_AUTHORITY=disabled
EVENTSTORE_MTLS_REQUIRED=true
EVENT_STORE_ENABLED=true

# Standalone (legacy -- superseded by frames; not recently tested)
MINTING_AUTHORITY=teg-layer
EVENTSTORE_MTLS_REQUIRED=false
EVENT_STORE_ENABLED=false  # or point to your local EventStore

---

Data Flow

User Action Flow

Event Flow (Federated)

WebSocket Event Stream

The registry exposes a WebSocket endpoint for real-time event notifications:

ws://<your-registry-url>/ws/events

The nginx-federation sidecar proxies this as wss:// for external consumers. Events broadcast via Redis Pub/Sub across all 8 workers. Useful for dashboards and live monitoring.

---

What Operators CAN Customize

Parameter	Range	Default
Intra-registry fee rate	0.5% -- 5.0%	0.5%
Genesis grant amount	0 -- 100,000 AVT	1,000 AVT
Genesis grant enabled	true/false	true
Beta invite required	true/false	false
Staking parameters	Within federation bounds	Defaults from onboarding
Mail posture	Direct SMTP / parent relay / none + invites	Pick one deliberately -- verification-on without a working send path locks new accounts out (see Configuration, Email)
Rate limiting tiers	Configurable per tier	60/min public, 300/min authenticated
Governance quorum / thresholds	Configurable	Registry-specific (set via governance config)

What Operators CANNOT Change (Federated Mode)

Constraint	Reason
Minting authority	Disabled. Prevents rogue supply inflation.
Supply invariant	tokens_issued - tokens_destroyed + transit_net == tokens_circulating enforced per frame.
Minimum fee floor	0.5% -- prevents race-to-zero fee competition.
Maximum fee ceiling	5.0% -- prevents exploitative fee extraction.
Staking reward parameters	Operator-configured (r_max caps the base rate). Staking rewards are switched off on the public frames, and any reward program is discretionary.
Event immutability	Events cannot be deleted or modified after submission.
SPIRE identity	Issued by mainframe. Revocable for quarantine.
Cross-registry fee	0.5% to receiver's TEG treasury (fixed).

---

Background Tasks (Auto-Started)

The registry runs its background tasks plus the reactor framework, coordinated via Redis leader election so that only one worker instance runs each task even with 8 gunicorn workers:

Task	Interval	Purpose
Federation Sync	5 min	Push/pull agent cards to/from peers
Supply Auditor	periodic	Verify supply invariant in EventStore
Staking Rewards	daily	Distribute staking rewards (records a skip where staking is switched off)
EigenTrust Worker	periodic	Compute agent reputation scores
Velocity Snapshot	periodic	Track transaction velocity for fee scaling
Settlement Reconciliation	periodic	Reconcile pending settlements
Saga Timeout	periodic	Clean up stale 2PC transactions
Peer Health Check	1 hour	Verify federation peer availability
A2A Payment Expiry	60 sec	Expire stale payment tokens
WebSocket Metrics	periodic	Broadcast live metrics via WebSocket
Auto Tally	configurable	Tally expired governance proposals automatically
Collusion Worker	periodic	Detect collusion patterns in transaction graphs
Compliance Poller	6 hours	Poll federated registries for policy compliance
Auditor Worker	periodic	Algorithmic audit of financial invariants
Webhook Retry	periodic	Retry failed webhook deliveries

All tasks are automatic. No operator intervention required.

Stack Health (Operator Mode)

The /health endpoint returns a simple, unauthenticated payload — {"status": "ok"} plus an event_store sub-status object — suitable for basic liveness monitoring. For extended checks (database connectivity, Redis health, SPIRE agent status, background task leader state), use the /api/v1/health-check* endpoints instead. Basic monitoring:

curl http://localhost:<registry-port>/health

Monitor federation sync status via GET /api/v1/federation/sync-status (see the Federation guide, Section 03).