# osrg/gobgp architecture

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

- Interactive diagram: https://gitdiagram.com/osrg/gobgp
- Repository: https://github.com/osrg/gobgp

## Overview

##### Key Components
- CLI & Daemon Executables: The “cmd” directory clearly contains two main executables—one for the primary BGP daemon (gobgp) and another for a variant (gobgpd). They serve as the entry points for launching the BGP control plane.
- API and Protobuf Definitions: The “api” folder contains protobuf definitions for BGP attributes, capabilities, and gRPC endpoints. This shows that GoBGP exposes an API (including gRPC services) for programmatic management.
- Core BGP Engine: The heart of the BGP implementation is found across the “pkg” and “internal” directories. Within these directories are submodules for:
- BGP packet processing and protocol state machine (pkg/packet/bgp, pkg/server/fsm, etc.).
- Route table management and policy processing (internal/pkg/table).
- Configuration management (pkg/config).
- Logging and metrics (pkg/log and pkg/metrics).
- External Integrations: Components like “pkg/zebra” and portions of the configuration related to Zebra indicate external system integrations. Other integration points include gRPC service hosting (pkg/server/grpc_server.go) and RPKI handling.
- Tests and Documentation: Although not core to the system’s runtime architecture, the “test” and “docs” directories are significant to understand usage scenarios and validation of network behaviors. They provide context for how the system components interact in various BGP scenarios.
- Tools & Scripts: The “tools” directory contains utilities for completion scripts, configuration examples, and integration support (like gRPC client scripts). These help with operational usability and deployment automation.

##### Relationships and Interactions
- The CLI/Application Layer (cmd/gobgp and cmd/gobgpd) initiates and controls operations, invoking the underlying BGP engine.
- The Core BGP Engine (spanning pkg/packet, pkg/server, and internal/pkg/table) maintains BGP sessions, handles message parsing, manages route advertisement, and enforces policies. It interacts with:
- the configuration system (pkg/config) to load and apply settings,
- logging/metrics modules to record activity and performance,
- and the API layer (defined in the “api” folder) to allow programmatic control and status reporting.
- External interfaces, such as gRPC (from pkg/server/grpc_server) and Zebra integration (pkg/zebra), allow the daemon to interact with external management or data-plane components (like the forwarding plane).
- Testing and tools support continuous integration and provide operational enhancements.

##### Important Architectural Patterns/Design Principles
- Layered architecture: Separation of presentation (CLI/API), business logic (BGP state machine, routing engine, policy enforcement), and integration (external systems such as Zebra).
- Modular design: Subdivision into packages (e.g., packet handling, configuration, logging) aids in maintainability and testability.
- Use of protocol buffers and gRPC: This detail indicates a clear API boundary between the BGP daemon and external control applications.
- Extensibility: With dedicated directories for plugins and additional tools (e.g., pyang_plugins for YANG modules), the project is designed to be extendable for future protocol features or integrations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Entry
    subgraph "Application Entry"
        CLI1["gobgp (CLI/Daemon Executable)"]
        CLI2["gobgpd (CLI/Daemon Executable)"]
    end

    %% Core BGP Engine
    subgraph "Core BGP Engine"
        PPM["Packet Processing Module (BGP Protocol)"]
        RT["State Machine & Routing Table"]
    end

    %% Support Modules
    Config["Configuration Manager (pkg/config)"]
    
    subgraph "API & Protobuf Interface"
        APIProto["Protobuf Interface (api definitions)"]
        GRPC["gRPC Server (pkg/server/grpc_server)"]
    end

    subgraph "Observability"
        Logger["Logger (pkg/log)"]
        Metrics["Metrics Module (pkg/metrics)"]
    end

    subgraph "External Integrations"
        Zebra["Zebra Integration"]
        ZClient["ZClient Integration"]
    end

    Tools["Tools & Scripts"]
    TestDoc["Tests & Documentation"]

    %% Connections
    CLI1 -->|"launches"| PPM
    CLI2 -->|"launches"| PPM
    PPM -->|"routes"| RT
    Config -->|"providesConfig"| PPM
    PPM -->|"sendsUpdates"| Logger
    PPM -->|"sendsUpdates"| Metrics
    PPM -->|"exposesDef"| APIProto
    PPM -->|"servesVia"| GRPC
    PPM -->|"integrates"| Zebra
    PPM -->|"integrates"| ZClient
    Tools -->|"supports"| Config
    Tools -->|"supports"| APIProto
    TestDoc -->|"verifies"| PPM

    %% Click Events
    click CLI1 "https://github.com/osrg/gobgp/blob/master/cmd/gobgp/main.go"
    click CLI2 "https://github.com/osrg/gobgp/blob/master/cmd/gobgpd/main.go"
    click PPM "https://github.com/osrg/gobgp/blob/master/pkg/packet/bgp/bgp.go"
    click RT "https://github.com/osrg/gobgp/blob/master/internal/pkg/table/table.go"
    click Config "https://github.com/osrg/gobgp/blob/master/pkg/config/config.go"
    click Logger "https://github.com/osrg/gobgp/blob/master/pkg/log/logger.go"
    click Metrics "https://github.com/osrg/gobgp/blob/master/pkg/metrics/metrics.go"
    click Zebra "https://github.com/osrg/gobgp/blob/master/pkg/zebra/zapi.go"
    click ZClient "https://github.com/osrg/gobgp/blob/master/pkg/server/zclient.go"
    click APIProto "https://github.com/osrg/gobgp/blob/master/api/gobgp.proto"
    click GRPC "https://github.com/osrg/gobgp/blob/master/pkg/server/grpc_server.go"
    click Tools "https://github.com/osrg/gobgp/tree/master/tools/config"
    click TestDoc "https://github.com/osrg/gobgp/tree/master/test/scenario_test"

    %% Styles
    class CLI1,CLI2 cli
    class PPM,RT engine
    class Config tools
    class APIProto,GRPC api
    class Logger logger
    class Metrics metrics
    class Zebra,ZClient external
    class Tools tools
    class TestDoc test

    %% Class Definitions
    classDef cli fill:#8FBC8F,stroke:#333,stroke-width:2px;
    classDef engine fill:#87CEEB,stroke:#333,stroke-width:2px;
    classDef tools fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef api fill:#DA70D6,stroke:#333,stroke-width:2px;
    classDef logger fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef metrics fill:#F0E68C,stroke:#333,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef test fill:#EEE8AA,stroke:#333,stroke-width:2px;
```
