# sbezverk/gobmp architecture

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

- Interactive diagram: https://gitdiagram.com/sbezverk/gobmp
- Repository: https://github.com/sbezverk/gobmp

## Overview

##### Project type and purpose
- Type: An open-source, network-protocol collector/processor tool written in Go.
- Purpose:
– Accept Open BMP (RFC 7854) messages over TCP.
– Parse BGP update NLRI/attributes (multiple AFI/SAFI).
– Build unified “record” objects.
– Publish those records to Kafka topics, NATS, files, or stdout.
– Support “player” (replay) and “validator” (message‐check) commands.
– Run standalone, in Docker, or as a Kubernetes deployment.

##### File structure (high-level)
- cmd/
– gobmp: main collector binary (HTTP pprof + BMP TCP listener)
– player: replay recorded BMP messages
– validator: validate BMP or JSON files
- pkg/
– gobmpsrv: TCP server, BMP session handling
– parser: low-level BMP message parsing
– base, bgp, bmp, bgpls, evpn, flowspec, …: NLRI/attribute definitions & parsers
– message: unified record schema (types.go)
– kafka, nats, pub: publisher interfaces & implementations
– dumper: file or console output
– validator: runtime message checks
- build/: Dockerfiles, testbed configs, kernel tuning scripts
- deployment/: Kubernetes YAML for gobmp (standalone + with “player”)
- CI/CD: .github/workflows/cicd.yml
- Makefile: build commands for binaries and images
- README.md + BMP.md: protocol reference & usage

##### Extract architectural insights from README
- goBMP listens on port 5000 for BMP speakers.
- Exposes port 56767 for pprof monitoring.
- Configurable sinks: Kafka servers, JSON file, stdout.
- Intercept mode: forwards raw BMP to another port.
- Deployable as Docker container or K8s deployment.

##### Main components and interactions
a. Ingress:
– External BMP Speaker(s) → TCP (port 5000) → gobmpsrv (pkg/gobmpsrv)
b. Core processing pipeline:
1. gobmpsrv receives raw BMP messages (common header, per-peer header).
2. parser unpacks BMP messages into Go structs (pkg/parser + pkg/bmp).
3. Per-AFI/SAFI modules (pkg/bgp, pkg/bgpls, pkg/evpn, etc.) parse Update NLRI & attributes.
4. message builder (pkg/message) constructs unified JSON record objects.
5. Optional validator (pkg/validator) can check record correctness.
c. Output/publishing layer:
– KafkaPublisher (pkg/kafka) → Kafka topics
– NATSPublisher (pkg/nats) → NATS streams
– File Dumper (pkg/dumper) → JSON file
– Console Dumper (stdout)
– Custom publisher (pkg/pub) for extensibility
d. Auxiliary components:
– Intercept module: duplicates raw BMP → another TCP port for external processor
– pprof HTTP server → port 56767 (runtime monitoring)
– CLI wrappers (cmd/gobmp, cmd/player, cmd/validator)

