# gnbdev/opengnb architecture

> Architecture diagram of the GitHub repository gnbdev/opengnb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gnbdev/opengnb
- Repository: https://github.com/gnbdev/opengnb

## Overview

##### Project type and purpose
- This is an open-source, multi-platform, P2P VPN/virtual network daemon written in C (OpenGNB).
- It provides intranet-penetration, point-to-point and relay forwarding of IP packets over virtual TUN interfaces, with NAT traversal and optional relay (“forward”) and index (“tracker”) nodes.

##### File structure
- Top-level:
- Makefiles for various OSes (Makefile.linux, Makefile.mingw_x86_64, etc.) → cross-platform build system
- libs/ → bundled third-party libraries: ed25519 (crypto), miniupnpc, libnatpmp, zlib, TAP-Windows, Wintun, protocol definitions, packet filter helpers
- src/ → application source code
– src/cli/ → CLI entry points: gnb, gnb_crypto, gnb_ctl, gnb_es
– src/crypto/ → symmetric/stream cipher modules (arc4, xor) and random
– src/ctl/, src/es/ → control-plane (configuration dumping, environment service, discovery)
– src/*Platform*/ → platform abstraction for TUN/TAP driver and native network I/O (linux, freebsd, darwin, openbsd, mingw, unix)
– src/packet_filter/ → packet-filtering, payload manipulation (zip, route, crypto)
– src/gnb_*.c/.h → core engine: configuration, node management, message frames, workers, ring buffers, forwarding, logging
- scripts/ → systemd service definitions
- examples/ → sample configuration files and up/down scripts per OS

##### Extract README insights
- Core components:
- gnb daemon – establishes virtual network interface (gnb_tun), manages peers, routes packets
- gnb_crypto – key management and signing (ED25519)
- gnb_ctl – control interface to query or dump internal state
- gnb_es – environment service for LAN discovery and broadcast
- External services:
- index node (tracker-like) – peer address indexing, no data forwarding
- forward node – optional relay for data when P2P fails

