# soyunomas/taltun architecture

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

- Interactive diagram: https://gitdiagram.com/soyunomas/taltun
- Repository: https://github.com/soyunomas/taltun

## Overview

Taltun is an encrypted VPN engine with both a Go/Linux runtime and an Android client. The main workflow is to configure peer identities and routes, establish authenticated sessions, then encrypt and route IPv4 traffic through the tunnel or a user-space relay. The README also documents Lighthouse endpoint discovery, direct P2P promotion and relay fallback. The Android service excerpts show its tunnel and UDP processing; Go excerpts show engine setup and dataplane work. Some Go subsystem links rely on the SOURCE INDEX or README rather than sampled call sites.

Main entry points: [`internal/engine/engine.go`](https://github.com/soyunomas/taltun/blob/main/internal/engine/engine.go) (VPN engine), [`android/app/src/main/java/com/soyunomas/taltun/android/MainActivity.kt`](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/MainActivity.kt) (VPN controls), [`android/app/src/main/java/com/soyunomas/taltun/android/TaltunVpnService.kt`](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/TaltunVpnService.kt) (VPN service), [`android/app/src/main/java/com/soyunomas/taltun/android/config/TaltunConfig.kt`](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/config/TaltunConfig.kt) (Profile validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android client"]
  node_main["VPN controls<br/>[MainActivity.kt]"]
  node_editor["Profile editor"]
  node_store[("Profile storage<br/>[ConfigStore.kt]")]
  node_androidconfig["Profile validation<br/>[TaltunConfig.kt]"]
  node_service["VPN service"]
  node_runtime_state["Connection status<br/>[VpnRuntimeState.kt]"]
end

subgraph group_runtime["Go runtime"]
  node_cmd["VPN entry point<br/>[main.go]"]
  node_config["Runtime configuration<br/>[config.go]"]
  node_engine["VPN engine<br/>[engine.go]"]
end

subgraph group_security["Identity and sessions"]
  node_android_session["Android sessions<br/>[TaltunSession.kt]"]
  node_android_crypto["Android cryptography<br/>[TaltunCrypto.kt]"]
  node_android_protocol["Android wire protocol<br/>[TaltunProtocol.kt]"]
  node_hex["Key encoding<br/>[Hex.kt]"]
  node_replay["Android replay window<br/>[ReplayWindow.kt]"]
  node_handshake["Handshake v2<br/>[handshake_v2.go]"]
  node_control["Control messages<br/>[control_v2.go]"]
  node_peer["Peer sessions<br/>[peer.go]"]
  node_crypto["Key and AEAD<br/>[keypair.go]"]
  node_cookie["Cookie protection<br/>[protector.go]"]
  node_protocol["Wire protocol<br/>[handshake.go]"]
  node_replay_filter["Replay filtering<br/>[filter.go]"]
  node_keygen["Key generation<br/>[main.go]"]
end

subgraph group_network["Routing and transport"]
  node_ipv4["IPv4 utilities<br/>[Ipv4.kt]"]
  node_router["Peer route lookup<br/>[trie.go]"]
  node_netutil["Network utilities<br/>[interface_linux.go]"]
  node_buffers["Packet buffers<br/>[buffer.go]"]
end

node_user(("VPN user"))
node_vpn_user(("VPN command"))
node_tunnel["TUN interface"]
node_peers(("Remote VPN peers"))

node_user -->|"manages VPN"| node_main
node_main -->|"opens editor"| node_editor
node_main -->|"loads profiles"| node_store
node_editor -->|"saves profiles"| node_store
node_editor -->|"validates profile"| node_androidconfig
node_main -->|"starts or stops"| node_service
node_main -->|"reads status"| node_runtime_state
node_service -->|"loads profile"| node_store
node_service -->|"handles sessions"| node_android_session
node_service -->|"parses packets"| node_android_protocol
node_service -->|"updates counters"| node_runtime_state
node_androidconfig -->|"decodes keys"| node_hex
node_androidconfig -->|"validates addresses"| node_ipv4
node_androidconfig -->|"checks key size"| node_android_crypto
node_android_session -->|"derives session keys"| node_android_crypto
node_android_session -->|"handles messages"| node_android_protocol
node_android_session -->|"checks replay"| node_replay
node_vpn_user -->|"runs VPN"| node_cmd
node_cmd -->|"loads settings"| node_config
node_cmd -->|"creates and runs"| node_engine
node_cmd -->|"configures peers"| node_peer
node_engine -->|"uses settings"| node_config
node_engine -->|"manages peers"| node_peer
node_engine -->|"routes packets"| node_router
node_engine -->|"protects handshakes"| node_cookie
node_engine -->|"uses key operations"| node_crypto
node_engine -->|"sets up networking"| node_netutil
node_engine -->|"gets packet buffers"| node_buffers
node_engine -->|"encodes packets"| node_protocol
node_engine -->|"creates TUN"| node_tunnel
node_tunnel -.->|"supplies packets"| node_engine
node_engine -.->|"exchanges encrypted UDP"| node_peers
node_handshake -->|"derives keys"| node_crypto
node_handshake -->|"uses handshake format"| node_protocol
node_control -->|"uses control format"| node_protocol
node_peer -->|"installs sessions"| node_crypto
node_peer -->|"checks replay"| node_replay_filter
node_engine -.->|"dispatches handshakes"| node_handshake
node_engine -.->|"handles peer updates"| node_control
node_keygen -->|"generates keys"| node_crypto
node_engine -.->|"relays and discovers routes"| node_peers

click node_main "https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/MainActivity.kt"
click node_editor "https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/ProfileEditorActivity.kt"
click node_store "https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/config/ConfigStore.kt"
click node_androidconfig "https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/config/TaltunConfig.kt"
click node_service "https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/TaltunVpnService.kt"
click node_runtime_state "https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/VpnRuntimeState.kt"
click node_android_session "https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/core/TaltunSession.kt"
click node_android_crypto "https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/core/TaltunCrypto.kt"
click node_android_protocol "https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/core/TaltunProtocol.kt"
click node_hex "https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/core/Hex.kt"
click node_ipv4 "https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/core/Ipv4.kt"
click node_replay "https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/core/ReplayWindow.kt"
click node_cmd "https://github.com/soyunomas/taltun/blob/main/cmd/vpn/main.go"
click node_config "https://github.com/soyunomas/taltun/blob/main/internal/config/config.go"
click node_engine "https://github.com/soyunomas/taltun/blob/main/internal/engine/engine.go"
click node_handshake "https://github.com/soyunomas/taltun/blob/main/internal/engine/handshake_v2.go"
click node_control "https://github.com/soyunomas/taltun/blob/main/internal/engine/control_v2.go"
click node_peer "https://github.com/soyunomas/taltun/blob/main/internal/session/peer.go"
click node_crypto "https://github.com/soyunomas/taltun/blob/main/pkg/crypto/keypair.go"
click node_cookie "https://github.com/soyunomas/taltun/blob/main/pkg/cookie/protector.go"
click node_protocol "https://github.com/soyunomas/taltun/blob/main/pkg/protocol/handshake.go"
click node_replay_filter "https://github.com/soyunomas/taltun/blob/main/pkg/replay/filter.go"
click node_router "https://github.com/soyunomas/taltun/blob/main/pkg/router/trie.go"
click node_netutil "https://github.com/soyunomas/taltun/blob/main/pkg/netutil/interface_linux.go"
click node_buffers "https://github.com/soyunomas/taltun/blob/main/pkg/pool/buffer.go"
click node_keygen "https://github.com/soyunomas/taltun/blob/main/cmd/keygen/main.go"

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_main,node_editor,node_store,node_androidconfig,node_service,node_runtime_state,node_user toneBlue
class node_cmd,node_config,node_engine toneAmber
class node_android_session,node_android_crypto,node_android_protocol,node_hex,node_replay,node_handshake,node_control,node_peer,node_crypto,node_cookie,node_protocol,node_replay_filter,node_keygen toneMint
class node_ipv4,node_router,node_netutil,node_buffers toneRose
class node_vpn_user,node_tunnel,node_peers toneIndigo
```

## Components

### Android client

- [VPN controls](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/MainActivity.kt): `android/app/src/main/java/com/soyunomas/taltun/android/MainActivity.kt`
- [Profile editor](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/ProfileEditorActivity.kt): `android/app/src/main/java/com/soyunomas/taltun/android/ProfileEditorActivity.kt`
- [Profile storage](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/config/ConfigStore.kt): `android/app/src/main/java/com/soyunomas/taltun/android/config/ConfigStore.kt`
- [Profile validation](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/config/TaltunConfig.kt): `android/app/src/main/java/com/soyunomas/taltun/android/config/TaltunConfig.kt`
- [VPN service](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/TaltunVpnService.kt): `android/app/src/main/java/com/soyunomas/taltun/android/TaltunVpnService.kt`
- [Connection status](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/VpnRuntimeState.kt): `android/app/src/main/java/com/soyunomas/taltun/android/VpnRuntimeState.kt`

### Go runtime

- [VPN entry point](https://github.com/soyunomas/taltun/blob/main/cmd/vpn/main.go): `cmd/vpn/main.go`
- [Runtime configuration](https://github.com/soyunomas/taltun/blob/main/internal/config/config.go): `internal/config/config.go`
- [VPN engine](https://github.com/soyunomas/taltun/blob/main/internal/engine/engine.go): `internal/engine/engine.go`

### Identity and sessions

- [Android sessions](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/core/TaltunSession.kt): `android/app/src/main/java/com/soyunomas/taltun/android/core/TaltunSession.kt`
- [Android cryptography](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/core/TaltunCrypto.kt): `android/app/src/main/java/com/soyunomas/taltun/android/core/TaltunCrypto.kt`
- [Android wire protocol](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/core/TaltunProtocol.kt): `android/app/src/main/java/com/soyunomas/taltun/android/core/TaltunProtocol.kt`
- [Key encoding](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/core/Hex.kt): `android/app/src/main/java/com/soyunomas/taltun/android/core/Hex.kt`
- [Android replay window](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/core/ReplayWindow.kt): `android/app/src/main/java/com/soyunomas/taltun/android/core/ReplayWindow.kt`
- [Handshake v2](https://github.com/soyunomas/taltun/blob/main/internal/engine/handshake_v2.go): `internal/engine/handshake_v2.go`
- [Control messages](https://github.com/soyunomas/taltun/blob/main/internal/engine/control_v2.go): `internal/engine/control_v2.go`
- [Peer sessions](https://github.com/soyunomas/taltun/blob/main/internal/session/peer.go): `internal/session/peer.go`
- [Key and AEAD](https://github.com/soyunomas/taltun/blob/main/pkg/crypto/keypair.go): `pkg/crypto/keypair.go`
- [Cookie protection](https://github.com/soyunomas/taltun/blob/main/pkg/cookie/protector.go): `pkg/cookie/protector.go`
- [Wire protocol](https://github.com/soyunomas/taltun/blob/main/pkg/protocol/handshake.go): `pkg/protocol/handshake.go`
- [Replay filtering](https://github.com/soyunomas/taltun/blob/main/pkg/replay/filter.go): `pkg/replay/filter.go`
- [Key generation](https://github.com/soyunomas/taltun/blob/main/cmd/keygen/main.go): `cmd/keygen/main.go`

### Routing and transport

- [IPv4 utilities](https://github.com/soyunomas/taltun/blob/main/android/app/src/main/java/com/soyunomas/taltun/android/core/Ipv4.kt): `android/app/src/main/java/com/soyunomas/taltun/android/core/Ipv4.kt`
- [Peer route lookup](https://github.com/soyunomas/taltun/blob/main/pkg/router/trie.go): `pkg/router/trie.go`
- [Network utilities](https://github.com/soyunomas/taltun/blob/main/pkg/netutil/interface_linux.go): `pkg/netutil/interface_linux.go`
- [Packet buffers](https://github.com/soyunomas/taltun/blob/main/pkg/pool/buffer.go): `pkg/pool/buffer.go`

### Other components

- **VPN user**
- **VPN command**
- **TUN interface**
- **Remote VPN peers**

## Connections

- VPN user → VPN controls: manages VPN (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/MainActivity.kt`)
- VPN controls → Profile editor: opens editor (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/MainActivity.kt`)
- VPN controls → Profile storage: loads profiles (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/MainActivity.kt`)
- Profile editor → Profile storage: saves profiles (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/ProfileEditorActivity.kt`)
- Profile editor → Profile validation: validates profile (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/ProfileEditorActivity.kt`)
- VPN controls → VPN service: starts or stops (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/MainActivity.kt`)
- VPN controls → Connection status: reads status (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/MainActivity.kt`)
- VPN service → Profile storage: loads profile (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/TaltunVpnService.kt`)
- VPN service → Android sessions: handles sessions (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/TaltunVpnService.kt`)
- VPN service → Android wire protocol: parses packets (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/TaltunVpnService.kt`)
- VPN service → Connection status: updates counters (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/TaltunVpnService.kt`)
- Profile validation → Key encoding: decodes keys (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/config/TaltunConfig.kt`)
- Profile validation → IPv4 utilities: validates addresses (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/config/TaltunConfig.kt`)
- Profile validation → Android cryptography: checks key size (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/config/TaltunConfig.kt`)
- Android sessions → Android cryptography: derives session keys (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/core/TaltunSession.kt`)
- Android sessions → Android wire protocol: handles messages (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/core/TaltunSession.kt`)
- Android sessions → Android replay window: checks replay (evidence: `android/app/src/main/java/com/soyunomas/taltun/android/core/TaltunSession.kt`)
- VPN command → VPN entry point: runs VPN (evidence: `cmd/vpn/main.go`)
- VPN entry point → Runtime configuration: loads settings (evidence: `cmd/vpn/main.go`)
- VPN entry point → VPN engine: creates and runs (evidence: `cmd/vpn/main.go`)
- VPN entry point → Peer sessions: configures peers (evidence: `cmd/vpn/main.go`)
- VPN engine → Runtime configuration: uses settings (evidence: `internal/engine/engine.go`)
- VPN engine → Peer sessions: manages peers (evidence: `internal/engine/engine.go`)
- VPN engine → Peer route lookup: routes packets (evidence: `internal/engine/engine.go`)
- VPN engine → Cookie protection: protects handshakes (evidence: `internal/engine/engine.go`)
- VPN engine → Key and AEAD: uses key operations (evidence: `internal/engine/engine.go`)
- VPN engine → Network utilities: sets up networking (evidence: `internal/engine/engine.go`)
- VPN engine → Packet buffers: gets packet buffers (evidence: `internal/engine/engine.go`)
- VPN engine → Wire protocol: encodes packets (evidence: `internal/engine/engine.go`)
- VPN engine → TUN interface: creates TUN (evidence: `internal/engine/engine.go`)
- TUN interface → VPN engine: supplies packets (evidence: `README.md`)
- VPN engine → Remote VPN peers: exchanges encrypted UDP (evidence: `README.md`)
- Handshake v2 → Key and AEAD: derives keys (evidence: `internal/engine/handshake_v2.go`)
- Handshake v2 → Wire protocol: uses handshake format (evidence: `internal/engine/handshake_v2.go`)
- Control messages → Wire protocol: uses control format (evidence: `internal/engine/control_v2.go`)
- Peer sessions → Key and AEAD: installs sessions (evidence: `internal/session/peer.go`)
- Peer sessions → Replay filtering: checks replay (evidence: `internal/session/peer.go`)
- VPN engine → Handshake v2: dispatches handshakes
- VPN engine → Control messages: handles peer updates
- Key generation → Key and AEAD: generates keys (evidence: `cmd/keygen/main.go`)
- VPN engine → Remote VPN peers: relays and discovers routes (evidence: `README.md`)