# yggdrasil-network/yggdrasil-go architecture

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

- Interactive diagram: https://gitdiagram.com/yggdrasil-network/yggdrasil-go
- Repository: https://github.com/yggdrasil-network/yggdrasil-go

## Overview

Yggdrasil is an end-to-end encrypted IPv6 overlay network. The primary workflow configures a node, establishes peer links, routes IPv6 packets, and exposes them to applications through a TUN interface or the mobile packet API. The graph also preserves peer discovery, administration, and key-generation capabilities. Some startup wiring is only partially excerpted; those relationships are marked dashed with no evidence path rather than inferred as confirmed calls.

Main entry points: [`src/core/core.go`](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/core/core.go) (Overlay core), [`cmd/yggdrasil/main.go`](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/cmd/yggdrasil/main.go) (Node daemon), [`contrib/mobile/mobile.go`](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/contrib/mobile/mobile.go) (Mobile API), [`src/multicast/multicast.go`](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/multicast/multicast.go) (Peer discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["User entrypoints"]
  node_daemon["Node daemon<br/>[main.go]"]
  node_mobile["Mobile API<br/>[mobile.go]"]
  node_controlcli["Admin CLI<br/>[main.go]"]
end

subgraph group_network["Overlay networking"]
  node_core["Overlay core<br/>[core.go]"]
  node_routing["Packet routing<br/>[proto.go]"]
  node_links["Peer links<br/>[link.go]"]
  node_multicast["Peer discovery<br/>[multicast.go]"]
end

subgraph group_interfaces["Packet interfaces"]
  node_ipv6["IPv6 packet bridge<br/>[ipv6rwc.go]"]
  node_tun["TUN adapter<br/>[tun.go]"]
end

subgraph group_operations["Operations and identity"]
  node_config["Configuration<br/>[config.go]"]
  node_address["Address derivation<br/>[address.go]"]
  node_admin["Admin socket<br/>[admin.go]"]
  node_keygen["Key generator<br/>[main.go]"]
  node_bruteforce["Key search utility"]
end

node_operator(("Node operator"))
node_app(("IPv6 applications"))
node_peer(("Remote Yggdrasil peers"))
node_osnet(("Host network interfaces"))

node_operator -->|"starts or configures"| node_daemon
node_operator -->|"requests status"| node_controlcli
node_daemon -.->|"loads configuration"| node_config
node_daemon -.->|"starts node"| node_core
node_daemon -.->|"starts discovery"| node_multicast
node_daemon -.->|"sets up interface"| node_tun
node_mobile -->|"generates config"| node_config
node_mobile -->|"starts node"| node_core
node_mobile -->|"starts discovery"| node_multicast
node_mobile -->|"sends and receives"| node_ipv6
node_core -->|"derives addresses"| node_address
node_core -.->|"manages peer links"| node_links
node_core -.->|"routes packets"| node_routing
node_links -.->|"exchanges encrypted traffic"| node_peer
node_multicast -->|"uses node identity"| node_core
node_multicast -->|"discovers interfaces"| node_osnet
node_ipv6 -->|"writes packets"| node_core
node_tun -.->|"bridges packets"| node_ipv6
node_app -->|"sends and receives IPv6"| node_tun
node_controlcli -->|"sends JSON requests"| node_admin
node_admin -->|"queries node state"| node_core
node_keygen -->|"derives candidate address"| node_address
node_bruteforce -->|"prints candidate keys"| node_operator

click node_daemon "https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/cmd/yggdrasil/main.go"
click node_mobile "https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/contrib/mobile/mobile.go"
click node_controlcli "https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/cmd/yggdrasilctl/main.go"
click node_config "https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/config/config.go"
click node_address "https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/address/address.go"
click node_core "https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/core/core.go"
click node_routing "https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/core/proto.go"
click node_links "https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/core/link.go"
click node_multicast "https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/multicast/multicast.go"
click node_ipv6 "https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/ipv6rwc/ipv6rwc.go"
click node_tun "https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/tun/tun.go"
click node_admin "https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/admin/admin.go"
click node_keygen "https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/cmd/genkeys/main.go"
click node_bruteforce "https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/contrib/yggdrasil-brute-simple/yggdrasil-brute-multi-ed25519.c"

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_daemon,node_mobile,node_controlcli toneBlue
class node_core,node_routing,node_links,node_multicast toneAmber
class node_ipv6,node_tun toneMint
class node_config,node_address,node_admin,node_keygen,node_bruteforce toneRose
class node_operator,node_app,node_peer,node_osnet toneIndigo
```

## Components

### User entrypoints

- [Node daemon](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/cmd/yggdrasil/main.go): `cmd/yggdrasil/main.go`
- [Mobile API](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/contrib/mobile/mobile.go): `contrib/mobile/mobile.go`
- [Admin CLI](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/cmd/yggdrasilctl/main.go): `cmd/yggdrasilctl/main.go`

### Overlay networking

- [Overlay core](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/core/core.go): `src/core/core.go`
- [Packet routing](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/core/proto.go): `src/core/proto.go`
- [Peer links](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/core/link.go): `src/core/link.go`
- [Peer discovery](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/multicast/multicast.go): `src/multicast/multicast.go`

### Packet interfaces

- [IPv6 packet bridge](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/ipv6rwc/ipv6rwc.go): `src/ipv6rwc/ipv6rwc.go`
- [TUN adapter](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/tun/tun.go): `src/tun/tun.go`

### Operations and identity

- [Configuration](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/config/config.go): `src/config/config.go`
- [Address derivation](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/address/address.go): `src/address/address.go`
- [Admin socket](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/src/admin/admin.go): `src/admin/admin.go`
- [Key generator](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/cmd/genkeys/main.go): `cmd/genkeys/main.go`
- [Key search utility](https://github.com/yggdrasil-network/yggdrasil-go/blob/develop/contrib/yggdrasil-brute-simple/yggdrasil-brute-multi-ed25519.c): `contrib/yggdrasil-brute-simple/yggdrasil-brute-multi-ed25519.c`

### Other components

- **Node operator**
- **IPv6 applications**
- **Remote Yggdrasil peers**
- **Host network interfaces**

## Connections

- Node operator → Node daemon: starts or configures (evidence: `README.md`)
- Node operator → Admin CLI: requests status (evidence: `cmd/yggdrasilctl/main.go`)
- Node daemon → Configuration: loads configuration
- Node daemon → Overlay core: starts node
- Node daemon → Peer discovery: starts discovery
- Node daemon → TUN adapter: sets up interface
- Mobile API → Configuration: generates config (evidence: `contrib/mobile/mobile.go`)
- Mobile API → Overlay core: starts node (evidence: `contrib/mobile/mobile.go`)
- Mobile API → Peer discovery: starts discovery (evidence: `contrib/mobile/mobile.go`)
- Mobile API → IPv6 packet bridge: sends and receives (evidence: `contrib/mobile/mobile.go`)
- Overlay core → Address derivation: derives addresses (evidence: `src/core/core.go`)
- Overlay core → Peer links: manages peer links
- Overlay core → Packet routing: routes packets
- Peer links → Remote Yggdrasil peers: exchanges encrypted traffic
- Peer discovery → Overlay core: uses node identity (evidence: `src/multicast/multicast.go`)
- Peer discovery → Host network interfaces: discovers interfaces (evidence: `src/multicast/multicast.go`)
- IPv6 packet bridge → Overlay core: writes packets (evidence: `src/ipv6rwc/ipv6rwc.go`)
- TUN adapter → IPv6 packet bridge: bridges packets
- IPv6 applications → TUN adapter: sends and receives IPv6 (evidence: `README.md`)
- Admin CLI → Admin socket: sends JSON requests (evidence: `cmd/yggdrasilctl/main.go`)
- Admin socket → Overlay core: queries node state
- Key generator → Address derivation: derives candidate address (evidence: `cmd/genkeys/main.go`)
- Key search utility → Node operator: prints candidate keys (evidence: `contrib/yggdrasil-brute-simple/yggdrasil-brute-multi-ed25519.c`)
