# endgameddos/endgame-v3 architecture

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

- Interactive diagram: https://gitdiagram.com/endgameddos/endgame-v3
- Repository: https://github.com/endgameddos/endgame-v3

## Overview

EndGame V3 is documented as a self-hosted traffic shield, but its NGINX/Lua filtering and proxy implementation is not present in this file tree. The available runtime components are a Rust captcha and Go/Rust GoBalance implementations; the Rust modules provide the clearest evidenced descriptor-publication workflow. GoBalance fetches backend-instance descriptors and publishes frontend descriptors through Tor. Edges reflect shown calls or source-index references; README-only product capabilities are noted without inventing missing implementation nodes.

Main entry points: [`sourcecode/rsbalance/src/onionbalance/service.rs`](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/service.rs) (Frontend Service), [`sourcecode/rsbalance/src/onionbalance/manager.rs`](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/manager.rs) (Event Manager), [`sourcecode/rsbalance/src/onionbalance/onionbalance.rs`](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/onionbalance.rs) (Balance Coordinator), [`sourcecode/rsbalance/src/onionbalance/descriptor.rs`](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/descriptor.rs) (Descriptor Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_captcha["Captcha"]
  node_captcha_runtime["Captcha Runtime<br/>[main.rs]"]
end

subgraph group_gobalance["GoBalance Go"]
  node_go_entry["GoBalance Entry<br/>[main.go]"]
  node_go_balance["GoBalance Engine"]
end

subgraph group_rust_core["GoBalance Rust Core"]
  node_rust_entry["Rust Entry<br/>[main.rs]"]
  node_manager["Event Manager<br/>[manager.rs]"]
  node_onionbalance["Balance Coordinator<br/>[onionbalance.rs]"]
  node_service["Frontend Service<br/>[service.rs]"]
  node_instance["Backend Instances<br/>[instance.rs]"]
  node_config["Service Config<br/>[config.rs]"]
  node_parameters["Timing Parameters<br/>[param.rs]"]
end

subgraph group_rust_protocol["Tor Protocol"]
  node_controller["Tor Controller<br/>[controller.rs]"]
  node_consensus["Network Consensus<br/>[consensus.rs]"]
  node_hashring["HSDir Hashring<br/>[hashring.rs]"]
  node_tor_node["Tor Relay Node<br/>[tor_node.rs]"]
  node_descriptor["Descriptor Builder<br/>[descriptor.rs]"]
  node_hs_descriptor["HS Descriptor Codec<br/>[hidden_service.rs]"]
  node_certificate["Descriptor Certificates<br/>[certificate.rs]"]
  node_key_ops["Ed25519 Key Ops"]
  node_slow_ed["Ed25519 Reference<br/>[slow_ed25519.rs]"]
  node_key_wrapper["Private Key Wrapper<br/>[mod.rs]"]
  node_stem_util["Ed25519 Utilities<br/>[mod.rs]"]
end

node_tor_network(("Tor Network"))
node_endgame_users(("EndGame Users"))
node_origin(("Origin Service"))

node_endgame_users -.->|"requests challenge"| node_captcha_runtime
node_endgame_users -.->|"clean traffic reaches"| node_origin
node_rust_entry -->|"starts"| node_manager
node_manager -->|"initializes"| node_onionbalance
node_manager -->|"handles reconnects"| node_controller
node_manager -->|"registers fetched descriptors"| node_instance
node_manager -->|"schedules fetches"| node_parameters
node_onionbalance -->|"coordinates"| node_service
node_onionbalance -->|"uses"| node_consensus
node_onionbalance -->|"tracks"| node_instance
node_service -->|"derives publication parameters"| node_consensus
node_service -->|"builds descriptors"| node_descriptor
node_service -->|"uploads descriptors"| node_controller
node_service -->|"selects HSDirs"| node_hashring
node_service -->|"reads service settings"| node_config
node_consensus -->|"obtains relay data"| node_controller
node_consensus -->|"constructs relay nodes"| node_tor_node
node_descriptor -->|"encodes and parses"| node_hs_descriptor
node_descriptor -->|"uses certificates"| node_certificate
node_descriptor -->|"checks size limits"| node_parameters
node_hs_descriptor -->|"parses certificates"| node_certificate
node_hs_descriptor -->|"uses crypto utilities"| node_stem_util
node_key_wrapper -->|"derives public keys"| node_key_ops
node_key_ops -->|"delegates arithmetic"| node_slow_ed
node_service -.->|"publishes descriptors"| node_tor_network
node_go_entry -.->|"runs balancing service"| node_go_balance

click node_captcha_runtime "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/captcha-source/src/main.rs"
click node_go_entry "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/gobalance/main.go"
click node_go_balance "https://github.com/endgameddos/endgame-v3/tree/main/sourcecode/gobalance/pkg/onionbalance"
click node_rust_entry "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/main.rs"
click node_manager "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/manager.rs"
click node_onionbalance "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/onionbalance.rs"
click node_service "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/service.rs"
click node_instance "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/instance.rs"
click node_config "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/config.rs"
click node_parameters "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/param.rs"
click node_controller "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/controller.rs"
click node_consensus "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/consensus.rs"
click node_hashring "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/hashring.rs"
click node_tor_node "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/tor_node.rs"
click node_descriptor "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/descriptor.rs"
click node_hs_descriptor "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/stem/descriptor/hidden_service.rs"
click node_certificate "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/stem/descriptor/certificate.rs"
click node_key_ops "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/hs_v3/ext/ed_25519_exts_ref.rs"
click node_slow_ed "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/hs_v3/ext/slow_ed25519.rs"
click node_key_wrapper "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/rsbpk/mod.rs"
click node_stem_util "https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/stem/util/mod.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_captcha_runtime,node_endgame_users toneBlue
class node_go_entry,node_go_balance toneAmber
class node_rust_entry,node_manager,node_onionbalance,node_service,node_instance,node_config,node_parameters toneMint
class node_controller,node_consensus,node_hashring,node_tor_node,node_descriptor,node_hs_descriptor,node_certificate,node_key_ops,node_slow_ed,node_key_wrapper,node_stem_util toneRose
class node_tor_network,node_origin toneIndigo
```

## Components

### Captcha

- [Captcha Runtime](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/captcha-source/src/main.rs): `sourcecode/captcha-source/src/main.rs`

### GoBalance Go

- [GoBalance Entry](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/gobalance/main.go): `sourcecode/gobalance/main.go`
- [GoBalance Engine](https://github.com/endgameddos/endgame-v3/tree/main/sourcecode/gobalance/pkg/onionbalance): `sourcecode/gobalance/pkg/onionbalance`

### GoBalance Rust Core

- [Rust Entry](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/main.rs): `sourcecode/rsbalance/src/main.rs`
- [Event Manager](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/manager.rs): `sourcecode/rsbalance/src/onionbalance/manager.rs`
- [Balance Coordinator](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/onionbalance.rs): `sourcecode/rsbalance/src/onionbalance/onionbalance.rs`
- [Frontend Service](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/service.rs): `sourcecode/rsbalance/src/onionbalance/service.rs`
- [Backend Instances](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/instance.rs): `sourcecode/rsbalance/src/onionbalance/instance.rs`
- [Service Config](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/config.rs): `sourcecode/rsbalance/src/onionbalance/config.rs`
- [Timing Parameters](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/param.rs): `sourcecode/rsbalance/src/onionbalance/param.rs`

### Tor Protocol

- [Tor Controller](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/controller.rs): `sourcecode/rsbalance/src/onionbalance/controller.rs`
- [Network Consensus](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/consensus.rs): `sourcecode/rsbalance/src/onionbalance/consensus.rs`
- [HSDir Hashring](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/hashring.rs): `sourcecode/rsbalance/src/onionbalance/hashring.rs`
- [Tor Relay Node](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/tor_node.rs): `sourcecode/rsbalance/src/onionbalance/tor_node.rs`
- [Descriptor Builder](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/descriptor.rs): `sourcecode/rsbalance/src/onionbalance/descriptor.rs`
- [HS Descriptor Codec](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/stem/descriptor/hidden_service.rs): `sourcecode/rsbalance/src/stem/descriptor/hidden_service.rs`
- [Descriptor Certificates](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/stem/descriptor/certificate.rs): `sourcecode/rsbalance/src/stem/descriptor/certificate.rs`
- [Ed25519 Key Ops](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/hs_v3/ext/ed_25519_exts_ref.rs): `sourcecode/rsbalance/src/onionbalance/hs_v3/ext/ed_25519_exts_ref.rs`
- [Ed25519 Reference](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/onionbalance/hs_v3/ext/slow_ed25519.rs): `sourcecode/rsbalance/src/onionbalance/hs_v3/ext/slow_ed25519.rs`
- [Private Key Wrapper](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/rsbpk/mod.rs): `sourcecode/rsbalance/src/rsbpk/mod.rs`
- [Ed25519 Utilities](https://github.com/endgameddos/endgame-v3/blob/main/sourcecode/rsbalance/src/stem/util/mod.rs): `sourcecode/rsbalance/src/stem/util/mod.rs`

### Other components

- **Tor Network**
- **EndGame Users**
- **Origin Service**

## Connections

- EndGame Users → Captcha Runtime: requests challenge
- EndGame Users → Origin Service: clean traffic reaches
- Rust Entry → Event Manager: starts (evidence: `sourcecode/rsbalance/src/main.rs`)
- Event Manager → Balance Coordinator: initializes (evidence: `sourcecode/rsbalance/src/onionbalance/manager.rs`)
- Event Manager → Tor Controller: handles reconnects (evidence: `sourcecode/rsbalance/src/onionbalance/manager.rs`)
- Event Manager → Backend Instances: registers fetched descriptors (evidence: `sourcecode/rsbalance/src/onionbalance/manager.rs`)
- Event Manager → Timing Parameters: schedules fetches (evidence: `sourcecode/rsbalance/src/onionbalance/manager.rs`)
- Balance Coordinator → Frontend Service: coordinates (evidence: `sourcecode/rsbalance/src/onionbalance/onionbalance.rs`)
- Balance Coordinator → Network Consensus: uses (evidence: `sourcecode/rsbalance/src/onionbalance/onionbalance.rs`)
- Balance Coordinator → Backend Instances: tracks (evidence: `sourcecode/rsbalance/src/onionbalance/onionbalance.rs`)
- Frontend Service → Network Consensus: derives publication parameters (evidence: `sourcecode/rsbalance/src/onionbalance/service.rs`)
- Frontend Service → Descriptor Builder: builds descriptors (evidence: `sourcecode/rsbalance/src/onionbalance/service.rs`)
- Frontend Service → Tor Controller: uploads descriptors (evidence: `sourcecode/rsbalance/src/onionbalance/service.rs`)
- Frontend Service → HSDir Hashring: selects HSDirs (evidence: `sourcecode/rsbalance/src/onionbalance/service.rs`)
- Frontend Service → Service Config: reads service settings (evidence: `sourcecode/rsbalance/src/onionbalance/service.rs`)
- Network Consensus → Tor Controller: obtains relay data (evidence: `sourcecode/rsbalance/src/onionbalance/consensus.rs`)
- Network Consensus → Tor Relay Node: constructs relay nodes (evidence: `sourcecode/rsbalance/src/onionbalance/consensus.rs`)
- Descriptor Builder → HS Descriptor Codec: encodes and parses (evidence: `sourcecode/rsbalance/src/onionbalance/descriptor.rs`)
- Descriptor Builder → Descriptor Certificates: uses certificates (evidence: `sourcecode/rsbalance/src/onionbalance/descriptor.rs`)
- Descriptor Builder → Timing Parameters: checks size limits (evidence: `sourcecode/rsbalance/src/onionbalance/descriptor.rs`)
- HS Descriptor Codec → Descriptor Certificates: parses certificates (evidence: `sourcecode/rsbalance/src/stem/descriptor/hidden_service.rs`)
- HS Descriptor Codec → Ed25519 Utilities: uses crypto utilities (evidence: `sourcecode/rsbalance/src/stem/descriptor/hidden_service.rs`)
- Private Key Wrapper → Ed25519 Key Ops: derives public keys (evidence: `sourcecode/rsbalance/src/rsbpk/mod.rs`)
- Ed25519 Key Ops → Ed25519 Reference: delegates arithmetic (evidence: `sourcecode/rsbalance/src/onionbalance/hs_v3/ext/ed_25519_exts_ref.rs`)
- Frontend Service → Tor Network: publishes descriptors
- GoBalance Entry → GoBalance Engine: runs balancing service