# nextmn/srv6 architecture

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

- Interactive diagram: https://gitdiagram.com/nextmn/srv6
- Repository: https://github.com/nextmn/srv6

## Overview

##### Project Type & Purpose
- Type: A single Go‐based network agent/CLI daemon that implements SRv6 MUP endpoint behaviors.
- Purpose: Load user configuration, register SRv6 “tasks” (behaviors), expose an optional HTTP control API, and perform data‐plane packet handling by invoking Linux networking primitives (via iproute2/iptables).

##### File Structure
Top‐level:
– main.go: entrypoint.
– config/: static YAML example.
– internal/app: application bootstrap, API registry.
– internal/config: all config‐loading and feature flags.
– internal/ctrl: control‐plane HTTP server and endpoint registry.
– internal/database: persistence layer (embedded SQL).
– internal/iana: protocol constants.
– internal/iproute2: wrapper over Linux iproute2/tun interfaces.
– internal/netfunc: SRv6 behavior implementations (“net functions”).
– internal/tasks: task registry and implementations (glue code between controller, netfunc, iproute2).
– etc/, bash‐completion/: shipping example configs and shell completions.
CI/CD: .github/workflows; linting: .pre‐commit‐config.yaml; Makefile targets.

##### README Insights
– Incoming‐packet‐flow SVG shows separation of control vs. data paths.
– Runtime deps: iproute2 & iptables (interact with Linux kernel).
– Optional Docker deployment requiring NET_ADMIN capabilities.
– Roadmap tables list which SRv6 behaviors are implemented.

##### Main Components & Their Relationships
a. Core Components
- CLI/Daemon (main.go + internal/app): reads CLI flags, loads config, starts subsystems.
- Configuration Loader (internal/config): parses YAML and environment overrides.
- Control Plane (internal/ctrl + internal/app/api): optional HTTP server exposing REST endpoints to dynamically add/remove policies.
- Persistence Layer (internal/database): initializes embedded SQL store (database.sql), CRUD APIs for uplink/downlink sessions.
- Task Registry (internal/tasks): “Command” pattern where each SRv6 behavior is registered, configured, and executed.
- SRv6 Functions (internal/netfunc): actual packet‐processing logic implementing each endpoint behavior.
- IPRoute2 Adapter (internal/iproute2): interfaces for creating TUN devices, adding ip rules, SRv6 policy.
- Operating System Kernel (Linux Networking Stack): performs packet encapsulation, forwarding, and actual SRv6 data path.
- External Tools: iptables (for filtering), iproute2 CLI under the hood.

b. Data & Control Flows
– Control Flow: User CLI → config loader → app bootstrap → register netfuncs/tasks → start HTTP server → HTTP API calls → ctrl layer → tasks → iproute2 adapter → kernel.
– Data Flow: Inbound packet arrives at kernel → SRv6 routing (seg6) hands to TUN or hook → NextMN‐SRv6 netfunc handler processes packet → potentially modifies headers or forwards → kernel.

##### Architectural Patterns & Design Principles
- Layered modularization: config → app → controller → tasks → netfunc → platform adapter.
- Registry/Plugin pattern: all behaviors (“tasks” and “netfuncs”) self‐register via init/registry.go.
- Separation of Concerns: distinct packages for control plane vs. data plane vs. persistence vs. system adapters.
- Dependency injection via configuration (internal/config + registry.go).

