Skip to content

Architecture

Jump to bottom
TamTunnel edited this page Jan 4, 2026 · 1 revision

SpaceComms Architecture

Technical design for software architects and integrators

System Overview

SpaceComms is a peer-to-peer protocol for exchanging space traffic coordination data. Each participant runs a node that connects to other nodes (peers) to exchange messages about space objects, conjunction events, and maneuver coordination.

Design Principles

  1. Protocol-first: Clear message specifications enable independent implementations
  2. Stateless messaging, stateful nodes: Each message is self-contained; nodes maintain routing state
  3. Pluggable architecture: Adapters abstract external data sources
  4. Eventual consistency: Nodes converge on shared state through announcements
  5. Defense in depth: Auth, validation, and audit at multiple layers

High-Level Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              SpaceComms Node                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐                  │
│  │   REST API   │    │   Protocol   │    │   Adapters   │                  │
│  │   (HTTP/2)   │    │   Layer      │    │              │                  │
│  │              │    │              │    │ ┌──────────┐ │                  │
│  │ /cdm         │    │ Messages     │    │ │Space-Trk │ │                  │
│  │ /peers       │    │ Routing      │    │ └──────────┘ │                  │
│  │ /objects     │    │ Sessions     │    │ ┌──────────┐ │                  │
│  │ /health      │    │              │    │ │Const Hub │ │                  │
│  └──────┬───────┘    └──────┬───────┘    │ └──────────┘ │                  │
│         │                   │            └──────┬───────┘                  │
│         │                   │                   │                          │
│  ┌──────▼───────────────────▼───────────────────▼───────┐                  │
│  │                      Core Engine                      │                  │
│  │                                                       │                  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │                  │
│  │  │   Storage   │  │  CDM Proc.  │  │   Routing   │   │                  │
│  │  │  (Memory)   │  │  & Valid.   │  │   Engine    │   │                  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘   │                  │
│  └───────────────────────────────────────────────────────┘                  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ Peer Connections
                                    ▼
                    ┌───────────────────────────────┐
                    │        Other Nodes            │
                    │   (Operators, Providers,      │
                    │    Regulators)                │
                    └───────────────────────────────┘

Component Details

REST API Layer

Exposes HTTP/2 endpoints for external interaction:

Endpoint Method Purpose
/health GET Health check and node status
/cdm POST Ingest CDM from local source
/cdms GET List active CDMs
/cdms/{id} GET Retrieve specific CDM
/objects GET List tracked space objects
/objects/{id} GET Retrieve specific object
/peers GET List configured peers
/peers POST Add new peer
/peers/{id} DELETE Remove peer

Request/Response Format: JSON with versioned envelope

Protocol Layer

Handles peer-to-peer communication:

Message Types

enum MessageType {
    Hello,              // Capability negotiation
    ObjectStateAnnounce,// New/updated object
    ObjectStateWithdraw,// Object no longer tracked
    CdmAnnounce,        // New conjunction data
    CdmWithdraw,        // CDM no longer valid
    ManeuverIntent,     // Planned maneuver
    ManeuverStatus,     // Maneuver execution status
    Heartbeat,          // Connection health
    Error,              // Error response
}

Session Management

┌─────────────┐                              ┌─────────────┐
│   Node A    │                              │   Node B    │
└──────┬──────┘                              └──────┬──────┘
       │                                            │
       │─────────── HELLO (capabilities) ──────────►│
       │                                            │
       │◄────────── HELLO (capabilities) ───────────│
       │                                            │
       │          [Session Established]             │
       │                                            │
       │◄───────────── HEARTBEAT ───────────────────│
       │─────────────── HEARTBEAT ─────────────────►│
       │                                            │
       │            [Session Active]                │
       │                                            │

Core Engine

Storage Layer

trait Storage: Send + Sync {
    fn store_object(&self, obj: ObjectRecord) -> Result<()>;
    fn get_object(&self, id: &str) -> Result<Option<ObjectRecord>>;
    fn list_objects(&self) -> Result<Vec<ObjectRecord>>;

    fn store_cdm(&self, cdm: CdmRecord) -> Result<()>;
    fn get_cdm(&self, id: &str) -> Result<Option<CdmRecord>>;
    fn list_cdms(&self) -> Result<Vec<CdmRecord>>;
    fn withdraw_cdm(&self, id: &str) -> Result<()>;
}

Reference implementation uses in-memory storage with file-based persistence hooks.

