Skip to main content

Architecture

The Suite is a Next.js App Router application running as a standalone Node server on Oracle Cloud VMs. Both production and shared test use SQLite; Cloudflare still supplies DNS, tunnels, Access and R2.

Components​

ComponentWhat it isWhere it runs
Suite web appNext.js 16, React 19, TypeScript, TailwindOracle VM, standalone Node server
SQLiteRelational database holding accounts, customers, drones, documents, flight logs, licences, connectionsOracle VM, file at SUITE_DATABASE_PATH
R2Object storage for drone media, public media and avatarsCloudflare R2, accessed from Node through S3
Suite OIDC providerLogin for the Suite, Harlock and ArcadiaOracle Node service plus SQLite
Jetson gatewayTelemetry, command and media control for one vehicleOn the aircraft
MediaMTXRTSP ingest and WebRTC/HLS playbackOn the aircraft, alongside the gateway

What runs where​

The Node service authenticates users and manages configuration. Live vehicle services remain on the aircraft:

  • Telemetry — the browser opens a WebSocket straight to the vehicle's gateway. The Suite never holds that socket.
  • Video — the browser plays WHEP or HLS through authenticated Suite proxy routes. Those routes forward to MediaMTX without exposing vehicle credentials or private playback origins to the client.
  • Commands, mission, parameters — the Suite makes an ordinary HTTPS request to the gateway's own API.
  • Gimbal and zoom — the browser sends commands directly to the gateway with a short-lived Suite-issued token, reusing it until renewal. Suite routes provide the fallback when the browser cannot reach the gateway.

For the remote link, the Suite authenticates callers, enforces visibility, issues tokens and proxies the operations described above. WebRTC media follows the ICE route selected by the peers; WHEP signalling and HLS resources cross the authenticated Suite routes. See The remote link.

Reaching a vehicle​

Two transports exist, for two different consumers.

  • Cloudflare Named Tunnel — a stable per-vehicle hostname that terminates HTTPS and WebSocket traffic. This is the path a browser can use, so it is the Suite's path.
  • The same tunnel, for ground stations — Harlock and Arcadia read the vehicle's MAVLink through the same gateway, with a gateway token the Suite signs for them.

Who may reach a vehicle is decided by the Suite when it signs a gateway token, not by a check inside an interface. That reasoning is written out in docs/remote-link-security-boundary.md in the repository.

Code layout​

  • app/[lang]/… — localized pages
  • app/api/… — route handlers
  • lib/ — shared logic; lib/server/ is server-only
  • lib/db/ — the database client and typed helpers
  • lib/platform/ — SQLite and R2 access for Node, behind the retained D1/R2 interfaces
  • lib/auth/ — OIDC client selection and encrypted browser sessions
  • lib/oidc/ — the Suite OIDC provider
  • models/ — shared shapes and the pure functions that carry business rules
  • data/ — data-access actions and browser request helpers
  • migrations/ — SQLite migrations, applied by hand

Shared vehicle rules, instruments, telemetry, missions and gateway contracts are supplied by the versioned @sab-group-srl/* packages from sabrobotix-kit. The package tags in package.json and the runtime revision in contract/jetson-runtime.json define compatibility; they do not establish which runtime is installed on a particular vehicle.