##### Architectural patterns & design principles
- Modular Go packages by protocol feature (separation of concerns).
- Publisher interface pattern: easily add new sinks (Kafka, NATS, file, custom).
- Pluggable parsers for each AFI/SAFI and extension.
- Clear CLI vs. library boundary: cmd/* uses pkg/* internally.
- “Player” and “Validator” reuse core parsing/message logic.

##### Final checklist
[ ] All major components (listener, parser, per-AFI modules, message builder, publishers) are present
[ ] Extensibility points (new AFI support, new publisher) are highlighted
[ ] Deployment variants (binary vs. Docker vs. Kubernetes) are shown, if needed

## Diagram (Mermaid)

```mermaid
flowchart TD
    External["BMP Speaker"]:::external
    External -->|"TCP 5000"| Gobmpsrv

    subgraph "goBMP Core"
        direction TB
        Gobmpsrv["BMP TCP Listener & Session Handler"]:::ingestion
        Parser["Low-Level Parser Core"]:::parsing
        BMPDefs["BMP Message Definitions & Parsing"]:::parsing
        AFIModules["AFI/SAFI Protocol Modules"]:::parsing
        MessageBuilder["Unified Record Builder"]:::parsing
        RuntimeValidator["Runtime Validator (optional)"]:::aux
    end

    Gobmpsrv --> Parser
    Parser --> BMPDefs
    BMPDefs --> AFIModules
    AFIModules --> MessageBuilder
    MessageBuilder --> RuntimeValidator

    subgraph "Publishers"
        direction TB
        PubInterface["Publisher Interface"]:::aux
        KafkaPublisher["Kafka Publisher"]:::publishing
        NATSPublisher["NATS Publisher"]:::publishing
        Dumper["File & Console Dumper"]:::publishing
        Filer["File Output Support"]:::publishing
    end

    MessageBuilder --> PubInterface
    PubInterface --> KafkaPublisher
    KafkaPublisher --> KafkaTopic[(Kafka Topic)]
    PubInterface --> NATSPublisher
    NATSPublisher --> NATSStream[(NATS Stream)]
    PubInterface --> Dumper
    Dumper --> JSONFile[(JSON File)]
    Dumper --> Console[(Stdout)]

    subgraph "CLI Tools"
        direction TB
        CollectorCLI["Collector CLI (gobmp)"]:::aux
        PlayerCLI["Player CLI (replay)"]:::aux
        ValidatorCLI["Validator CLI"]:::aux
    end

    CollectorCLI --> Gobmpsrv
    PlayerCLI --> MessageBuilder
    ValidatorCLI --> RuntimeValidator

    subgraph "Auxiliary Services"
        direction TB
        Pprof["pprof HTTP Server (port 56767)"]:::aux
        Intercept["Intercept Module"]:::aux
    end

    Gobmpsrv --> Intercept
    Gobmpsrv --> Pprof

    subgraph "Deployment"
        direction TB
        Local["Local Binary / Docker / Kubernetes"]:::aux
    end

    CollectorCLI --> Local

    click CollectorCLI "https://github.com/sbezverk/gobmp/blob/master/cmd/gobmp/gobmp.go"
    click PlayerCLI "https://github.com/sbezverk/gobmp/blob/master/cmd/player/player.go"
    click ValidatorCLI "https://github.com/sbezverk/gobmp/blob/master/cmd/validator/validator.go"
    click Gobmpsrv "https://github.com/sbezverk/gobmp/blob/master/pkg/gobmpsrv/gobmpsrv.go"
    click Parser "https://github.com/sbezverk/gobmp/blob/master/pkg/parser/parser.go"
    click BMPDefs "https://github.com/sbezverk/gobmp/tree/master/pkg/bmp"
    click AFIModules "https://github.com/sbezverk/gobmp/tree/master/pkg/bgp"
    click MessageBuilder "https://github.com/sbezverk/gobmp/blob/master/pkg/message/types.go"
    click PubInterface "https://github.com/sbezverk/gobmp/blob/master/pkg/pub/publisher.go"
    click KafkaPublisher "https://github.com/sbezverk/gobmp/blob/master/pkg/kafka/kafka-publisher.go"
    click NATSPublisher "https://github.com/sbezverk/gobmp/blob/master/pkg/nats/nats-publisher.go"
    click Dumper "https://github.com/sbezverk/gobmp/blob/master/pkg/dumper/dumper.go"
    click RuntimeValidator "https://github.com/sbezverk/gobmp/blob/master/pkg/validator/check.go"

    classDef external fill:#EBF5FB,stroke:#5DADE2,color:#154360
    classDef ingestion fill:#D6EAF8,stroke:#3498DB,color:#154360
    classDef parsing fill:#D5F5E3,stroke:#27AE60,color:#1D8348
    classDef publishing fill:#FCF3CF,stroke:#F1C40F,color:#B9770E
    classDef aux fill:#E5E7E9,stroke:#ABB2B9,color:#424949
```
