# juanpablojs1024/orbital-net architecture

> Architecture diagram of the GitHub repository juanpablojs1024/orbital-net, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/juanpablojs1024/orbital-net
- Repository: https://github.com/juanpablojs1024/orbital-net

## Overview

Orbital Net simulates satellite and ground-station motion, derives changing visibility, and exposes that state to routing, communications, and the control-center UI. Users can create or remove nodes, inspect live topology and message logs, and send messages between nodes. Communications handles routing and congestion queues; storage persists message logs. The README also describes Kubernetes horizontal scaling. Service interactions follow the sampled entry points and documented responsibilities; implementation details not sampled are represented only where the README supports them.

Main entry points: [`services/sim-service/internal/server/server.go`](https://github.com/juanpablojs1024/orbital-net/blob/main/services/sim-service/internal/server/server.go) (Simulation gRPC), [`services/communications-service/cmd/main.go`](https://github.com/juanpablojs1024/orbital-net/blob/main/services/communications-service/cmd/main.go) (Communications gRPC), [`services/control-center-service/main.go`](https://github.com/juanpablojs1024/orbital-net/blob/main/services/control-center-service/main.go) (HTTP API), [`services/pathfinder-service/cmd/main.go`](https://github.com/juanpablojs1024/orbital-net/blob/main/services/pathfinder-service/cmd/main.go) (Pathfinder gRPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation"]
  node_simserver["Simulation gRPC<br/>[server.go]"]
  node_simloop["Physics Loop<br/>[main.go]"]
  node_orbitmodel["Orbital Model"]
  node_simproto["Simulation Contract<br/>[sim-service.proto]"]
end

subgraph group_routing["Routing"]
  node_pathserver["Pathfinder gRPC<br/>[main.go]"]
  node_graphmodel["Network Graph<br/>[graph.go]"]
end

subgraph group_messaging["Messaging"]
  node_comsserver["Communications gRPC<br/>[main.go]"]
  node_commodel["Message Protocol"]
  node_queue["Pending Queue<br/>[main.go]"]
  node_storage["Storage gRPC<br/>[main.go]"]
  node_logfile[("Message Log<br/>[main.go]")]
  node_autoscaler["Communications HPA"]
end

subgraph group_control["Control Center"]
  node_browser["Browser UI<br/>[index.html]"]
  node_gateway["HTTP API<br/>[main.go]"]
end

node_operator(("User"))

node_operator -->|"uses"| node_browser
node_browser -->|"HTTP requests"| node_gateway
node_gateway -->|"node commands"| node_simserver
node_simloop -->|"ticks physics"| node_orbitmodel
node_simserver -->|"reads state"| node_orbitmodel
node_simserver -->|"streams state"| node_simproto
node_simserver -->|"streams topology"| node_gateway
node_simserver -->|"streams topology"| node_pathserver
node_simserver -->|"streams topology"| node_comsserver
node_gateway -->|"sends messages"| node_comsserver
node_comsserver -->|"delegates delivery"| node_commodel
node_comsserver -->|"queues overload"| node_queue
node_comsserver -->|"requests routes"| node_pathserver
node_commodel -->|"persists messages"| node_storage
node_gateway -->|"requests logs"| node_storage
node_storage -->|"appends and reads"| node_logfile
node_pathserver -->|"builds and queries"| node_graphmodel
node_autoscaler -.->|"scales replicas"| node_comsserver

click node_browser "https://github.com/juanpablojs1024/orbital-net/blob/main/services/control-center-service/web/index.html"
click node_gateway "https://github.com/juanpablojs1024/orbital-net/blob/main/services/control-center-service/main.go"
click node_simserver "https://github.com/juanpablojs1024/orbital-net/blob/main/services/sim-service/internal/server/server.go"
click node_simloop "https://github.com/juanpablojs1024/orbital-net/blob/main/services/sim-service/cmd/main.go"
click node_orbitmodel "https://github.com/juanpablojs1024/orbital-net/tree/main/services/sim-service/internal/model"
click node_simproto "https://github.com/juanpablojs1024/orbital-net/blob/main/pkg/proto/sim/sim-service.proto"
click node_comsserver "https://github.com/juanpablojs1024/orbital-net/blob/main/services/communications-service/cmd/main.go"
click node_commodel "https://github.com/juanpablojs1024/orbital-net/tree/main/services/communications-service/internal/model"
click node_queue "https://github.com/juanpablojs1024/orbital-net/blob/main/services/communications-service/cmd/main.go"
click node_pathserver "https://github.com/juanpablojs1024/orbital-net/blob/main/services/pathfinder-service/cmd/main.go"
click node_graphmodel "https://github.com/juanpablojs1024/orbital-net/blob/main/services/pathfinder-service/internal/model/graph.go"
click node_storage "https://github.com/juanpablojs1024/orbital-net/blob/main/services/storage-service/cmd/main.go"
click node_logfile "https://github.com/juanpablojs1024/orbital-net/blob/main/services/storage-service/cmd/main.go"
click node_autoscaler "https://github.com/juanpablojs1024/orbital-net/blob/main/k8s/hpa-communications.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_simserver,node_simloop,node_orbitmodel,node_simproto,node_operator toneBlue
class node_pathserver,node_graphmodel toneAmber
class node_comsserver,node_commodel,node_queue,node_storage,node_logfile,node_autoscaler toneMint
class node_browser,node_gateway toneRose
```

## Components

### Simulation

- [Simulation gRPC](https://github.com/juanpablojs1024/orbital-net/blob/main/services/sim-service/internal/server/server.go): `services/sim-service/internal/server/server.go`
- [Physics Loop](https://github.com/juanpablojs1024/orbital-net/blob/main/services/sim-service/cmd/main.go): `services/sim-service/cmd/main.go`
- [Orbital Model](https://github.com/juanpablojs1024/orbital-net/tree/main/services/sim-service/internal/model): `services/sim-service/internal/model`
- [Simulation Contract](https://github.com/juanpablojs1024/orbital-net/blob/main/pkg/proto/sim/sim-service.proto): `pkg/proto/sim/sim-service.proto`

### Routing

- [Pathfinder gRPC](https://github.com/juanpablojs1024/orbital-net/blob/main/services/pathfinder-service/cmd/main.go): `services/pathfinder-service/cmd/main.go`
- [Network Graph](https://github.com/juanpablojs1024/orbital-net/blob/main/services/pathfinder-service/internal/model/graph.go): `services/pathfinder-service/internal/model/graph.go`

### Messaging

- [Communications gRPC](https://github.com/juanpablojs1024/orbital-net/blob/main/services/communications-service/cmd/main.go): `services/communications-service/cmd/main.go`
- [Message Protocol](https://github.com/juanpablojs1024/orbital-net/tree/main/services/communications-service/internal/model): `services/communications-service/internal/model`
- [Pending Queue](https://github.com/juanpablojs1024/orbital-net/blob/main/services/communications-service/cmd/main.go): `services/communications-service/cmd/main.go`
- [Storage gRPC](https://github.com/juanpablojs1024/orbital-net/blob/main/services/storage-service/cmd/main.go): `services/storage-service/cmd/main.go`
- [Message Log](https://github.com/juanpablojs1024/orbital-net/blob/main/services/storage-service/cmd/main.go): `services/storage-service/cmd/main.go`
- [Communications HPA](https://github.com/juanpablojs1024/orbital-net/blob/main/k8s/hpa-communications.yaml): `k8s/hpa-communications.yaml`

### Control Center

- [Browser UI](https://github.com/juanpablojs1024/orbital-net/blob/main/services/control-center-service/web/index.html): `services/control-center-service/web/index.html`
- [HTTP API](https://github.com/juanpablojs1024/orbital-net/blob/main/services/control-center-service/main.go): `services/control-center-service/main.go`

### Other components

- **User**

## Connections

- User → Browser UI: uses
- Browser UI → HTTP API: HTTP requests
- HTTP API → Simulation gRPC: node commands
- Physics Loop → Orbital Model: ticks physics
- Simulation gRPC → Orbital Model: reads state
- Simulation gRPC → Simulation Contract: streams state
- Simulation gRPC → HTTP API: streams topology
- Simulation gRPC → Pathfinder gRPC: streams topology
- Simulation gRPC → Communications gRPC: streams topology
- HTTP API → Communications gRPC: sends messages
- Communications gRPC → Message Protocol: delegates delivery
- Communications gRPC → Pending Queue: queues overload
- Communications gRPC → Pathfinder gRPC: requests routes
- Message Protocol → Storage gRPC: persists messages
- HTTP API → Storage gRPC: requests logs
- Storage gRPC → Message Log: appends and reads
- Pathfinder gRPC → Network Graph: builds and queries
- Communications HPA → Communications gRPC: scales replicas