# dotchance/nodalarc architecture

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

- Interactive diagram: https://gitdiagram.com/dotchance/nodalarc
- Repository: https://github.com/dotchance/nodalarc
- Video tour (about a minute): https://gitdiagram.com/dotchance/nodalarc/video

## Overview

NodalArc is a browser-operated satellite network emulator: engineers configure a session, preview its orbital and ground-link feasibility, deploy it, then observe and probe real network workloads as topology changes. The graph follows that workflow through the API, Kubernetes reconciliation, orbital engines, scheduling, and node-level actuation, with separate branches for live inspection and measurement. README capabilities inform the broader product map; sampled excerpts confirm selected engine and service behavior, so uncertain internal call links are omitted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/dotchance/nodalarc/blob/main/frontend/src/App.tsx) (Browser App), [`services/vs_api/main.py`](https://github.com/dotchance/nodalarc/blob/main/services/vs_api/main.py) (VS API), [`services/ome/propagation_engine.py`](https://github.com/dotchance/nodalarc/blob/main/services/ome/propagation_engine.py) (Orbital Propagation), [`services/nodalarc_operator/handlers.py`](https://github.com/dotchance/nodalarc/blob/main/services/nodalarc_operator/handlers.py) (Session Operator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser Lab"]
  node_frontend["Browser App<br/>[App.tsx]"]
  node_wizard["Session Wizard<br/>[SessionWizard.tsx]"]
  node_builder["Session Builder<br/>[BuilderView.tsx]"]
  node_globe["Live Globe<br/>[Scene.tsx]"]
  node_topology["Topology View<br/>[TopologyView.tsx]"]
end

subgraph group_api["Session Services"]
  node_api["VS API<br/>[main.py]"]
  node_builder_service["Builder Save"]
  node_catalog[("Catalog Repository")]
  node_session_manager["Session Switcher<br/>[session_manager.py]"]
end

subgraph group_runtime["Orbital Runtime"]
  node_ome["Orbital Propagation"]
  node_isl["ISL Feasibility<br/>[isl_engine.py]"]
  node_ground["Ground Visibility"]
  node_snapshot["Snapshot Builder"]
  node_scheduler["Link Scheduler<br/>[dispatcher.py]"]
end

subgraph group_infrastructure["Network Substrate"]
  node_operator["Session Operator<br/>[handlers.py]"]
  node_node_agent["Node Agent<br/>[server.py]"]
  node_workloads["Router Workloads<br/>[adapter.py]"]
end

subgraph group_experiments["Inspection &amp; Measurement"]
  node_explain["Decision Explanations<br/>[explain.py]"]
  node_terminal["Node Terminal<br/>[terminal.py]"]
  node_measurement["Probe Measurement<br/>[flow_manager.py]"]
end

node_engineer(("Network Engineer"))
node_kubernetes{{"Kubernetes"}}
node_linux{{"Linux Network Nodes"}}
node_probe["Probe Daemon<br/>[probe_daemon.py]"]

node_engineer -->|"uses"| node_frontend
node_frontend -->|"opens"| node_wizard
node_frontend -->|"opens"| node_builder
node_wizard -->|"deploys session"| node_api
node_builder -->|"saves session"| node_api
node_api -->|"delegates save"| node_builder_service
node_builder_service -->|"reads and commits"| node_catalog
node_api -->|"reads catalog"| node_catalog
node_api -->|"switches session"| node_session_manager
node_session_manager -->|"applies session spec"| node_kubernetes
node_kubernetes -->|"dispatches lifecycle"| node_operator
node_operator -->|"reconciles workloads"| node_kubernetes
node_operator -->|"starts runtime"| node_ome
node_ome -->|"provides propagated states"| node_isl
node_ome -->|"provides propagated states"| node_ground
node_ome -->|"provides runtime state"| node_snapshot
node_isl -->|"provides link decisions"| node_scheduler
node_ground -->|"provides visibility"| node_scheduler
node_scheduler -->|"dispatches link changes"| node_node_agent
node_node_agent -->|"actuates networking"| node_linux
node_operator -->|"deploys workloads"| node_workloads
node_workloads -->|"runs in namespaces"| node_linux
node_frontend -->|"receives live state"| node_snapshot
node_frontend -->|"renders"| node_globe
node_frontend -->|"renders"| node_topology
node_frontend -->|"requests explanations"| node_explain
node_engineer -->|"opens node shell"| node_terminal
node_frontend -->|"requests terminal"| node_terminal
node_engineer -->|"runs probes"| node_measurement
node_measurement -->|"manages flows"| node_probe
node_probe -->|"measures traffic"| node_linux

click node_frontend "https://github.com/dotchance/nodalarc/blob/main/frontend/src/App.tsx"
click node_wizard "https://github.com/dotchance/nodalarc/blob/main/frontend/src/catalog/SessionWizard.tsx"
click node_builder "https://github.com/dotchance/nodalarc/blob/main/frontend/src/builder/BuilderView.tsx"
click node_globe "https://github.com/dotchance/nodalarc/blob/main/frontend/src/globe/r3f/Scene.tsx"
click node_topology "https://github.com/dotchance/nodalarc/blob/main/frontend/src/topology/TopologyView.tsx"
click node_api "https://github.com/dotchance/nodalarc/blob/main/services/vs_api/main.py"
click node_builder_service "https://github.com/dotchance/nodalarc/blob/main/services/vs_api/builder_session_service.py"
click node_catalog "https://github.com/dotchance/nodalarc/blob/main/lib/nodalarc/filesystem_catalog_repository.py"
click node_session_manager "https://github.com/dotchance/nodalarc/blob/main/services/vs_api/session_manager.py"
click node_operator "https://github.com/dotchance/nodalarc/blob/main/services/nodalarc_operator/handlers.py"
click node_ome "https://github.com/dotchance/nodalarc/blob/main/services/ome/propagation_engine.py"
click node_isl "https://github.com/dotchance/nodalarc/blob/main/services/ome/isl_engine.py"
click node_ground "https://github.com/dotchance/nodalarc/blob/main/services/ome/ground_visibility_engine.py"
click node_snapshot "https://github.com/dotchance/nodalarc/blob/main/services/ome/snapshot_builder.py"
click node_scheduler "https://github.com/dotchance/nodalarc/blob/main/services/scheduler/dispatcher.py"
click node_node_agent "https://github.com/dotchance/nodalarc/blob/main/services/node_agent/server.py"
click node_workloads "https://github.com/dotchance/nodalarc/blob/main/adapters/frr/adapter.py"
click node_explain "https://github.com/dotchance/nodalarc/blob/main/lib/nodalarc/explain.py"
click node_terminal "https://github.com/dotchance/nodalarc/blob/main/services/vs_api/terminal.py"
click node_measurement "https://github.com/dotchance/nodalarc/blob/main/services/measurement/flow_manager.py"
click node_probe "https://github.com/dotchance/nodalarc/blob/main/services/measurement/probe_daemon.py"

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_frontend,node_wizard,node_builder,node_globe,node_topology toneBlue
class node_api,node_builder_service,node_catalog,node_session_manager toneAmber
class node_ome,node_isl,node_ground,node_snapshot,node_scheduler toneMint
class node_operator,node_node_agent,node_workloads toneRose
class node_explain,node_terminal,node_measurement,node_engineer,node_kubernetes,node_linux toneIndigo
class node_probe toneTeal
```

## Components

### Browser Lab

- [Browser App](https://github.com/dotchance/nodalarc/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Session Wizard](https://github.com/dotchance/nodalarc/blob/main/frontend/src/catalog/SessionWizard.tsx): `frontend/src/catalog/SessionWizard.tsx`
- [Session Builder](https://github.com/dotchance/nodalarc/blob/main/frontend/src/builder/BuilderView.tsx): `frontend/src/builder/BuilderView.tsx`
- [Live Globe](https://github.com/dotchance/nodalarc/blob/main/frontend/src/globe/r3f/Scene.tsx): `frontend/src/globe/r3f/Scene.tsx`
- [Topology View](https://github.com/dotchance/nodalarc/blob/main/frontend/src/topology/TopologyView.tsx): `frontend/src/topology/TopologyView.tsx`

### Session Services

- [VS API](https://github.com/dotchance/nodalarc/blob/main/services/vs_api/main.py): `services/vs_api/main.py`
- [Builder Save](https://github.com/dotchance/nodalarc/blob/main/services/vs_api/builder_session_service.py): `services/vs_api/builder_session_service.py`
- [Catalog Repository](https://github.com/dotchance/nodalarc/blob/main/lib/nodalarc/filesystem_catalog_repository.py): `lib/nodalarc/filesystem_catalog_repository.py`
- [Session Switcher](https://github.com/dotchance/nodalarc/blob/main/services/vs_api/session_manager.py): `services/vs_api/session_manager.py`

### Orbital Runtime

- [Orbital Propagation](https://github.com/dotchance/nodalarc/blob/main/services/ome/propagation_engine.py): `services/ome/propagation_engine.py`
- [ISL Feasibility](https://github.com/dotchance/nodalarc/blob/main/services/ome/isl_engine.py): `services/ome/isl_engine.py`
- [Ground Visibility](https://github.com/dotchance/nodalarc/blob/main/services/ome/ground_visibility_engine.py): `services/ome/ground_visibility_engine.py`
- [Snapshot Builder](https://github.com/dotchance/nodalarc/blob/main/services/ome/snapshot_builder.py): `services/ome/snapshot_builder.py`
- [Link Scheduler](https://github.com/dotchance/nodalarc/blob/main/services/scheduler/dispatcher.py): `services/scheduler/dispatcher.py`

### Network Substrate

- [Session Operator](https://github.com/dotchance/nodalarc/blob/main/services/nodalarc_operator/handlers.py): `services/nodalarc_operator/handlers.py`
- [Node Agent](https://github.com/dotchance/nodalarc/blob/main/services/node_agent/server.py): `services/node_agent/server.py`
- [Router Workloads](https://github.com/dotchance/nodalarc/blob/main/adapters/frr/adapter.py): `adapters/frr/adapter.py`

### Inspection & Measurement

- [Decision Explanations](https://github.com/dotchance/nodalarc/blob/main/lib/nodalarc/explain.py): `lib/nodalarc/explain.py`
- [Node Terminal](https://github.com/dotchance/nodalarc/blob/main/services/vs_api/terminal.py): `services/vs_api/terminal.py`
- [Probe Measurement](https://github.com/dotchance/nodalarc/blob/main/services/measurement/flow_manager.py): `services/measurement/flow_manager.py`

### Other components

- **Network Engineer**
- **Kubernetes**
- **Linux Network Nodes**
- [Probe Daemon](https://github.com/dotchance/nodalarc/blob/main/services/measurement/probe_daemon.py): `services/measurement/probe_daemon.py`

## Connections

- Network Engineer → Browser App: uses
- Browser App → Session Wizard: opens
- Browser App → Session Builder: opens
- Session Wizard → VS API: deploys session
- Session Builder → VS API: saves session
- VS API → Builder Save: delegates save
- Builder Save → Catalog Repository: reads and commits
- VS API → Catalog Repository: reads catalog
- VS API → Session Switcher: switches session
- Session Switcher → Kubernetes: applies session spec
- Kubernetes → Session Operator: dispatches lifecycle
- Session Operator → Kubernetes: reconciles workloads
- Session Operator → Orbital Propagation: starts runtime
- Orbital Propagation → ISL Feasibility: provides propagated states
- Orbital Propagation → Ground Visibility: provides propagated states
- Orbital Propagation → Snapshot Builder: provides runtime state
- ISL Feasibility → Link Scheduler: provides link decisions
- Ground Visibility → Link Scheduler: provides visibility
- Link Scheduler → Node Agent: dispatches link changes
- Node Agent → Linux Network Nodes: actuates networking
- Session Operator → Router Workloads: deploys workloads
- Router Workloads → Linux Network Nodes: runs in namespaces
- Browser App → Snapshot Builder: receives live state
- Browser App → Live Globe: renders
- Browser App → Topology View: renders
- Browser App → Decision Explanations: requests explanations
- Network Engineer → Node Terminal: opens node shell
- Browser App → Node Terminal: requests terminal
- Network Engineer → Probe Measurement: runs probes
- Probe Measurement → Probe Daemon: manages flows
- Probe Daemon → Linux Network Nodes: measures traffic