# shibbityshwab/lightspeed architecture

> Architecture diagram of the GitHub repository shibbityshwab/lightspeed, 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/shibbityshwab/lightspeed
- Repository: https://github.com/shibbityshwab/lightspeed

## Overview

LightSpeed optimizes multiplayer-game UDP traffic by selecting a relay, intercepting a game’s packets, tunneling them through the relay, and forwarding them to the game server. Users start from the GUI or CLI; the GUI embeds the client engine, while the CLI provides headless and diagnostic modes. Relay discovery, route prediction, multipath recovery, and telemetry extend this core flow. The proxy also exposes control and health services. Some links reflect README-documented capabilities; sampled excerpts do not establish every internal call path.

Main entry points: [`client/src/engine.rs`](https://github.com/shibbityshwab/lightspeed/blob/master/client/src/engine.rs) (Client engine), [`proxy/src/relay.rs`](https://github.com/shibbityshwab/lightspeed/blob/master/proxy/src/relay.rs) (Relay service), [`client/src/tunnel/mod.rs`](https://github.com/shibbityshwab/lightspeed/blob/master/client/src/tunnel/mod.rs) (Client tunnel), [`client-gui/src/app.rs`](https://github.com/shibbityshwab/lightspeed/blob/master/client-gui/src/app.rs) (Desktop GUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client_ui["Client interfaces"]
  node_gui["Desktop GUI<br/>[app.rs]"]
  node_cli["Client CLI<br/>[main.rs]"]
end

subgraph group_client_runtime["Client runtime"]
  node_engine["Client engine<br/>[engine.rs]"]
  node_game_profiles["Game profiles<br/>[mod.rs]"]
  node_interceptor["Traffic interception<br/>[mod.rs]"]
  node_capture["Packet capture<br/>[mod.rs]"]
  node_routing["Route selection<br/>[mod.rs]"]
  node_ml["Route prediction<br/>[mod.rs]"]
  node_client_tunnel["Client tunnel<br/>[mod.rs]"]
  node_telemetry["Client telemetry<br/>[telemetry.rs]"]
end

subgraph group_wire_relay["Tunnel and relay"]
  node_protocol["Tunnel protocol<br/>[lib.rs]"]
  node_proxy["Relay service<br/>[relay.rs]"]
  node_proxy_auth["Relay security<br/>[auth.rs]"]
  node_proxy_control["Relay control plane<br/>[control.rs]"]
  node_health["Relay health<br/>[health.rs]"]
end

subgraph group_community_ops["Community services"]
  node_registry_client["Relay discovery<br/>[registry.rs]"]
  node_registry_worker["Signed registry<br/>[worker.js]"]
  node_registry_store[("Registry records<br/>[worker.js]")]
end

node_user(("Player or operator"))
node_game_server(("Game server"))

node_user -->|"starts or configures"| node_gui
node_user -->|"runs command"| node_cli
node_gui -->|"controls"| node_engine
node_cli -->|"starts runtime"| node_engine
node_gui -->|"requests discovery"| node_registry_client
node_registry_client -.->|"fetches signed list"| node_registry_worker
node_registry_worker -->|"reads or writes"| node_registry_store
node_registry_client -->|"supplies relay candidates"| node_routing
node_engine -->|"resolves game"| node_game_profiles
node_engine -->|"starts interception"| node_interceptor
node_interceptor -->|"captures packets"| node_capture
node_engine -->|"selects relay"| node_routing
node_routing -.->|"uses prediction"| node_ml
node_engine -->|"runs tunnel"| node_client_tunnel
node_client_tunnel -->|"encodes packets"| node_protocol
node_client_tunnel -->|"sends tunnel traffic"| node_proxy
node_proxy -->|"decodes packets"| node_protocol
node_proxy -->|"checks client"| node_proxy_auth
node_proxy -->|"forwards game packets"| node_game_server
node_game_server -->|"returns responses"| node_proxy
node_proxy -->|"returns tunneled replies"| node_client_tunnel
node_cli -->|"registers session"| node_proxy_control
node_proxy -->|"serves health checks"| node_health
node_engine -->|"flushes reports"| node_telemetry
node_telemetry -->|"sends reports"| node_proxy_control

click node_gui "https://github.com/shibbityshwab/lightspeed/blob/master/client-gui/src/app.rs"
click node_cli "https://github.com/shibbityshwab/lightspeed/blob/master/client/src/main.rs"
click node_engine "https://github.com/shibbityshwab/lightspeed/blob/master/client/src/engine.rs"
click node_game_profiles "https://github.com/shibbityshwab/lightspeed/blob/master/client/src/games/mod.rs"
click node_interceptor "https://github.com/shibbityshwab/lightspeed/blob/master/client/src/interceptor/mod.rs"
click node_capture "https://github.com/shibbityshwab/lightspeed/blob/master/client/src/capture/mod.rs"
click node_routing "https://github.com/shibbityshwab/lightspeed/blob/master/client/src/route/mod.rs"
click node_ml "https://github.com/shibbityshwab/lightspeed/blob/master/client/src/ml/mod.rs"
click node_client_tunnel "https://github.com/shibbityshwab/lightspeed/blob/master/client/src/tunnel/mod.rs"
click node_protocol "https://github.com/shibbityshwab/lightspeed/blob/master/protocol/src/lib.rs"
click node_proxy "https://github.com/shibbityshwab/lightspeed/blob/master/proxy/src/relay.rs"
click node_proxy_auth "https://github.com/shibbityshwab/lightspeed/blob/master/proxy/src/auth.rs"
click node_proxy_control "https://github.com/shibbityshwab/lightspeed/blob/master/proxy/src/control.rs"
click node_registry_client "https://github.com/shibbityshwab/lightspeed/blob/master/client/src/registry.rs"
click node_registry_worker "https://github.com/shibbityshwab/lightspeed/blob/master/infra/registry/worker.js"
click node_registry_store "https://github.com/shibbityshwab/lightspeed/blob/master/infra/registry/worker.js"
click node_telemetry "https://github.com/shibbityshwab/lightspeed/blob/master/client/src/telemetry.rs"
click node_health "https://github.com/shibbityshwab/lightspeed/blob/master/proxy/src/health.rs"

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_gui,node_cli toneBlue
class node_engine,node_game_profiles,node_interceptor,node_capture,node_routing,node_ml,node_client_tunnel,node_telemetry toneAmber
class node_protocol,node_proxy,node_proxy_auth,node_proxy_control,node_health,node_game_server toneMint
class node_registry_client,node_registry_worker,node_registry_store toneRose
class node_user toneIndigo
```

## Components

### Client interfaces

- [Desktop GUI](https://github.com/shibbityshwab/lightspeed/blob/master/client-gui/src/app.rs): `client-gui/src/app.rs`
- [Client CLI](https://github.com/shibbityshwab/lightspeed/blob/master/client/src/main.rs): `client/src/main.rs`

### Client runtime

- [Client engine](https://github.com/shibbityshwab/lightspeed/blob/master/client/src/engine.rs): `client/src/engine.rs`
- [Game profiles](https://github.com/shibbityshwab/lightspeed/blob/master/client/src/games/mod.rs): `client/src/games/mod.rs`
- [Traffic interception](https://github.com/shibbityshwab/lightspeed/blob/master/client/src/interceptor/mod.rs): `client/src/interceptor/mod.rs`
- [Packet capture](https://github.com/shibbityshwab/lightspeed/blob/master/client/src/capture/mod.rs): `client/src/capture/mod.rs`
- [Route selection](https://github.com/shibbityshwab/lightspeed/blob/master/client/src/route/mod.rs): `client/src/route/mod.rs`
- [Route prediction](https://github.com/shibbityshwab/lightspeed/blob/master/client/src/ml/mod.rs): `client/src/ml/mod.rs`
- [Client tunnel](https://github.com/shibbityshwab/lightspeed/blob/master/client/src/tunnel/mod.rs): `client/src/tunnel/mod.rs`
- [Client telemetry](https://github.com/shibbityshwab/lightspeed/blob/master/client/src/telemetry.rs): `client/src/telemetry.rs`

### Tunnel and relay

- [Tunnel protocol](https://github.com/shibbityshwab/lightspeed/blob/master/protocol/src/lib.rs): `protocol/src/lib.rs`
- [Relay service](https://github.com/shibbityshwab/lightspeed/blob/master/proxy/src/relay.rs): `proxy/src/relay.rs`
- [Relay security](https://github.com/shibbityshwab/lightspeed/blob/master/proxy/src/auth.rs): `proxy/src/auth.rs`
- [Relay control plane](https://github.com/shibbityshwab/lightspeed/blob/master/proxy/src/control.rs): `proxy/src/control.rs`
- [Relay health](https://github.com/shibbityshwab/lightspeed/blob/master/proxy/src/health.rs): `proxy/src/health.rs`

### Community services

- [Relay discovery](https://github.com/shibbityshwab/lightspeed/blob/master/client/src/registry.rs): `client/src/registry.rs`
- [Signed registry](https://github.com/shibbityshwab/lightspeed/blob/master/infra/registry/worker.js): `infra/registry/worker.js`
- [Registry records](https://github.com/shibbityshwab/lightspeed/blob/master/infra/registry/worker.js): `infra/registry/worker.js`

### Other components

- **Player or operator**
- **Game server**

## Connections

- Player or operator → Desktop GUI: starts or configures
- Player or operator → Client CLI: runs command
- Desktop GUI → Client engine: controls
- Client CLI → Client engine: starts runtime
- Desktop GUI → Relay discovery: requests discovery
- Relay discovery → Signed registry: fetches signed list
- Signed registry → Registry records: reads or writes
- Relay discovery → Route selection: supplies relay candidates
- Client engine → Game profiles: resolves game
- Client engine → Traffic interception: starts interception
- Traffic interception → Packet capture: captures packets
- Client engine → Route selection: selects relay
- Route selection → Route prediction: uses prediction
- Client engine → Client tunnel: runs tunnel
- Client tunnel → Tunnel protocol: encodes packets
- Client tunnel → Relay service: sends tunnel traffic
- Relay service → Tunnel protocol: decodes packets
- Relay service → Relay security: checks client
- Relay service → Game server: forwards game packets
- Game server → Relay service: returns responses
- Relay service → Client tunnel: returns tunneled replies
- Client CLI → Relay control plane: registers session
- Relay service → Relay health: serves health checks
- Client engine → Client telemetry: flushes reports
- Client telemetry → Relay control plane: sends reports