Platform Architecture Overview

SkyHub is a drone-fleet operations platform. A browser Dashboard operates drones; a Flask Gateway Service brokers every command and telemetry stream; and each drone runs the SkyCore Drone OS (ROS 2 + MAVLink on a Jetson) — or is a SITL simulation the Gateway spawns on demand. Around that control loop sit a video plane (Janus + WHIP), a network plane (WireGuard User VPN behind a single jumphost), a separate low-latency manual-control path (WS Proxy + Redis), and shared infrastructure (PostgreSQL, Redis, S3). The whole stack spans six repositories — see the Repository Map for who owns what. This page is the map. It shows how the pieces connect and points you at the four deep-dive pages in this group when you need the detail.

​

The big picture

The four planes are worth naming, because each has its own transport, latency budget, and failure mode:

​

The Gateway is the control-plane hub

Every operator action funnels through the Gateway Service. It:

• Authenticates users over HTTP with JWT (10-min access, 12-hr refresh tokens).
• Owns the database — User, Drone, Mission, Asset, UserDroneAccess all live in one PostgreSQL instance the Gateway reads and writes.
• Dispatches drone commands by translating REST calls (POST /api/v1/drone/action/{arm|takeoff|set_mode|push_mission|...}) into rosbridge call_service/publish frames on a pooled, auto-reconnecting WebSocket (src/rosbridge/connection.py, src/service/drone_control_service.py).
• Streams telemetry back to the browser over Socket.IO — the drone’s MAVROS topics arrive on the rosbridge connection and are re-emitted as telemetry_data events.
• Spawns and tears down SITL Docker containers on a remote Docker host (src/service/sitl_drone_service.py), gated by ENABLE_SITL.
• Creates Janus video rooms and pushes the room credentials to the drone so it knows where to publish.

For the exact request and telemetry sequences, see Cross-System Data Flows.

​

SITL and physical drones are interchangeable

A design keystone: the Gateway speaks the same rosbridge/topic contract to a real drone and to a SITL container. A SITL container runs sim_vehicle.py + MAVROS + rosbridge_server + a GStreamer→WHIP video node — the identical interface a SkyCore drone exposes. The only differences the Gateway cares about are where to connect and lifecycle: Because of this, code paths for commands, telemetry, missions, and video work unchanged whether you flew a physical aircraft or clicked “add SITL”. See SITL Drone Lifecycle and the SITL Simulator for the container internals.

​

Three real-time transport channels

Do not conflate these — they are independent connections with different protocols and different clients. Tuning or debugging one has no effect on the others. Real-time Transport Channels covers the heartbeats, throttling (TELEMETRY_THROTTLE_RATE, default 200 ms), reconnect/backoff, and the room-naming details for each.

​

Three auth models coexist

Different actors authenticate different ways. A change to one must not accidentally widen another. The VPN-IP model is why the whole platform must stay behind the VPN and jumphost: those drone-callback endpoints (/drone/pull, /executions/*, /authenticate_upload) carry no JWT. See Authentication & Security Model and the VPN Middleware & Jumphost page.

​

The jumphost: keystone and single point of failure

The jumphost’s nginx reverse proxy fronts these ports (all on the WireGuard EC2 host): The :9090 header-driven proxy is what lets the Gateway reach any drone with a single connection string — it sets x-drone-ip/x-drone-port (src/rosbridge/connection.py:162) and nginx forwards accordingly. See Network & VPN Topology and VPC, WireGuard Jumphost & nginx Routing for the full port map and the WireGuard address plan.

​

Shared infrastructure

Three data stores are touched by multiple services, so schema or availability changes ripple widely:

• PostgreSQL — the single skyhub database (user, drone, user_drone_access, missions, assets, executions). Read/written by the Gateway, the WS Proxy, and the User VPN service. In production it runs as an ECS Fargate container on EFS — not RDS.
• Redis — the pub/sub bus for the gamepad/manual-control path ({drone_ip}:gamepad_input, {ip}:output, {ip}:aruco_tracking) and an optional Socket.IO message queue for multi-worker scaling. A container, not ElastiCache.
• S3 — skyhub-prod-assets (video/image/log assets), skyhub-prod-user-vpn (per-user WireGuard configs), and the UI bucket.

Production runs in AWS eu-central-1 on ECS Fargate behind Cloud Map service discovery (skyhub-prod.internal). See the AWS Infrastructure Overview for the full deployment.

​

Where to go next

To dive into a specific system instead: Gateway Service, SkyCore Drone OS, Dashboard, or the Ecosystem services (Janus, WHIP, SITL, User VPN, WS Proxy). New to the domain? Start with Core Concepts & Glossary.