# rtbrick/bngblaster architecture

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

- Interactive diagram: https://gitdiagram.com/rtbrick/bngblaster
- Repository: https://github.com/rtbrick/bngblaster

## Overview

##### Project type and purpose
- This is an open-source network testing tool (Routing Protocol and BNG Blaster) written in C/C++ using CMake.
- Purpose: simulate large numbers of access (PPPoE, DHCP/IPoE, L2TP) and routing (ISIS, OSPF, LDP, BGP) sessions; generate and verify traffic; measure QoS and convergence.

##### File structure
- Top-level:
- code/ – all source subprojects:
– bngblaster – main application (src, CLI, interactive, stats, config)
– bgpupdate, ldpupdate, lspgen, ldpupdate – helper tools
– common – shared utilities (logging, timer, checksum)
– lwip – bundled TCP/IP stack (core, netif, ports, apps, tests)
- docs/, docsrc/ – Sphinx documentation source and output
- examples/ – JSON config examples
- wireshark/ – dissector plugin
- CI: .github/workflows/*.yml
- Build: CMakeLists.txt, shell.nix, flake.nix

##### README
- Confirms the project simulates millions of flows, supports protocol fuzzing, interactive mode, integrates with external libs (lwIP), and is used via CLI.

a. Main components
- User Interface Layer
– CLI Front-end (bngblaster-cli)
– Interactive Shell (bbl_interactive)
- Configuration & Control
– Config Parser (bbl_config)
– Session Manager (bbl_ctx, bbl_session)
- Protocol Engines
– Access Protocol Modules (PPPoE, DHCPv4/v6, L2TP, PPP)
– Routing Protocol Modules (ISIS, OSPF, LDP, BGP)
- Traffic Generator
– Flow Tracker & Stats Collector (bbl_stream, bbl_stats)
- I/O Abstraction Layer
– io_socket, io_raw, io_dpdk, io_pcap, io_thread
- Embedded TCP/IP Stack
– lwIP core (ip, tcp, udp) + netif ports
- Common Utilities
– Logging, checksums, timers (common/src)
- External Tools
– Fuzzing (code/bngblaster/fuzzing)
– Helper tools (bgpupdate, ldpupdate, lspgen)
– Wireshark dissector plugin

b. Relationships & interactions
- User → CLI → Config Parser → Session Manager
- Session Manager instantiates Protocol Engines + Traffic Generator
- Protocol Engines and Traffic Generator issue/send packets via I/O Abstraction → network interface
- I/O Abstraction may invoke lwIP or raw socket/DPDK drivers → actual NIC or pcap
- Stats Collector gathers metrics, feeds back to CLI/interactive shell
- Fuzzing harness sits alongside Protocol Engines, injecting malformed packets via I/O layer
- Helper tools (bgpupdate, etc.) operate in sequence for specific protocol test flows

c. Architectural patterns / design principles
- Modular plugin-style protocol implementation
- Clear separation of concerns: UI / control / protocol / I/O / utilities
- Abstraction of transport (raw/DPDK/pcap) behind a unified I/O interface
- Usage of an embedded stack (lwIP) to simulate protocol behavior where beneficial
- Extensive test and fuzzing harness integrated in same codebase

d. Key technologies, frameworks, libraries
- CMake build system
- lwIP (MIT-style TCP/IP stack)
- DPDK (if built via io_dpdk)
- libpcap (via io_pcap)
- GitHub Actions (CI/CD)
- Sphinx (documentation)
- Wireshark Lua (packet dissector plugin)
- shell.nix / flake.nix (reproducible dev environment)

##### Detail
- Break out each protocol (ISIS, OSPF, etc.) only if space allows; otherwise group under “Routing Protocols”.
- Optional paths (fuzzing injection versus normal run).
- Build & CI pipeline as an auxiliary flow if desired (CMake → GitHub Actions).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI & Control Layer
    subgraph "UI & Control" 
        CLI["CLI Front-end"]:::ui
        Interactive["Interactive Shell"]:::ui
        Config["Config Parser"]:::ui
        Ctx["Session Manager\n(Context)"]:::ui
        Sess["Session Manager\n(Sessions)"]:::ui
    end

    %% Protocol Engines
    subgraph "Protocol Engines" 
        Access["Access Protocols"]:::proto
        Routing["Routing Protocols"]:::proto
    end

    %% Traffic Generation & Statistics
    subgraph "Traffic & Stats"
        Flow["Flow Tracker"]:::traffic
        Stats["Stats Collector"]:::traffic
    end

    %% I/O & Network Layer
    subgraph "I/O Abstraction & Network"
        IoCore["I/O Abstraction"]:::io
        IoRaw["Raw Socket / mmap"]:::io
        IoDpdk["DPDK"]:::io
        IoSock["Socket"]:::io
        IoThread["Threaded I/O"]:::io
        IoStream["Stream I/O"]:::io
        Network["Physical NIC / pcap"]:::io
    end

    %% Embedded TCP/IP Stack
    subgraph "Embedded Stack (lwIP)"
        LwipStub["lwIP opts"]:::stack
        LwipFull["lwIP full tree"]:::stack
    end

    %% Common Utilities
    Util["Common Utilities"]:::util

    %% External Tools & Tests
    subgraph "External Tools & Tests"
        Fuzz["Fuzzing Harness"]:::ext
        Helper1["BGP Update"]:::ext
        Helper2["LDP Update"]:::ext
        Helper3["LSP Generator"]:::ext
        Wireshark["Wireshark Plugin"]:::ext
    end

    %% Connections: UI → Control
    CLI -->|"invoke"| Config
    Interactive -->|"invoke"| Config
    Config -->|"config load"| Ctx
    Ctx -->|"init sessions"| Sess

    %% Session to sub-systems
    Sess -->|"start access protocols"| Access
    Sess -->|"start routing protocols"| Routing
    Sess -->|"start flows"| Flow
    Sess -->|"start stats"| Stats

    %% Protocols & Traffic to I/O
    Access -->|"packet send"| IoCore
    Routing -->|"packet send"| IoCore
    Flow -->|"packet inject"| IoCore

    %% I/O internal
    IoCore --> IoRaw
    IoCore --> IoDpdk
    IoCore --> IoSock
    IoCore --> IoThread
    IoCore --> IoStream
    IoCore -->|"to network"| Network

    %% Embedded stack integration
    LwipFull -->|"stack calls"| IoCore
    IoCore -->|"stack hooks"| LwipFull
    LwipStub --> LwipFull

    %% Stats feedback
    Stats -->|"stats update"| CLI
    Stats -->|"stats update"| Interactive

    %% Utilities
    Access --> Util
    Routing --> Util
    Flow --> Util
    Config --> Util
    Ctx --> Util

    %% External Tools
    Fuzz -->|"inject malformed"| IoCore
    Helper1 -->|"control flow"| IoCore
    Helper2 -->|"control flow"| IoCore
    Helper3 -->|"control flow"| IoCore
    Wireshark -->|"dissector"| Network

    %% Click Events
    click CLI "https://github.com/rtbrick/bngblaster/tree/main/code/bngblaster-cli"
    click Interactive "https://github.com/rtbrick/bngblaster/blob/main/code/bngblaster/src/bbl_interactive.c"
    click Config "https://github.com/rtbrick/bngblaster/blob/main/code/bngblaster/src/bbl_config.c"
    click Ctx "https://github.com/rtbrick/bngblaster/blob/main/code/bngblaster/src/bbl_ctx.c"
    click Sess "https://github.com/rtbrick/bngblaster/blob/main/code/bngblaster/src/bbl_session.c"
    click Access "https://github.com/rtbrick/bngblaster/blob/main/code/bngblaster/src/bbl_access.c"
    click Routing "https://github.com/rtbrick/bngblaster/tree/main/code/bngblaster/src/bngblaster/src/isis/"
    click Flow "https://github.com/rtbrick/bngblaster/blob/main/code/bngblaster/src/bbl_stream.c"
    click Stats "https://github.com/rtbrick/bngblaster/blob/main/code/bngblaster/src/bbl_stats.c"
    click IoCore "https://github.com/rtbrick/bngblaster/blob/main/code/bngblaster/src/io/io.c"
    click IoRaw "https://github.com/rtbrick/bngblaster/blob/main/code/bngblaster/src/io/io_raw.c"
    click IoDpdk "https://github.com/rtbrick/bngblaster/blob/main/code/bngblaster/src/io/io_dpdk.c"
    click IoSock "https://github.com/rtbrick/bngblaster/blob/main/code/bngblaster/src/io/io_socket.c"
    click IoThread "https://github.com/rtbrick/bngblaster/blob/main/code/bngblaster/src/io/io_thread.c"
    click IoStream "https://github.com/rtbrick/bngblaster/blob/main/code/bngblaster/src/io/io_stream.c"
    click LwipStub "https://github.com/rtbrick/bngblaster/blob/main/code/bngblaster/src/lwip/lwipopts.h"
    click LwipFull "https://github.com/rtbrick/bngblaster/tree/main/code/lwip/"
    click Util "https://github.com/rtbrick/bngblaster/tree/main/code/common/src/"
    click Fuzz "https://github.com/rtbrick/bngblaster/tree/main/code/bngblaster/fuzzing/"
    click Helper1 "https://github.com/rtbrick/bngblaster/tree/main/code/bgpupdate"
    click Helper2 "https://github.com/rtbrick/bngblaster/tree/main/code/ldpupdate"
    click Helper3 "https://github.com/rtbrick/bngblaster/tree/main/code/lspgen"
    click Wireshark "https://github.com/rtbrick/bngblaster/blob/main/wireshark/bbl_header.lua"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef proto fill:#d4edda,stroke:#155724,color:#155724
    classDef traffic fill:#fff3cd,stroke:#856404,color:#856404
    classDef io fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef stack fill:#fff5d1,stroke:#8a6d3b,color:#8a6d3b
    classDef util fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef ext fill:#f0e6ff,stroke:#4b0082,color:#4b0082
```