##### Detail
– Capture all internal packages and their high‐level responsibility.
– Reflect the plugin registry mechanism.
– Explicitly show how configuration and database tie into the controller.
– Don’t over‐aggregate: represent at least one example netfunc and one example task to illustrate extensibility.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Bootstrap Layer
    subgraph "Bootstrap Layer"
        direction TB
        CLI["CLI/Daemon\n(main.go)"]:::engine
        ConfigLoader["Configuration Loader\n(internal/config/config.go)"]:::control
        CLI -->|reads flags & config| ConfigLoader
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        AppSetup["App Setup\n(internal/app/setup.go)"]:::engine
        AppRegistry["App Registry\n(internal/app/registry.go)"]:::engine
        APIRegistry["API Registry\n(internal/app/api/registry.go)"]:::control
        ConfigLoader --> AppSetup
        AppSetup --> AppRegistry
        AppRegistry --> APIRegistry
    end

    %% Control Plane
    subgraph "Control Plane" 
        direction TB
        HTTPServer["HTTP Control API\n(internal/ctrl/api/rules-registry-http.go)"]:::control
        CtrlRegistry["Controller Registry\n(internal/ctrl/controller-registry.go)"]:::control
        APIRegistry --> HTTPServer
        HTTPServer --> CtrlRegistry
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        DBCore["Database Core\n(internal/database/database.go)"]:::control
        DBSchema["Schema SQL\n(internal/database/database.sql)"]:::control
        APIUplink["Uplink API\n(internal/database/api/uplink.go)"]:::control
        APIDownlink["Downlink API\n(internal/database/api/downlink.go)"]:::control
        CtrlRegistry --> DBCore
        DBCore --> DBSchema
        DBCore --> APIUplink
        DBCore --> APIDownlink
    end

    %% Task Registry & Implementations
    subgraph "Task Registry" 
        direction TB
        TasksRegistry["Tasks Registry\n(internal/tasks/registry.go)"]:::engine
        TasksCtrlReg["Task Ctrl Registry\n(internal/tasks/controller-registry.go)"]:::engine
        TasksAPIReg["Task API Registry\n(internal/tasks/api/registry.go)"]:::engine
        TasksRegistry --> TasksCtrlReg
        TasksCtrlReg --> TasksAPIReg
        CtrlRegistry --> TasksRegistry
    end

    %% SRv6 Netfuncs
    subgraph "SRv6 Netfuncs"
        direction TB
        IANA["Protocol Constants\n(internal/iana/srv6-endpoint-behaviors-registry.go)"]:::data
        NetfuncBase["Netfunc Base\n(internal/netfunc/base-handler.go)"]:::data
        NetfuncAPI["Netfunc API\n(internal/netfunc/api/netfunc.go)"]:::data
        NetfuncGTP4["End.M.GTP4.E\n(internal/netfunc/endpoint-m-gtp4-e.go)"]:::data
        Headend["Headend\n(internal/netfunc/headend.go)"]:::data
        HeadendGTP4["Headend GTP4\n(internal/netfunc/headend-gtp4.go)"]:::data
        HeadendEnc["Headend Encaps Ctrl\n(internal/netfunc/headend-encaps-ctrl.go)"]:::data
        TasksAPIReg --> IANA
        IANA --> NetfuncBase
        NetfuncBase --> NetfuncAPI
        NetfuncAPI --> NetfuncGTP4
        NetfuncAPI --> Headend
        NetfuncAPI --> HeadendGTP4
        NetfuncAPI --> HeadendEnc
    end

    %% System Adapter Layer
    subgraph "IPRoute2 Adapter" 
        direction TB
        TableAPI["Table API\n(internal/iproute2/table.go)"]:::adapter
        IfaceAPI["Iface API\n(internal/iproute2/api/iface.go)"]:::adapter
        TunIface["TUN Interface\n(internal/iproute2/tun-iface.go)"]:::adapter
        DummyIface["Dummy Interface\n(internal/iproute2/dummy-iface.go)"]:::adapter
        Utils["Utils\n(internal/iproute2/utils.go)"]:::adapter
        TasksAPIReg --> TableAPI
        TasksAPIReg --> IfaceAPI
        TasksAPIReg --> TunIface
        TasksAPIReg --> DummyIface
        TasksAPIReg --> Utils
    end

    %% Data Plane Flow
    KernelIn["Linux Kernel\n(Network Stack)"]:::external
    KernelOut["Linux Kernel\n(Network Stack)"]:::external
    KernelIn -->|packet arrives| NetfuncAPI
    NetfuncAPI -->|processed packet| KernelOut
    KernelOut -->|forward| KernelIn

    %% External Tools
    Iptables["iptables"]:::external
    IPRoute2CLI["iproute2 CLI"]:::external
    Iptables --> KernelIn
    TunIface --> KernelIn
    DummyIface --> KernelIn
    TableAPI --> IPRoute2CLI

    %% Click Events
    click CLI "https://github.com/nextmn/srv6/blob/master/main.go"
    click ConfigLoader "https://github.com/nextmn/srv6/blob/master/internal/config/config.go"
    click AppSetup "https://github.com/nextmn/srv6/blob/master/internal/app/setup.go"
    click AppRegistry "https://github.com/nextmn/srv6/blob/master/internal/app/registry.go"
    click APIRegistry "https://github.com/nextmn/srv6/blob/master/internal/app/api/registry.go"
    click HTTPServer "https://github.com/nextmn/srv6/blob/master/internal/ctrl/api/rules-registry-http.go"
    click CtrlRegistry "https://github.com/nextmn/srv6/blob/master/internal/ctrl/controller-registry.go"
    click DBCore "https://github.com/nextmn/srv6/blob/master/internal/database/database.go"
    click DBSchema "https://github.com/nextmn/srv6/blob/master/internal/database/database.sql"
    click APIUplink "https://github.com/nextmn/srv6/blob/master/internal/database/api/uplink.go"
    click APIDownlink "https://github.com/nextmn/srv6/blob/master/internal/database/api/downlink.go"
    click IANA "https://github.com/nextmn/srv6/blob/master/internal/iana/srv6-endpoint-behaviors-registry.go"
    click TableAPI "https://github.com/nextmn/srv6/blob/master/internal/iproute2/table.go"
    click IfaceAPI "https://github.com/nextmn/srv6/blob/master/internal/iproute2/api/iface.go"
    click TunIface "https://github.com/nextmn/srv6/blob/master/internal/iproute2/tun-iface.go"
    click DummyIface "https://github.com/nextmn/srv6/blob/master/internal/iproute2/dummy-iface.go"
    click Utils "https://github.com/nextmn/srv6/blob/master/internal/iproute2/utils.go"
    click NetfuncAPI "https://github.com/nextmn/srv6/blob/master/internal/netfunc/api/netfunc.go"
    click NetfuncBase "https://github.com/nextmn/srv6/blob/master/internal/netfunc/base-handler.go"
    click NetfuncGTP4 "https://github.com/nextmn/srv6/blob/master/internal/netfunc/endpoint-m-gtp4-e.go"
    click Headend "https://github.com/nextmn/srv6/blob/master/internal/netfunc/headend.go"
    click HeadendGTP4 "https://github.com/nextmn/srv6/blob/master/internal/netfunc/headend-gtp4.go"
    click HeadendEnc "https://github.com/nextmn/srv6/blob/master/internal/netfunc/headend-encaps-ctrl.go"
    click TasksRegistry "https://github.com/nextmn/srv6/blob/master/internal/tasks/registry.go"
    click TasksCtrlReg "https://github.com/nextmn/srv6/blob/master/internal/tasks/controller-registry.go"
    click TasksAPIReg "https://github.com/nextmn/srv6/blob/master/internal/tasks/api/registry.go"
    click TasksRegistry "https://github.com/nextmn/srv6/blob/master/internal/tasks/blackhole.go"
    click TasksRegistry "https://github.com/nextmn/srv6/blob/master/internal/tasks/nextmn-endpoint.go"
    click TasksRegistry "https://github.com/nextmn/srv6/blob/master/internal/tasks/nextmn-headend.go"
    click TasksRegistry "https://github.com/nextmn/srv6/blob/master/internal/tasks/tun-iface.go"
    click TasksRegistry "https://github.com/nextmn/srv6/blob/master/internal/tasks/iprule.go"
    click TasksRegistry "https://github.com/nextmn/srv6/blob/master/internal/tasks/http-server.go"
    click Iptables "https://github.com/nextmn/srv6/blob/master/etc/iproute2/rt_protos.d/nextmn.conf"
    click Iptables "https://github.com/nextmn/srv6/blob/master/etc/iproute2/rt_tables.d/nextmn.conf"

    %% Styles
    classDef control fill:#D0E8FF,stroke:#0066CC
    classDef data fill:#DFFFD0,stroke:#99CC33
    classDef adapter fill:#FFE6B3,stroke:#FF9900
    classDef engine fill:#F0F0F0,stroke:#999999
    classDef external fill:#EEEEEE,stroke:#666666
    class CLI,ConfigLoader,AppSetup,AppRegistry,APIRegistry,HTTPServer,CtrlRegistry,DBCore,DBSchema,APIUplink,APIDownlink control
    class NetfuncBase,NetfuncAPI,NetfuncGTP4,Headend,HeadendGTP4,HeadendEnc,IANA data
    class TableAPI,IfaceAPI,TunIface,DummyIface,Utils adapter
    class CLI,AppSetup,AppRegistry,TasksRegistry,TasksCtrlReg,TasksAPIReg engine
    class KernelIn,KernelOut,Iptables,IPRoute2CLI external
```
