API Architecture Overview

The Apollon API is a Rust application built with Actix-web that provides REST, GraphQL, and WebSocket interfaces for real-time GPS tracking and logistics management.

Tech Stack

Component	Technology
HTTP framework	Actix-web 4
Database	PostgreSQL 17 via sqlx
Time-series	TimescaleDB (separate pool)
GraphQL	async-graphql with Actix integration
WebSocket	actix-ws with per-channel tokio broadcast (speed, gps, trips, vessels)
AIS	AISstream.io via tokio-tungstenite (vessel tracking, binary frames)
OpenAPI	utoipa + utoipa-swagger-ui
Config	config-rs (TOML + env vars)
Telemetry	tracing + Sentry
Error handling	thiserror + custom ApiError type

Crate Structure

The API is split into 9 focused crates plus the binary:

platform/api/          Binary entry point (main.rs)
  |
  +-- apollon-config       Configuration types (Settings, TOML + env)
  +-- apollon-common       Shared error types (ApiError) and response wrappers (LinkedResponse)
  +-- apollon-db           Database models, queries, pool init, migrations
  +-- apollon-peplink      Peplink router client (auth, GPS polling, mock provider)
  +-- apollon-rest         REST route definitions, handlers, middleware, OpenAPI spec
  +-- apollon-graphql      GraphQL schema, queries, mutations, types
  +-- apollon-websocket    WebSocket server, GPS + speed broadcaster, AIS vessel tracking (ais.rs), channel system
  +-- apollon-forwarding   GPS data forwarding to external services
  +-- apollon-telemetry    Tracing initialization and Sentry integration

Dependency Flow

api (binary)
  +-- apollon-config
  +-- apollon-telemetry
  +-- apollon-db -----------> apollon-config
  +-- apollon-peplink ------> apollon-config
  +-- apollon-common
  +-- apollon-rest ---------> apollon-common, apollon-db, apollon-peplink,
  |                           apollon-graphql, apollon-forwarding, apollon-config
  +-- apollon-graphql ------> apollon-common, apollon-db, apollon-peplink,
  |                           apollon-forwarding
  +-- apollon-websocket ----> apollon-peplink
  +-- apollon-forwarding ---> apollon-config

Server Startup Sequence

The server starts in 16 stages defined in main.rs:

Stage	Description
1	Configuration -- Load Settings from TOML files + APOLLON__* env vars
2	Tracing -- Initialize structured logging with configured level
3	Sentry -- Initialize error reporting (optional, requires DSN)
4	Database pools -- Connect PostgreSQL main pool + TimescaleDB pool
5	Migrations -- Run sqlx migrations on both databases
6	GPS provider -- Create Peplink client or mock provider based on config
7	GPS init -- Authenticate with Peplink router (or start mock simulation)
8	Forwarding -- Initialize GPS data forwarding service
9	WebSocket server -- Create WsServer with per-channel broadcast senders (speed, gps, trips, vessels)
10	GPS broadcaster + AIS -- Create GpsBroadcaster (feeds speed + gps channels) and AIS client (feeds vessels channel)
11	Shutdown signal -- Create watch channel for coordinated shutdown
12	Broadcast loops -- Spawn speed and GPS broadcast tasks (poll GPS at interval)
13	GPS poll loop -- Spawn 60s GPS recording task (saves to TimescaleDB)
14	Forwarding loop -- Spawn 60s forwarding task (sends to external service)
15	GraphQL schema -- Build async-graphql schema with runtime context
16	HTTP server -- Start Actix-web with middleware stack and route configuration

Middleware Stack Order

Middleware is applied in reverse registration order (last registered runs first):

1. Compress -- gzip/brotli response compression
2. Rate Limiter -- Per-IP sliding window rate limiting
3. API Key Auth -- X-API-Key header validation
4. CORS -- Cross-origin request handling
5. Security Headers -- X-Content-Type-Options, CSP, HSTS, etc.

Route Registration

All REST routes are mounted under /v1:

/                     GET   -> Redirect to /v1
/health               GET   -> System health check
/ws                   GET   -> WebSocket upgrade
/v1                   GET   -> API info and version
/v1/peplink/gps/*     GET   -> GPS endpoints
/v1/trips/*           CRUD  -> Trip management
/v1/clients/*         CRUD  -> Client management
/v1/categories/*      CRUD  -> Category management
/v1/gql               POST  -> GraphQL endpoint
/v1/graphiql          GET   -> GraphiQL IDE
/v1/schema            GET   -> GraphQL SDL
/v1/openapi.json      GET   -> OpenAPI spec
/v1/swagger-ui/*      GET   -> Swagger UI

Graceful Shutdown

When the server receives a shutdown signal, it executes 9 cleanup steps:

Step	Action
0	Actix-web stops accepting new connections
1	Stop GPS broadcaster and AIS client (cancel broadcast intervals, close AIS WebSocket)
2	Signal GPS poll loop to exit via watch channel
3	Signal forwarding loop to exit via watch channel
4	Peplink cleanup (revoke auth token, cancel renewal timer)
5	Flush forwarding queue (process remaining entries)
6	Close WebSocket connections with code 1000
7	Drain database pools (main + TimescaleDB)
8	Flush Sentry events (2s timeout)
9	Exit with code 0