Apollon GPS Tracking System

Apollon is a real-time GPS tracking system for logistics and cargo, built on Peplink router hardware. It provides REST, GraphQL and WebSocket APIs for live position tracking, trip management, AIS vessel tracking, water level monitoring and AIS watchlist proximity alerts.

Architecture

                    ┌──────────────┐
                    │   Peplink    │
                    │   Router     │
                    └──────┬───────┘
                           │
┌─────────────┐     ┌──────┴───────┐     ┌────────────────┐
│  Next.js     │────▶│   Rust API   │────▶│  PostgreSQL    │
│  Frontend    │     │  (Actix-web) │     │  (Relational)  │
└──────┬──────┘     └──────────────┘     └────────────────┘
       │                                  ┌────────────────┐
       │ WebSocket (direct)               │  TimescaleDB   │
       └─────────────────────────────────▶│  (GPS Series)  │
                                          └────────────────┘

Data Flow:

• Browser → fetch() → Next.js API Routes → gql() → Rust API /v1/gql
• Browser → WebSocket → Rust API /v1/ws (direct, no proxy)

Core Components

Component	Technology	Purpose
API	Rust (Actix-web, sqlx, async-graphql)	REST + GraphQL + WebSocket server
Web	Next.js 16, React 19, shadcn/ui, Tailwind CSS 4	Frontend with live map and trip management
Shared API	@elcto/apollon-api (TypeScript)	GraphQL client, WebSocket client, types
Shared UI	@elcto/apollon-ui (React)	Map, Spinner, ThemeToggle components
Shared Logger	@elcto/apollon-logger (TypeScript)	Structured logger with Sentry integration
Database	PostgreSQL 18	Clients, trips, categories, contacts
Time-Series	TimescaleDB	GPS locations with hypertable compression
GPS Source	Peplink Router API	Hardware GPS with automatic token auth

Monorepo Structure

shared/
  api/               @elcto/apollon-api — GraphQL client, WebSocket, types
  ui/                @elcto/apollon-ui — Map, Spinner, ThemeToggle
  logger/            @elcto/apollon-logger — Structured logger, Sentry binding
platform/
  api/               Rust API (12 crates)
  web/               Next.js 16 frontend
  docs/              Documentation (Docusaurus)

Crate Structure

The Rust API is organized as a Cargo workspace with 12 crates:

Crate	Purpose
apollon-common	Shared types, error handling, API response format
apollon-config	TOML + env var configuration loading
apollon-db	Database models, sqlx queries, migrations
apollon-rest	REST handlers, middleware (auth, rate limit, security)
apollon-graphql	GraphQL schema, queries, mutations
apollon-websocket	WebSocket server, GPS/Speed/Trips/Vessels/Watchlist channels, AIS client
apollon-peplink	Peplink router client with token management
apollon-forwarding	GPS data forwarding to external services
apollon-pegelonline	Pegelonline water level client with caching
apollon-storage	Generic file storage (upload, serve, delete)
apollon-watchlist	AIS MMSI watchlist with proximity matching and alerts
apollon-telemetry	Tracing and Sentry integration
api	Main binary, server startup, background loops

API Protocols

• REST — Endpoints under /v1 with OpenAPI documentation
• GraphQL — Full schema at /v1/gql with GraphiQL IDE
• WebSocket — 5 channels at /v1/ws: speed, gps, trips, vessels, watchlist