# mudler/edgevpn architecture

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

## Overview

EdgeVPN is a Go application and embeddable library for forming decentralized private networks over libp2p, with VPN, DNS, service tunneling, file transfer, and a shared ledger. The main workflow is: a user supplies a shared network configuration or token, starts a node, and the node discovers peers and exchanges ledger-backed state; configured services then provide VPN connectivity or other peer-to-peer features. The optional local API and React dashboard expose network status and ledger data. CLI startup wiring is sampled; feature-level links beyond those shown are limited to documented capabilities and repository structure.

Main entry points: [`cmd`](https://github.com/mudler/edgevpn/tree/master/cmd) (CLI commands), [`pkg/node/node.go`](https://github.com/mudler/edgevpn/blob/master/pkg/node/node.go) (Peer node), [`pkg/blockchain/ledger.go`](https://github.com/mudler/edgevpn/blob/master/pkg/blockchain/ledger.go) (Distributed ledger), [`api/api.go`](https://github.com/mudler/edgevpn/blob/master/api/api.go) (Local status API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and API"]
  node_binary["EdgeVPN binary<br/>[main.go]"]
  node_cli["CLI commands"]
  node_config["Network config<br/>[config.go]"]
  node_api["Local status API<br/>[api.go]"]
end

subgraph group_peer["Peer Network"]
  node_node["Peer node<br/>[node.go]"]
  node_discovery["Peer discovery"]
  node_protocol["P2P protocols<br/>[protocol.go]"]
end

subgraph group_state["Ledger and Trust"]
  node_ledger[("Distributed ledger<br/>[ledger.go]")]
  node_ledgerstore[("Ledger storage<br/>[store_disk.go]")]
  node_trust["Trust zones"]
end

subgraph group_features["Network Features"]
  node_vpn["VPN interface<br/>[vpn.go]"]
  node_dns["DNS service<br/>[dns.go]"]
  node_alive["Peer liveness<br/>[alive.go]"]
  node_egress["Egress and DHCP<br/>[egress.go]"]
  node_service["TCP service tunnel<br/>[services.go]"]
  node_files["P2P file transfer<br/>[files.go]"]
  node_proxy["Reverse proxy<br/>[proxy.go]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard["Web dashboard<br/>[router.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

node_user(("Network operator"))
node_browser(("Dashboard user"))

node_user -->|"runs"| node_binary
node_binary -->|"starts"| node_cli
node_cli -->|"loads or generates"| node_config
node_cli -->|"starts"| node_node
node_cli -->|"registers interface"| node_vpn
node_cli -->|"adds service"| node_alive
node_cli -->|"adds when enabled"| node_dns
node_cli -->|"adds when enabled"| node_egress
node_node -->|"discovers peers"| node_discovery
node_node -->|"uses protocols"| node_protocol
node_node -->|"shares network state"| node_ledger
node_ledger -->|"persists data"| node_ledgerstore
node_node -->|"applies peer gating"| node_trust
node_node -->|"configures"| node_vpn
node_node -->|"hosts service"| node_dns
node_node -->|"runs service"| node_alive
node_node -->|"runs service"| node_egress
node_ledger -->|"provides service records"| node_service
node_cli -->|"configures TCP tunnel"| node_service
node_cli -->|"dispatches file commands"| node_files
node_cli -->|"dispatches proxy command"| node_proxy
node_cli -->|"starts optionally"| node_api
node_api -->|"reads network state"| node_ledger
node_browser -->|"views status"| node_dashboard
node_dashboard -->|"requests data"| node_api_client
node_api_client -->|"calls local API"| node_api

click node_binary "https://github.com/mudler/edgevpn/blob/master/main.go"
click node_cli "https://github.com/mudler/edgevpn/tree/master/cmd"
click node_config "https://github.com/mudler/edgevpn/blob/master/pkg/config/config.go"
click node_node "https://github.com/mudler/edgevpn/blob/master/pkg/node/node.go"
click node_discovery "https://github.com/mudler/edgevpn/tree/master/pkg/discovery"
click node_protocol "https://github.com/mudler/edgevpn/blob/master/pkg/protocol/protocol.go"
click node_ledger "https://github.com/mudler/edgevpn/blob/master/pkg/blockchain/ledger.go"
click node_ledgerstore "https://github.com/mudler/edgevpn/blob/master/pkg/blockchain/store_disk.go"
click node_trust "https://github.com/mudler/edgevpn/tree/master/pkg/trustzone"
click node_vpn "https://github.com/mudler/edgevpn/blob/master/pkg/vpn/vpn.go"
click node_dns "https://github.com/mudler/edgevpn/blob/master/pkg/services/dns.go"
click node_alive "https://github.com/mudler/edgevpn/blob/master/pkg/services/alive.go"
click node_egress "https://github.com/mudler/edgevpn/blob/master/pkg/services/egress.go"
click node_service "https://github.com/mudler/edgevpn/blob/master/pkg/services/services.go"
click node_files "https://github.com/mudler/edgevpn/blob/master/pkg/services/files.go"
click node_proxy "https://github.com/mudler/edgevpn/blob/master/cmd/proxy.go"
click node_api "https://github.com/mudler/edgevpn/blob/master/api/api.go"
click node_dashboard "https://github.com/mudler/edgevpn/blob/master/api/react-ui/src/router.tsx"
click node_api_client "https://github.com/mudler/edgevpn/blob/master/api/react-ui/src/lib/api.ts"

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_binary,node_cli,node_config,node_api,node_browser toneBlue
class node_node,node_discovery,node_protocol toneAmber
class node_ledger,node_ledgerstore,node_trust toneMint
class node_vpn,node_dns,node_alive,node_egress,node_service,node_files,node_proxy toneRose
class node_dashboard,node_api_client,node_user toneIndigo
```

## Components

### CLI and API

- [EdgeVPN binary](https://github.com/mudler/edgevpn/blob/master/main.go): `main.go`
- [CLI commands](https://github.com/mudler/edgevpn/tree/master/cmd): `cmd`
- [Network config](https://github.com/mudler/edgevpn/blob/master/pkg/config/config.go): `pkg/config/config.go`
- [Local status API](https://github.com/mudler/edgevpn/blob/master/api/api.go): `api/api.go`

### Peer Network

- [Peer node](https://github.com/mudler/edgevpn/blob/master/pkg/node/node.go): `pkg/node/node.go`
- [Peer discovery](https://github.com/mudler/edgevpn/tree/master/pkg/discovery): `pkg/discovery`
- [P2P protocols](https://github.com/mudler/edgevpn/blob/master/pkg/protocol/protocol.go): `pkg/protocol/protocol.go`

### Ledger and Trust

- [Distributed ledger](https://github.com/mudler/edgevpn/blob/master/pkg/blockchain/ledger.go): `pkg/blockchain/ledger.go`
- [Ledger storage](https://github.com/mudler/edgevpn/blob/master/pkg/blockchain/store_disk.go): `pkg/blockchain/store_disk.go`
- [Trust zones](https://github.com/mudler/edgevpn/tree/master/pkg/trustzone): `pkg/trustzone`

### Network Features

- [VPN interface](https://github.com/mudler/edgevpn/blob/master/pkg/vpn/vpn.go): `pkg/vpn/vpn.go`
- [DNS service](https://github.com/mudler/edgevpn/blob/master/pkg/services/dns.go): `pkg/services/dns.go`
- [Peer liveness](https://github.com/mudler/edgevpn/blob/master/pkg/services/alive.go): `pkg/services/alive.go`
- [Egress and DHCP](https://github.com/mudler/edgevpn/blob/master/pkg/services/egress.go): `pkg/services/egress.go`
- [TCP service tunnel](https://github.com/mudler/edgevpn/blob/master/pkg/services/services.go): `pkg/services/services.go`
- [P2P file transfer](https://github.com/mudler/edgevpn/blob/master/pkg/services/files.go): `pkg/services/files.go`
- [Reverse proxy](https://github.com/mudler/edgevpn/blob/master/cmd/proxy.go): `cmd/proxy.go`

### Dashboard

- [Web dashboard](https://github.com/mudler/edgevpn/blob/master/api/react-ui/src/router.tsx): `api/react-ui/src/router.tsx`
- [API client](https://github.com/mudler/edgevpn/blob/master/api/react-ui/src/lib/api.ts): `api/react-ui/src/lib/api.ts`

### Other components

- **Network operator**
- **Dashboard user**

## Connections

- Network operator → EdgeVPN binary: runs
- EdgeVPN binary → CLI commands: starts
- CLI commands → Network config: loads or generates
- CLI commands → Peer node: starts
- CLI commands → VPN interface: registers interface
- CLI commands → Peer liveness: adds service
- CLI commands → DNS service: adds when enabled
- CLI commands → Egress and DHCP: adds when enabled
- Peer node → Peer discovery: discovers peers
- Peer node → P2P protocols: uses protocols
- Peer node → Distributed ledger: shares network state
- Distributed ledger → Ledger storage: persists data
- Peer node → Trust zones: applies peer gating
- Peer node → VPN interface: configures
- Peer node → DNS service: hosts service
- Peer node → Peer liveness: runs service
- Peer node → Egress and DHCP: runs service
- Distributed ledger → TCP service tunnel: provides service records
- CLI commands → TCP service tunnel: configures TCP tunnel
- CLI commands → P2P file transfer: dispatches file commands
- CLI commands → Reverse proxy: dispatches proxy command
- CLI commands → Local status API: starts optionally
- Local status API → Distributed ledger: reads network state
- Dashboard user → Web dashboard: views status
- Web dashboard → API client: requests data
- API client → Local status API: calls local API