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 ── MainframeResponsibilities
Section titled “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 alerts 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. Radar-net consumes an external feed. A module may also use the client protocol, as world-sim’s operator does when reading missions and issuing dispatches.
Mainline Packages divide the product into Base, which every installation has, and the optional Drones, Air Picture, Comms, TAK and Simulation packages. An installation config says which packages are installed and which of their modules are enabled. Mainframe refuses the routes, documents and commands of an absent package, and Terminal shows none of its panels, menu items or settings. Code follows the same split: package code lives in its own directory in each app and never imports another package.
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
Section titled “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.