TALOS Ground Station Network -- Executive Summary¶

Date: April 2026 Version: 0.3.0 Repository: gitlab.com/pierros/talos Built by: Libre Space Foundation

1. Project Status¶

TALOS (Tracking, Acquisition, and Link Operation System) is a distributed satellite ground station controller that coordinates multiple antenna stations in real time from a centralized SGP4 physics engine running at 2 Hz with Doppler correction. No other open-source ground station network offers real-time multi-station coordination from a central propagator.

At v0.3.0, the system ships as a monorepo with five components:

Component	Role
Core API (`core/`)	FastAPI web server -- REST API, dashboard, authentication, SatNOGS sync, PostgreSQL persistence
Director (`director/`)	Real-time physics engine -- SGP4 propagation, Doppler correction, per-station campaign command publishing
Agent (`agent/`)	Edge client (Raspberry Pi) -- MQTT-to-Hamlib bridge for rotator and radio control
Shared (`shared/`)	Cross-component library -- MQTT topics, Pydantic v2 schemas, SatNOGS client, time utilities
Ops (`ops/`)	Docker Compose orchestration, Mosquitto broker config, Fly.io deployment

Test coverage: ~190 tests across unit, smoke, campaign lifecycle, integration, physics, agent hardware, and load test suites. CI runs 8 test jobs plus 3 security scanners, 3 Docker builds, 3 Fly.io deploys, release automation, and GitLab Pages -- 18 jobs total in a DAG pipeline.

Infrastructure: GitLab CI/CD with SAST, secret detection, dependency scanning, JUnit/Cobertura reporting, Docker container registry, automated releases on semver tags, and MkDocs Material documentation deployed via GitLab Pages.

2. What Has Been Achieved¶

v0.1.0 -- Monorepo Consolidation (April 1, 2026)¶

Merged three separate repositories (talos-core, talos-agent, talos-ops) into a single monorepo. Extracted the Director as a standalone process. Created the shared library. Added signed session cookies, MQTT authentication, CI/CD via GitHub Actions, SatNOGS API caching, and six architecture research reports.

v0.2.0 -- Organization-Grade Architecture (April 1, 2026)¶

Replaced the single-mission model with a multi-tenant organization system. Added: organization model with slug-based identification, membership with RBAC (owner/operator/viewer), campaign system with lifecycle management, per-station campaign assignments, multi-satellite concurrent tracking in the Director, org-scoped MQTT topics and API endpoints, multi-campaign dashboard visualization, and Alembic database migrations.

v0.2.1 -- Operational Hardening (April 2, 2026)¶

Stabilized the v0.2 feature set. Added management pages for members, stations, campaigns, and settings. Introduced magic link email authentication via Resend API. Simplified the assignment model (removed time windows). Shipped 71 end-to-end tests covering org, station, campaign, and assignment APIs plus RBAC enforcement. Fixed campaign creation resilience, Fly.io deployment, and database connection reliability.

v0.3.0 -- Design System and CI/CD (April 3, 2026)¶

Introduced the TALOS Design System based on Astro UXDS (U.S. Space Force design language) with a unified dark-theme stylesheet. Rebuilt the dashboard and all pages using the new design system, replacing Bootstrap CSS. Migrated from GitHub Actions to a full GitLab CI/CD pipeline with DAG dependencies, security scanning, Docker builds, release automation, and GitLab Pages. Added GitLab issue/MR templates, CODEOWNERS, editorconfig, and expanded the Makefile to 16 targets. Shipped campaign end-to-end tests (33 tests) and smoke tests for logout.

3. Current Capabilities¶

Real-time multi-campaign tracking -- Different stations track different satellites concurrently, coordinated from a single 2 Hz physics engine with Doppler correction.
Organization model -- Multi-org support with membership management, station ownership scoped to organizations, and auto-org creation for new users.
Role-based access control -- Owner, operator, and viewer roles enforced on all org-scoped API endpoints.
Campaign lifecycle -- Draft, scheduled, active, completed, cancelled states with per-station assignment management.
SatNOGS integration -- Satellite catalog, TLEs, and transmitter metadata sourced from SatNOGS DB with response caching.
Magic link authentication -- Passwordless email login via Resend API with JWT tokens (10-minute TTL).
Public satellite tracker -- Standalone tracking page showcasing PHASMA-LAMARR, PHASMA-DIRAC, PeakSat, and ISS.
TALOS Design System -- Astro UXDS-based dark theme with CSS custom properties, applied across all pages.
Management dashboard -- Web pages for members, stations, campaigns, organization settings, and live multi-satellite visualization.
Edge-native agents -- Lightweight Python clients on Raspberry Pi bridging MQTT to Hamlib (rotctld/rigctld).
Magic Find -- Sky scanning across 8,000+ satellite orbits in milliseconds to identify unknown signals.

4. Architecture Health¶

Strengths:

Clean component separation that maps to real deployment boundaries (server, edge, infrastructure).
Proper logging framework (logging module with structured format) replacing earlier print() statements.
Pydantic v2 data contracts for all MQTT payloads prevent schema drift.
Alembic migrations provide safe, versioned schema evolution.
The CI/CD pipeline is comprehensive: lint, type check, 8 test suites, 3 security scanners, Docker builds with DAG dependencies, automated releases, and documentation deployment.
Signed session cookies with environment-sourced secrets; MQTT authentication enabled.

Concerns:

Test coverage is broad but shallow. Unit tests cover shared/ only; core/ and director/ lack dedicated unit test suites. The 190 tests are mostly integration and end-to-end; Cobertura coverage reporting runs only on shared and core during integration jobs. There is no coverage gate enforcing a minimum threshold.
Director scalability ceiling. The single-threaded Python physics loop works well for ~10 stations but performance degrades at ~50-100. Pass prediction still runs inline in the 2 Hz loop, risking cadence stalls. Ground track visualization wastes ~48 redundant SGP4 calls per tick.
No observability stack. No Prometheus metrics, no Grafana dashboards, no structured log aggregation beyond stdout. If the Director process crashes, there is no health check or alerting to detect the failure until a pass is missed.
Security gaps remain. The browser connects directly to the MQTT broker via WebSocket, giving client-side JavaScript access to command topics. No MQTT TLS is configured. No CORS middleware restricts cross-origin requests. No API rate limiting is in place.
Bootstrap JS retained. The design system replaced Bootstrap CSS but retains Bootstrap JS for modal and dropdown behavior -- a coupling that should eventually be eliminated with lightweight alternatives.

5. Key Risks¶

#	Risk	Impact	Mitigation
1	No observability -- Director crash goes undetected until a pass is missed	Missed tracking opportunities; no diagnostic data for debugging	Add Prometheus metrics, structured logging, and a health-check endpoint on the Director
2	Browser-to-MQTT path -- WebSocket MQTT in the browser gives JavaScript direct hardware control	Unauthorized antenna movement; potential safety issue	Route dashboard data through FastAPI WebSocket relay; remove browser-to-broker connection
3	Director scaling wall at ~50 stations -- Single-threaded Python loop with inline pass prediction	Cannot support growing station networks	Integrate dSGP4 for batch propagation; move pass prediction to a background thread
4	Single-region deployment -- All infrastructure on Fly.io with no redundancy	Full outage if Fly.io region goes down; latency for geographically distant stations	Add health monitoring first; evaluate multi-region deployment when station count justifies it
5	SatNOGS API dependency -- TLE and transmitter data sourced exclusively from SatNOGS DB	Service degradation if SatNOGS API is unavailable	Existing response caching mitigates short outages; add a fallback TLE source (Space-Track or CelesTrak)

6. Strategic Priorities¶

v0.4 -- Observability and Security Completion¶

The most urgent gap is knowing when things break and closing the browser-to-hardware path.

Add Prometheus metrics endpoints to Core API and Director (request latency, propagation loop timing, MQTT message rates, active campaign count).
Deploy a Grafana dashboard for station health, Director performance, and MQTT throughput.
Route dashboard visualization through a FastAPI WebSocket relay, eliminating the direct browser-to-MQTT broker connection.
Enable MQTT TLS (port 8883) and configure topic ACLs restricting each agent to its own station prefix.
Add CORS middleware with an explicit origin allowlist and API rate limiting on authentication endpoints.
Add a Director health-check endpoint and Docker health checks for all services.

v0.5 -- Scheduling and Scale¶

Move from manual station assignment to automated scheduling, and remove the Director's scaling bottleneck.

Integrate OR-Tools constraint solver for automatic station-to-campaign assignment based on predicted pass windows, station capabilities, and campaign priorities.
Replace Skyfield SGP4 with dSGP4 (ESA) for batch/GPU-accelerated propagation.
Move pass prediction to a background thread to protect the 2 Hz real-time loop.
Cache ground track computation to eliminate ~48 redundant SGP4 calls per tick.
Add a coverage-gate CI job enforcing a minimum test coverage threshold.

v0.6 -- Interoperability and Visualization¶

Adopt space industry standards and upgrade the visualization layer.

CesiumJS 3D globe replacing the Leaflet 2D map for orbital visualization with ground station coverage cones.
CCSDS 502.0 (OMM) for standardized TLE interchange, replacing raw JSON TLE storage.
CCSDS 503.0 (TDM) for tracking data export (azimuth, elevation, Doppler measurements).
SatNOGS coexistence layer: run talos-agent alongside satnogs-client on the same station hardware with a hardware mutex to prevent conflicts.

Longer Term¶

Regional Director sharding for 100+ station networks.
MQTT 5.0 shared subscriptions for horizontal scaling.
gr-satellites integration for SDR-based stations.
Conjunction alerting via CCSDS 508.0 (CDM).

7. Research Index¶

The following companion documents provide detailed analysis behind this summary:

Document	Focus
01 -- Architecture Review	Component design, state management, MQTT patterns, code quality assessment
02 -- Security Review	Threat model, authentication/authorization review, MQTT security, remediation plan
03 -- Operations and Scalability	CI/CD maturity, deployment topology, scaling analysis (10/100/1000 stations)
04 -- SatNOGS Integration	SatNOGS API usage, data flow, coexistence strategy, integration gaps
05 -- Technology Roadmap	dSGP4, CesiumJS, OR-Tools, Grafana, MQTT 5.0 evaluation and adoption plan

Previous research (v0.1 era) is preserved in docs/research/archive/ for historical reference.

One-Line Summary¶

TALOS v0.3.0 is a working real-time multi-station satellite tracker with organization support, RBAC, a custom design system, and a mature CI/CD pipeline -- the next priorities are observability, closing the browser-to-MQTT security gap, and constraint-based scheduling to move toward production readiness.