Gateway Service Overview

The SkyHub Gateway Service is the control-plane hub of the platform. It is a Python/Flask + Flask-SocketIO backend that authenticates users over HTTP (JWT), streams real-time telemetry to the Dashboard over Socket.IO, and dispatches flight commands over rosbridge WebSocket (port 9090) to either physical drones (reachable via a per-user WireGuard VPN) or SITL Docker containers it spawns on a remote Docker host. It is also the platform’s integration point for Stripe billing, AWS (S3/ECR/STS/EC2), and the Janus video SFU. Everything a client can do lives behind one contract: ~113 HTTP endpoints, all under the /api/v1 prefix, plus a single Socket.IO namespace for telemetry. This page is the map of that surface — what the gateway does, how it is structured, and where new logic belongs. Deep-dives on each area live in the sibling pages linked throughout.

What the gateway is responsible for

Auth & accounts

Drone control

Drone CRUD plus ~20 /drone/action/* MAVROS commands (arm, takeoff, modes, params, missions, geofences).

Real-time telemetry

Socket.IO rooms fed by pooled rosbridge connections, with server-side dashboard yaw computation.

SITL orchestration

Spawns and tears down the 3-container SITL stack over local or remote Docker.

Media & flight data

Janus video rooms, S3 assets/HLS, execution tracking, log analysis, archives, and email reports.

Integrations

Stripe webhooks, AWS ECR/STS bootstrap for drone self-update, and Isaac Sim EC2 control.

Tech stack

Concern	Technology	Notes
Language	Python 3.10.12
Web framework	Flask 3.0.2	Blueprint-based routing
Real-time	Flask-SocketIO 5.3.6	`async_mode="gevent"`; JWT handshake via `?token=`
WSGI server	gunicorn 22.0.0 + `gevent-websocket`	`GeventWebSocketWorker`, 1 worker / 8 threads, binds `main:app`
Auth	Flask-JWT-Extended 4.5.3, Flask-Bcrypt	HS256 access (10 min) + refresh (12 hr) tokens
API docs	flasgger 0.9.7.1	Swagger 2.0 UI at `/api/docs/`, spec at `/apispec.json`
Persistence	Flask-SQLAlchemy + Flask-Migrate (Alembic)	PostgreSQL
Cloud	boto3 1.35.10	S3, ECR, STS, SSM, EC2
Billing	stripe SDK	Checkout, portal, signature-verified webhooks
Observability	OpenTelemetry (OTLP)	Traces/logs to SigNoz — see OpenTelemetry & SigNoz

The container entrypoint is defined in the Dockerfile:

Dockerfile

CMD ["gunicorn", "--workers", "1", "--threads", "8", \
     "-k", "geventwebsocket.gunicorn.workers.GeventWebSocketWorker", \
     "-b", "0.0.0.0:5000", "main:app"]

The default deployment runs a single gunicorn worker. Two pieces of state are process-local as a result: the JWT logout BLOCKLIST (an in-memory set() in src/routes/auth_routes.py) and, if you scale to multiple workers, Socket.IO room fan-out — which is why SOCKETIO_MESSAGE_QUEUE (an optional Redis URL) exists. See Authentication & JWT Lifecycle.

The API surface

The gateway exposes a Swagger 2.0 spec generated by flasgger. Browse it live at GET /api/docs/ (raw spec at GET /apispec.json); both are public. Gateway Swagger UI (SkyHub Gateway Service API v1.0.0, 113 endpoints)

Gateway Swagger UI (SkyHub Gateway Service API v1.0.0, 113 endpoints)

Every route is registered under url_prefix="/api/v1/" in src/main.py:222-233, and each rule itself begins with /, so the effective base path is /api/v1. The Socket.IO handlers are wired separately (src/main.py:240) and are not a blueprint.

12 blueprints

Blueprints are registered in src/main.py; each imports its collaborating service singleton from src/application/app.py and stays thin. Endpoint counts below are the @*_routes.route(...) decorators in each file (113 total).

Blueprint	File	Endpoints	Primary auth model
`auth_routes`	`src/routes/auth_routes.py`	9	Public (login/register) + JWT + activation token-in-path
`drone_routes`	`src/routes/drone_routes.py`	30	JWT; `/drone/activate` (10-digit header token), `/drone/pull` (VPN IP)
`execution_routes`	`src/routes/execution_routes.py`	15	Mixed: VPN-IP drone callbacks + JWT UI reads
`geofence_routes`	`src/routes/geofence_routes.py`	11	JWT
`billing_routes`	`src/routes/billing_routes.py`	10	JWT + public `pricing` + Stripe-Signature `webhook`
`mission_routes`	`src/routes/mission_routes.py`	9	JWT
`asset_routes`	`src/routes/asset_routes.py`	8	Mixed: VPN-IP upload callbacks + JWT reads
`calendar_routes`	`src/routes/calendar_routes.py`	7	JWT
`vpn_routes`	`src/routes/vpn_routes.py`	5	JWT
`video_room_routes`	`src/routes/video_room_routes.py`	4	JWT; `create` authed by drone video-room token
`isaac_sim_routes`	`src/routes/isaac_sim_routes.py`	4	JWT
`user_routes`	`src/routes/user_routes.py`	1	JWT

geofence_routes is registered and active even though the top-level CLAUDE.md architecture summary omits geofences. Trust src/main.py for the live blueprint list.

Three coexisting auth models

The gateway serves three different callers, each trusted by a different mechanism. This is intentional — the same rosbridge/topic contract makes SITL and physical drones interchangeable, but the callers are not.

JWT Bearer — the Dashboard. Validated by Flask-JWT-Extended (HS256). See Authentication & JWT Lifecycle.
VPN source IP — physical drone and agent callbacks. The check_vpn_ip decorator (src/middleware/drone_vpn.py) trusts a request whose remote_addr / X-Real-IP / X-Forwarded-For starts with 10.71. (the drone WireGuard subnet), or an X-Drone-IP header naming a SKYHUB_SITL_* container when ENABLE_SITL is set. It sets request.vpn_ip and returns 400 otherwise. These endpoints carry no JWT. See VPN IP Authentication & Jumphost Routing.
Token / signature — the 10-digit drone activation token header, the per-drone video-room bearer token, and the Stripe-Signature header on POST /billing/webhook.

Full details, status-code conventions, and the auth-per-endpoint matrix live in HTTP API Overview & Auth Models.

Design: thin routes, service delegation

Route handlers do the boring parts — parse the request, authorize, and translate a service result into an HTTP response — then delegate all business logic to a service singleton. Every service is instantiated once at import time in the composition root src/application/app.py and imported by the routes that need it. A representative handler:

src/routes/user_routes.py

@user_routes.route("/user", methods=["GET"])
@jwt_required()
def get_user_info():
    try:
        user_id = get_jwt_identity()
        user = user_service.get_user_by_id(user_id)
        if not user:
            return get_error_response("User not found", 404)
        return get_success_response(user.to_dict())
    except Exception:
        return get_error_response("Cannot get user info", 500)

Response envelope

Newer routes use the helpers in src/utils/common_helper.py:

get_success_response(data, message, status_code) → {"success": true, "data": ..., "message": ...} (common_helper.py:4). Omit data to drop the key; pass data=None to include an explicit null.
get_error_response(code, message) → ({"success": false, "error": {"code": code, "message": message}}, code) (common_helper.py:24).

The envelope is not universal. Older drone_routes, mission_routes, and geofence_routes return raw jsonify(...) with bare fields and frequently use 201 for reads and updates (e.g. GET /drones, PATCH /mission/point/<id>). The current Dashboard depends on these exact shapes and codes — changing them is a breaking change. This inconsistency is catalogued in HTTP API Overview & Auth Models.

Where things live (`src/` map)

Path	Role
`src/main.py`	App factory / gunicorn entrypoint: registers the 12 blueprints, Swagger, CORS, `JWTManager`, `Bcrypt`, `SocketIO`, and wires socket routes
`src/application/app.py`	Composition root — service singletons, the `get_service(drone_type)` factory, and `get_vpn_service()` lazy init
`src/application/settings.py`	Environment configuration (see Gateway Environment Variables)
`src/routes/`	HTTP blueprints + `socket_routes.py` (Socket.IO telemetry handlers)
`src/service/`	Business-logic tier (see Service Layer & Factory)
`src/models/`	SQLAlchemy ORM models (User, Drone, Mission, Asset, MissionExecution, Subscription, Geofence, Calendar…)
`src/rosbridge/`	Drone WebSocket connection management: `connection.py`, `request_format.py`, `socket.py`
`src/middleware/`	`drone_vpn.py` — the `check_vpn_ip` decorator
`src/utils/`	`common_helper.py`, `drone_types.py`, `mavros_topics.py`, `drone_utils.py`, `email_templates.py`
`src/connector/`	`db_connection.py` — DB/SQLAlchemy wiring
`src/diagnostic/`	`logs.py` — logging + OpenTelemetry log configuration
`src/drone/`	`messages.py` — drone message helpers
`src/migrator.py`	Alembic migration helper (see Migrations & DB Connection)

Deciding where new backend logic belongs

Route handler — request plumbing only

Parse and validate input, run the auth decorator (@jwt_required() or @check_vpn_ip), call one service, and shape the response with get_success_response / get_error_response. Keep it thin.

Service — the business logic

Add or extend a class in src/service/. Drone operations should go through DroneControlService (rosbridge dispatch) or a DroneService subclass obtained via get_service(drone_type). See Service Layer & Factory and DroneControlService & Rosbridge Dispatch.

Wire the singleton

Instantiate any new service once in src/application/app.py and import it from the route module — do not construct services inside request handlers.

Persistence & external calls

Add ORM models under src/models/; reach drones only through the pooled rosbridge Connection; put S3/Stripe/Janus/EC2 access behind a service, never in a route.

Explore the gateway

HTTP API Overview & Auth Models

Base path, the 12 blueprints, response envelope, and the three auth models in depth.

Drone Management & Control Actions

Drone CRUD and the ~20 /drone/action/* MAVROS commands.

Socket.IO Telemetry Streaming

Handshake, room subscriptions, stream types, and the dashboard fan-out.

Executions, Assets & Reports

VPN-IP drone callbacks, upload flow, log analysis, archives, and reports.

Missions & Geofences API

Mission and geofence CRUD plus MAVLink waypoint format.

Billing, Calendar, VPN, Video & Isaac Sim

Stripe endpoints, scheduling, VPN config, video rooms, and Isaac Sim control.

Service Layer & get_service Factory

How services are wired as singletons and the physical/SITL factory.

Rosbridge Connection & Reconnect

The persistent drone WebSocket, reconnect, and subscription tracking.

HTTP & Socket.IO API

Services & Realtime Internals

Data, Config & Ops

Gateway Service Overview

What the gateway is responsible for

Auth & accounts

Drone control

Real-time telemetry

SITL orchestration

Media & flight data

Integrations

Tech stack

The API surface

12 blueprints

Three coexisting auth models

Design: thin routes, service delegation

Response envelope

Where things live (`src/` map)

Deciding where new backend logic belongs

Explore the gateway

HTTP API Overview & Auth Models

Drone Management & Control Actions

Socket.IO Telemetry Streaming

Executions, Assets & Reports

Missions & Geofences API

Billing, Calendar, VPN, Video & Isaac Sim

Service Layer & get_service Factory

Rosbridge Connection & Reconnect

​What the gateway is responsible for

Auth & accounts

Drone control

Real-time telemetry

SITL orchestration

Media & flight data

Integrations

​Tech stack

​The API surface

​12 blueprints

​Three coexisting auth models

​Design: thin routes, service delegation

​Response envelope

​Where things live (src/ map)

​Deciding where new backend logic belongs

​Explore the gateway

HTTP API Overview & Auth Models

Drone Management & Control Actions

Socket.IO Telemetry Streaming

Executions, Assets & Reports

Missions & Geofences API

Billing, Calendar, VPN, Video & Isaac Sim

Service Layer & get_service Factory

Rosbridge Connection & Reconnect

What the gateway is responsible for

Tech stack

The API surface

12 blueprints

Three coexisting auth models

Design: thin routes, service delegation

Response envelope

Where things live (`src/` map)

Deciding where new backend logic belongs

Explore the gateway