How the system fits together

Mainframe is the source of shared operational state. Terminal is a client of that state. A module connects a specific device, feed, or service through the provider protocol.

Terminal ── HTTPS / WebSocket ── Mainframe ── Postgres
   │                                │
   │ WebRTC                  provider protocol
   ▼                                │
  MediaMTX ◀──── RTMP ─────────────── modules
   │
   └── closed DVR file ── media indexer ── private S3
                               │
                               └── manifest ── Mainframe

Responsibilities

Mainframe Core owns users, grants, the entity registry, live subscriptions, persistent history, documents, replay cursors, commands, leases, and media authorization. Its tasking runner follows missions by issuing ordinary flight commands. Its rules, alerts, proposals, and coverage services operate on the same state that Terminal sees.

Terminal presents that information in a dockable workspace. Multiple Terminals can connect to the same Mainframe. A browser’s selected entity, panel layout, and replay cursor are local to that workspace; mission edits and alert decisions are shared.

Modules own integration details. World-sim handles simulated physics and camera rendering. Autel hosts real controllers with the vendor’s protocol; vanagas reads the same protocol from another system’s deployment. Weather and radar-net consume external feeds. A module may also use the client protocol, as auto-operator does when reading missions and issuing dispatches.

Postgres stores Core’s entities, time-series samples, snapshots, events, command audits, documents, and media/blob indexes. Modules do not write Core tables directly.

MediaMTX and the indexer handle video. MediaMTX accepts authenticated RTMP publishing and native pulls, serves WebRTC and HLS, and records fragmented MP4 directly. The indexer copies closed files into fast-start MP4 without re-encoding, validates and uploads them, then registers their manifests with Mainframe. An on-demand audio rendition copies video and converts AAC to Opus once per watched source; the archive retains the original audio.

Design principles

• Describe behavior through capabilities. Panels and Core should not need a vendor-specific transport.
• Validate at the boundary. Shared Zod schemas define wire frames, capabilities, and documents.
• Keep identity stable. An entity is identified by its provider and external ID, even when its callsign changes.
• Make authority explicit. Reading, dispatching, continuous control, and observation are different permissions and policies.
• Keep commands observable. Acceptance is followed by execution outcomes, events, and audit records.
• Keep deployment state durable. Normal rebuilds preserve database, world state, media, and monitoring volumes.

Mainframe currently runs as one replica. Its in-memory registry, tasking runners, leases, and replay cursors rely on that contract. Scale the server or move heavy modules to another host before trying to run multiple Core replicas against one database.