CDM Processing

  1. Parse: Validate JSON against schema
  2. Normalize: Convert to internal CdmRecord
  3. Validate: Check required fields, value ranges
  4. Store: Persist to storage layer
  5. Route: Forward to peers per routing policy

Routing Engine

Inspired by BGP:

struct RoutingPolicy {
    peer_id: String,
    action: Action,        // Accept, Reject, Modify
    priority: u32,
    filters: Vec<Filter>,  // Object type, source, etc.
}

enum Action {
    Accept,
    Reject,
    ModifyAndAccept { modifications: Vec<Modification> },
}

Adapters Architecture

Adapters abstract external data sources and sinks:

┌─────────────────────────────────────────────────────────────────┐
│                        Adapter Interface                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  trait Adapter: Send + Sync {                                   │
│      fn name(&self) -> &str;                                    │
│      fn poll_objects(&self) -> Result<Vec<ObjectRecord>>;       │
│      fn poll_cdms(&self) -> Result<Vec<CdmRecord>>;             │
│      fn on_cdm_received(&self, cdm: &CdmRecord);                │
│      fn on_maneuver_intent(&self, intent: &ManeuverIntent);     │
│  }                                                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
        │                           │                      │
        ▼                           ▼                      ▼
┌───────────────┐         ┌───────────────┐      ┌───────────────┐
│  Space-Track  │         │ Constellation │      │    Custom     │
│     Mock      │         │   Hub Mock    │      │   Adapter     │
│               │         │               │      │               │
│ Static JSON   │         │ Satellite     │      │ Your system   │
│ fixtures      │         │ registry +    │      │ integration   │
│               │         │               │      │               │
└───────────────┘         └───────────────┘      └───────────────┘

Multi-Node Topology

SpaceComms supports arbitrary mesh topologies:

         ┌─────────────┐
         │   STM       │
         │  Provider   │
         └──────┬──────┘
                │
        ┌───────┴───────┐
        │               │
        ▼               ▼
┌─────────────┐   ┌─────────────┐
│  Operator A │   │  Operator B │
│  (100 sats) │   │  (50 sats)  │
└──────┬──────┘   └──────┬──────┘
       │                 │
       │    ┌────────────┘
       │    │
       ▼    ▼
┌─────────────┐
│  Regulator  │
│  (observer) │
└─────────────┘

Routing behavior:

  • CDMs propagate through mesh based on policies
  • Loops prevented via message IDs and hop counts
  • Nodes can filter what they forward

Security Architecture

Authentication

┌─────────────┐                              ┌─────────────┐
│   Node A    │                              │   Node B    │
└──────┬──────┘                              └──────┬──────┘
       │                                            │
       │──────── TLS Handshake (mTLS) ─────────────►│
       │                                            │
       │────── Token in HELLO message ─────────────►│
       │                                            │
       │◄─────── Token validation ──────────────────│
       │                                            │
       │         [Authenticated Session]            │

Authorization

  • Per-peer policies control message acceptance
  • Object-level filters restrict propagation
  • Audit logging for all message exchanges

Encryption

  • TLS 1.3 for transport
  • Optional message-level signatures (future)

Observability

Health Endpoints

GET /health

{
  "status": "healthy",
  "node_id": "node-alpha-01",
  "uptime_seconds": 86400,
  "peers": {
    "connected": 3,
    "total": 5
  },
  "objects_tracked": 1250,
  "cdms_active": 42
}

Logging

Structured JSON logs via tracing:

{
  "timestamp": "2024-01-15T14:30:00Z",
  "level": "INFO",
  "target": "spacecomms::node::routing",
  "message": "CDM propagated to peer",
  "cdm_id": "cdm-2024-001234",
  "peer_id": "peer-operator-b",
  "request_id": "req-abc123"
}

Metrics

Prometheus-compatible metrics endpoint exposed at /metrics:

  • Message counters (sent/received/errors)
  • Peer connectivity gauges
  • Protocol statistics (CDMs active/announced)

Performance Considerations

Detailed performance characteristics are documented in Performance & Scaling.

Design Choices

  • Async Networking: Built on Tokio for non-blocking I/O, allowing thousands of concurrent connections.
  • Message Parsing: Zero-copy deserialization where possible (serde_json).
  • Stateless Verification: Most validation checks do not require database lookups, increasing throughput.

For benchmarking methodology and scale assumptions, see the performance guide.

Clone this wiki locally