# netsys/bess architecture

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

- Interactive diagram: https://gitdiagram.com/netsys/bess
- Repository: https://github.com/netsys/bess

## Overview

##### Main Components
- Data Plane Core (Packet Processing):
– Represent the “core” directory which houses the main engine including modules, drivers, packet, port, scheduler, memory management, and dpdk integration.
– Highlight the multiple module implementations (files in core/modules) that operate as the building blocks for the packet processing pipeline.
- Control Plane and Configuration:
– Include the “bessctl” directory as the primary CLI tool for controlling and configuring the datapath. It contains the CLI interface (cli.py), commands (commands.py), and configuration scripts that allow external controllers or administrators to build and modify pipelines.
– The “pybess” directory also represents programmable interfaces for Python, which users can use to interact with BESS.
- Configuration Scripts and Samples:
– Show the “conf” directories under bessctl that include metadata (e.g., test*.bess) and sample configurations (samples, perftest, port, etc.).
– Don’t forget the “sample_plugin” directory, which illustrates how users can extend functionality via plugins and custom modules.
- Kernel Module and Lower-level Interfaces:
– Represent the “core/kmod” directory, which deals with the kernel module for handling high-performance I/O and connection with network interfaces.
- External Dependencies, Build, and Deployment:
– Mark the build scripts (build.py, container_build.py), CI configuration files (.travis.yml, codecov.yml), and Docker/Vagrant files in the “env” directory.
– Include the integration of DPDK and other driver-level components (core/drivers and related files).

##### Relationships and Data Flow
- Dependency of custom modules (from core/modules, sample_plugin) on the central packet processing engine.
- Interactions between user-supplied configurations (in conf/) and the instantiation of module objects in the core subsystems.
- Role of the Python interface (pybess) as a higher-level abstraction layer interfacing with the core.

##### Architectural Patterns and Design Principles
- Modular design – every packet processing element is a “module” (a concept similar to the Click modular router).
- Separation of concerns:
– Data Plane (core) is highly optimized for performance.
– Control Plane (bessctl, pybess) handles configuration and management.
- Extensibility via sample plugins and custom modules that allow users to plug in new functionality.
- Clear delineation between user-space and kernel-space components (e.g., “core/kmod” for kernel module, “core/drivers” for hardware interface).

##### Relevant Technologies and Frameworks
- Mention DPDK (as seen in dpdk.cc and dpdk.h) for fast packet I/O.
- Use of kernel modules and low-level C/C++ modules in the “core” directory.
- That the control plane uses Python (pybess, bessctl) and that configuration leverages protocol buffers (protobuf/ directory).

- This to a central Data Plane component (core) where packet processing occurs through a series of interconnected modules.
- Configuration & Plug-in area as a component that feeds into both the control and data planes, highlighting the “conf” and “sample_plugin” directories.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Control Plane"
        BESS_CLI("BESS CLI (bessctl)"):::control
        PYTHON_API("Python API (pybess)"):::control
        CONF_SCRIPTS("Configuration Scripts (bessctl/conf)"):::control
    end

    subgraph "Data Plane"
        DATA_PLANE("Data Plane Engine (core)"):::dataplane
        PACKET_MODULES("Packet Modules (core/modules)"):::dataplane
        SAMPLE_PLUGIN("Sample Plugin Extension (sample_plugin)"):::dataplane
        KERNEL_MODULE("Kernel Module Interface (core/kmod)"):::dataplane
        HW_DRIVER("Hardware Driver Integration (core/drivers)"):::dataplane
    end

    subgraph "Build & Deployment"
        BUILD_DEPLOY("Build & Deployment (env)"):::external
        BUILD_PY("Build Script (build.py)"):::external
        CONTAINER_BUILD("Container Build (container_build.py)"):::external
    end

    %% Control Plane Relationships
    CONF_SCRIPTS -->|"sends_config"| BESS_CLI
    BESS_CLI -->|"config_command"| DATA_PLANE
    PYTHON_API -->|"API_command"| DATA_PLANE

    %% Data Plane Internal Relationships
    SAMPLE_PLUGIN -->|"extends"| DATA_PLANE
    DATA_PLANE -->|"processes_packets"| PACKET_MODULES
    DATA_PLANE -->|"kernel_interact"| KERNEL_MODULE
    DATA_PLANE -->|"driver_interact"| HW_DRIVER

    %% Build & Deployment Relationships
    BUILD_PY -->|"trigger_build"| BUILD_DEPLOY
    CONTAINER_BUILD -->|"trigger_deploy"| BUILD_DEPLOY
    BUILD_DEPLOY -->|"deployed_to"| DATA_PLANE

    %% Click Events
    click BESS_CLI "https://github.com/netsys/bess/tree/master/bessctl/"
    click PYTHON_API "https://github.com/netsys/bess/tree/master/pybess/"
    click CONF_SCRIPTS "https://github.com/netsys/bess/tree/master/bessctl/conf/"
    click DATA_PLANE "https://github.com/netsys/bess/tree/master/core/"
    click PACKET_MODULES "https://github.com/netsys/bess/tree/master/core/modules/"
    click SAMPLE_PLUGIN "https://github.com/netsys/bess/tree/master/sample_plugin/"
    click KERNEL_MODULE "https://github.com/netsys/bess/tree/master/core/kmod/"
    click HW_DRIVER "https://github.com/netsys/bess/tree/master/core/drivers/"
    click BUILD_DEPLOY "https://github.com/netsys/bess/tree/master/env/"
    click BUILD_PY "https://github.com/netsys/bess/blob/master/build.py"
    click CONTAINER_BUILD "https://github.com/netsys/bess/blob/master/container_build.py"

    %% Styles
    classDef control fill:#ffdead,stroke:#333,stroke-width:2px;
    classDef dataplane fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef external fill:#90ee90,stroke:#333,stroke-width:2px;
```