##### Final recommendations
- **all** major sub-systems: CLI, config loader, core engine, worker threads (discover, index, forward, packet-filter), network I/O, crypto, platform drivers.
- **per-packet flow**: from TUN → core → crypto → UDP → peer → TUN.
- **initial handshake**: core contacting index node, NAT traversal, peer candidate selection.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Tools
    subgraph "CLI Tools"
        CLI_gnb["gnb"]:::internal
        CLI_crypto["gnb_crypto"]:::internal
        CLI_ctl["gnb_ctl"]:::internal
        CLI_es["gnb_es"]:::internal
    end

    %% Configuration Management
    subgraph "Configuration Management"
        Conf_file["gnb_conf_file.c"]:::config
        Conf_core["gnb_conf.c"]:::config
        Conf_lite["gnb_config_lite.c"]:::config
        Conf_args["gnb_arg_list.c"]:::config
        Conf_argv["gnb_argv.c"]:::config
    end

    %% Core Engine
    subgraph "Core Engine"
        Core_daemon["gnb_daemon.c"]:::internal
        Core_core["gnb_core.c"]:::internal
        Core_worker["gnb_worker.c"]:::internal
        Core_node_worker["gnb_node_worker.c"]:::internal
        Core_udp["gnb_udp.c"]:::internal
        Core_forward["gnb_unified_forwarding.c"]:::internal
    end

    %% Crypto Module
    subgraph "Crypto Module"
        Crypto_arc4["arc4.c / arc4.h"]:::internal
        Crypto_xor["xor.c / xor.h"]:::internal
        Crypto_rand["gnb_random.c / gnb_random.h"]:::internal
        Crypto_ed["ED25519 Library"]:::external
    end

    %% Packet Filter Sub-System
    subgraph "Packet Filter"
        PF_arc4["gnb_pf_crypto_arc4.c"]:::packet
        PF_xor["gnb_pf_crypto_xor.c"]:::packet
        PF_zip["gnb_pf_zip.c"]:::packet
        PF_route["gnb_pf_route.c"]:::packet
        PF_dump["gnb_pf_dump.c"]:::packet
    end

    %% Platform Abstraction
    subgraph "Platform Abstraction"
        Plat_linux["gnb_drv_linux.c"]:::platform
        Plat_darwin["gnb_drv_darwin.c"]:::platform
        Plat_freebsd["gnb_drv_freebsd.c"]:::platform
        Plat_openbsd["gnb_drv_openbsd.c"]:::platform
        Plat_win32["gnb_drv_win32.c"]:::platform
        Plat_wintun["gnb_drv_wintun.c"]:::platform
        Plat_unix["unix_platform.c"]:::platform
    end

    %% NAT Traversal Libraries
    subgraph "NAT Traversal Libs"
        NAT_upnp["miniupnpc"]:::nat
        NAT_pmp["libnatpmp"]:::nat
    end

    %% Network I/O & Virtual Interface
    UDP["UDP Socket"]:::network
    VIF["TUN/TAP Virtual Interface"]:::virtual

    %% External Services
    subgraph "External Services"
        Index["Index Node"]:::external
        Forward["Forward Node"]:::external
    end

    %% Connections
    CLI_gnb -->|invokes| Core_daemon
    CLI_crypto -->|invokes| Crypto_ed
    CLI_ctl -->|connects to| Core_daemon
    CLI_es -->|invokes| Core_daemon

    Conf_file -->|loads config| Core_core
    Conf_core -->|loads config| Core_core
    Conf_lite -->|loads config| Core_core
    Conf_args -->|parses args| Core_core
    Conf_argv -->|parses argv| Core_core

    Core_core -->|spawns| Core_worker
    Core_core -->|spawns| Core_node_worker
    Core_core -->|communicates| Core_udp
    Core_core -->|uses| Core_forward

    Core_core -->|sign/verify| Crypto_arc4
    Core_core -->|sign/verify| Crypto_xor
    Core_core -->|random| Crypto_rand
    Core_core -->|ED25519 ops| Crypto_ed

    Core_core -->|applies| PF_arc4
    Core_core -->|applies| PF_xor
    Core_core -->|applies| PF_zip
    Core_core -->|applies| PF_route
    Core_core -->|applies| PF_dump

    Core_core -->|inject/extract| VIF
    Core_core -->|send/receive| UDP

    UDP -->|hole punching| NAT_upnp
    UDP -->|hole punching| NAT_pmp

    UDP -->|lookup| Index
    UDP -->|relay if needed| Forward

    Plat_linux -->|driver| VIF
    Plat_darwin -->|driver| VIF
    Plat_freebsd -->|driver| VIF
    Plat_openbsd -->|driver| VIF
    Plat_win32 -->|driver| VIF
    Plat_wintun -->|driver| VIF
    Plat_unix -->|driver| VIF

    %% Click Events
    click CLI_gnb "https://github.com/gnbdev/opengnb/blob/master/src/cli/gnb.c"
    click CLI_crypto "https://github.com/gnbdev/opengnb/blob/master/src/cli/gnb_crypto.c"
    click CLI_ctl "https://github.com/gnbdev/opengnb/blob/master/src/cli/gnb_ctl.c"
    click CLI_es "https://github.com/gnbdev/opengnb/blob/master/src/cli/gnb_es.c"
    click Conf_file "https://github.com/gnbdev/opengnb/blob/master/src/gnb_conf_file.c"
    click Conf_core "https://github.com/gnbdev/opengnb/blob/master/src/gnb_conf.c"
    click Conf_lite "https://github.com/gnbdev/opengnb/blob/master/src/gnb_config_lite.c"
    click Conf_args "https://github.com/gnbdev/opengnb/blob/master/src/gnb_arg_list.c"
    click Conf_argv "https://github.com/gnbdev/opengnb/blob/master/src/gnb_argv.c"
    click Core_daemon "https://github.com/gnbdev/opengnb/blob/master/src/gnb_daemon.c"
    click Core_core "https://github.com/gnbdev/opengnb/blob/master/src/gnb_core.c"
    click Core_worker "https://github.com/gnbdev/opengnb/blob/master/src/gnb_worker.c"
    click Core_node_worker "https://github.com/gnbdev/opengnb/blob/master/src/gnb_node_worker.c"
    click Core_udp "https://github.com/gnbdev/opengnb/blob/master/src/gnb_udp.c"
    click Core_forward "https://github.com/gnbdev/opengnb/blob/master/src/gnb_unified_forwarding.c"
    click Crypto_arc4 "https://github.com/gnbdev/opengnb/blob/master/src/crypto/arc4/arc4.c"
    click Crypto_xor "https://github.com/gnbdev/opengnb/blob/master/src/crypto/xor/xor.c"
    click Crypto_rand "https://github.com/gnbdev/opengnb/blob/master/src/crypto/random/gnb_random.c"
    click Crypto_ed "https://github.com/gnbdev/opengnb/tree/master/libs/ed25519/"
    click PF_arc4 "https://github.com/gnbdev/opengnb/blob/master/src/packet_filter/gnb_pf_crypto_arc4.c"
    click PF_xor "https://github.com/gnbdev/opengnb/blob/master/src/packet_filter/gnb_pf_crypto_xor.c"
    click PF_zip "https://github.com/gnbdev/opengnb/blob/master/src/packet_filter/gnb_pf_zip.c"
    click PF_route "https://github.com/gnbdev/opengnb/blob/master/src/packet_filter/gnb_pf_route.c"
    click PF_dump "https://github.com/gnbdev/opengnb/blob/master/src/packet_filter/gnb_pf_dump.c"
    click Plat_linux "https://github.com/gnbdev/opengnb/blob/master/src/linux/gnb_drv_linux.c"
    click Plat_darwin "https://github.com/gnbdev/opengnb/blob/master/src/Darwin/gnb_drv_darwin.c"
    click Plat_freebsd "https://github.com/gnbdev/opengnb/blob/master/src/freebsd/gnb_drv_freebsd.c"
    click Plat_openbsd "https://github.com/gnbdev/opengnb/blob/master/src/openbsd/gnb_drv_openbsd.c"
    click Plat_win32 "https://github.com/gnbdev/opengnb/blob/master/src/mingw/gnb_drv_win32.c"
    click Plat_wintun "https://github.com/gnbdev/opengnb/blob/master/src/mingw/gnb_drv_wintun.c"
    click Plat_unix "https://github.com/gnbdev/opengnb/blob/master/src/unix/unix_platform.c"
    click NAT_upnp "https://github.com/gnbdev/opengnb/tree/master/libs/miniupnpc/"
    click NAT_pmp "https://github.com/gnbdev/opengnb/tree/master/libs/libnatpmp/"

    %% Styles
    classDef internal fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef external fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef config fill:#eeeeee,stroke:#757575,color:#424242,shape:cylinder
    classDef virtual fill:#fff9c4,stroke:#f9a825,color:#f57f17
    classDef network fill:#ffecb3,stroke:#ffa000,color:#e65100
    classDef packet fill:#d7ccc8,stroke:#8d6e63,color:#4e342e
    classDef platform fill:#e1bee7,stroke:#8e24aa,color:#4a148c
    classDef nat fill:#c5cae9,stroke:#3949ab,color:#1a237e
```
