# apache/brpc architecture

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

- Interactive diagram: https://gitdiagram.com/apache/brpc
- Repository: https://github.com/apache/brpc

## Overview

##### File Structure Analysis

- **Top-Level Directories and Files:**
- **`src/`**: Contains the core source code for bRPC, including `brpc`, `bthread`, `butil`, and `bvar` components.
- **`example/`**: Provides various examples demonstrating the usage of bRPC in different scenarios.
- **`docs/`**: Documentation files in both Chinese (`cn`) and English (`en`) languages.
- **`test/`**: Contains unit tests and fuzzing tests for different components.
- **`tools/`**: Utility tools related to bRPC, such as `rpc_press`, `rpc_replay`, and `rpc_view`.
- **Configuration and Build Files**: Includes `CMakeLists.txt`, `Makefile`, `BUILD.bazel`, and GitHub workflow configurations under `.github/`.

- **Architectural Patterns:**
- The presence of directories like `brpc`, `bthread`, `butil`, and `bvar` suggests a modular architecture with clear separation of concerns.
- Use of **Bazel** (`BUILD.bazel`, `MODULE.bazel`) indicates a build system optimized for large-scale C++ projects.
- **Microservices Support**: Multiple example services and protocol support imply a design catering to distributed systems and microservices architecture.

##### README Insights

The README highlights that bRPC is capable of:
- Handling multiple protocols on the same port.
- Providing synchronous and asynchronous server and client interfaces.
- Extensibility for custom protocols and components.
- High-performance features like threading, memory management, and load balancing.
- Integrated tools for benchmarking, profiling, and monitoring.

To accurately represent bRPC's architecture, follow these steps:

**a. Identify Main Components:**
- **Core Libraries:**
- **brpc**: Core RPC framework handling request routing, protocol management, and service definitions.
- **bthread**: Provides threading capabilities optimized for performance and concurrency.
- **butil**: Utility library offering functionalities like memory management, synchronization primitives, and data structures.
- **bvar**: Metrics and variable management for monitoring and tuning.

- **Protocols Supported:**
- **HTTP/HTTPS**, **gRPC**, **Thrift**, **Redis**, **Memcached**, **RTMP**, **HLS**, etc.

- **Server Components:**
- **Built-in Services**: Status, Vars, Connections, Flags, RPCZ, Profilers.
- **Custom Services**: User-defined services using various protocols.

- **Client Components:**
- Synchronous, Asynchronous, Semi-Synchronous Calls.
- Combo Channels for sharding and parallel access.

- **Tools and Utilities:**
- **rpc_press**: Benchmarking tool.
- **rpc_replay**: Request replay tool.
- **rpc_view**: Monitoring tool.

- **Testing Components:**
- Unit tests, Integration tests, Fuzzing tests.

**b. Determine Relationships and Interactions:**
- **brpc** interacts closely with **bthread** for managing concurrency and with **butil** for utility functions.
- **Clients** use **bthread** for handling asynchronous operations and **butil** for networking and data manipulation.
- **Servers** leverage **brpc** to expose services over supported protocols, utilizing **bthread** and **butil** for processing requests.
- **bvar** collects metrics from both clients and servers for monitoring purposes.
- **Tools** interact with both clients and servers to perform benchmarking, replaying requests, and monitoring.

**c. Highlight Architectural Patterns and Design Principles:**
- **Modular Architecture**: Clear separation between core libraries, protocols, and tools.
- **Extensibility**: Ability to add new protocols and services without altering core components.
- **Concurrency Management**: Efficient threading model using **bthread** to handle high-load scenarios.
- **Performance Optimization**: Use of optimized data structures and memory management in **butil**.
- **Monitoring and Profiling**: Integrated metrics collection and profiling tools via **bvar**.
- **Protocol Agnosticism**: Support for multiple protocols allows flexibility in service communication.

**d. Include Relevant Technologies, Frameworks, or Libraries:**
- **C++ Language**: Primary language for implementation.
- **Bazel Build System**: For scalable and efficient building of the project.
- **CMake and Make**: Alternative build systems for flexibility.
- **gRPC, Thrift**: Supported RPC frameworks.
- **Redis, Memcached**: Supported key-value store protocols.
- **HTTP/HTTPS, RTMP, HLS**: Supported communication protocols.
- **RAFT Consensus Algorithm**: Implemented in **braft** for high availability.
- **Profiling Tools**: Integrated CPU, heap, and contention profilers.

##### Core Layer
- **brpc** ↔ **bthread**
- **brpc** ↔ **butil**
- **brpc** ↔ **bvar**

##### Protocols Layer
- **brpc** supports:
- **HTTP/HTTPS**
- **gRPC**
- **Thrift**
- **Redis**
- **Memcached**
- **RTMP**
- **HLS**
- **Custom Protocols**

##### Client-Server Interaction
- **Clients**:
- Synchronous Calls
- Asynchronous Calls
- Combo Channels
- **Servers**:
- Synchronous Services
- Asynchronous Services
- Multi-Protocol Handling

##### Extensibility
- **Plugin Interfaces**
- **Custom Protocol Integration Points**

##### Monitoring and Profiling
- **bvar** collects metrics from **brpc**, **bthread**, and **butil**
- **Built-in Services** provide access to metrics and profiling data

##### Tools Integration
- **rpc_press** ↔ **Clients/Servers**
- **rpc_replay** ↔ **Servers**
- **rpc_view** ↔ **Monitoring Services**

## Diagram (Mermaid)

```mermaid
flowchart TD 
    %% Global entities

    %% Subgraphs and modules

    %% Core Libraries
    subgraph "Core Libraries"
        brpc["brpc"]:::core
        bthread["bthread"]:::core
        butil["butil"]:::core
        bvar["bvar"]:::monitoring
    end

    %% Protocols
    subgraph "Protocols"
        HTTP["HTTP/HTTPS"]:::protocol
        gRPC["gRPC"]:::protocol
        Thrift["Thrift"]:::protocol
        Redis["Redis"]:::protocol
        Memcached["Memcached"]:::protocol
        RTMP["RTMP"]:::protocol
        HLS["HLS"]:::protocol
        Custom["Custom Protocols"]:::protocol
    end

    %% Built-in Services
    subgraph "Built-in Services"
        Status_Service["Status Service"]:::service
        Vars_Service["Vars Service"]:::service
        Connections_Service["Connections Service"]:::service
        Flags_Service["Flags Service"]:::service
        RPCZ_Service["RPCZ Service"]:::service
        Profilers_Service["Profilers Service"]:::service
    end

    %% Client-Server Interaction
    subgraph "Client-Server Interaction"
        Clients["Clients"]:::client
        Servers["Servers"]:::server
        SyncAsync_Client["Synchronous & Asynchronous Interfaces"]:::client_interface
        Combo_Channel["Combo Channels"]:::client_interface
    end

    %% Extensibility
    subgraph "Extensibility"
        Plugin_Interfaces["Plugin Interfaces"]:::extensibility
        Custom_Protocol_Points["Custom Protocol Integration Points"]:::extensibility
    end

    %% Monitoring and Profiling
    subgraph "Monitoring & Profiling"
        bvar --> brpc
        bvar --> bthread
        bvar --> butil
    end

    %% Tools Integration
    subgraph "Tools"
        rpc_press["rpc_press"]:::tool
        rpc_replay["rpc_replay"]:::tool
        rpc_view["rpc_view"]:::tool
    end

    %% Testing Components
    Testing["Testing Components"]:::testing

    %% Example Services
    Examples["Example Services"]:::examples

    %% Documentation
    subgraph "Documentation"
        Docs_EN["docs/en/"]:::docs
        Docs_CN["docs/cn/"]:::docs
    end

    %% Build Systems
    subgraph "Build Systems"
        Bazel["Bazel"]:::build
        CMake["CMake"]:::build
        Make["Make"]:::build
    end

    %% Configuration and Workflow
    subgraph "Configuration & Workflow"
        GitHub[".github/"]:::config
        WORKSPACE["WORKSPACE"]:::config
        Module_Bazel["MODULE.bazel"]:::config
    end

    %% Connections
    brpc --> bthread
    brpc --> butil
    brpc --> bvar

    brpc --> HTTP
    brpc --> gRPC
    brpc --> Thrift
    brpc --> Redis
    brpc --> Memcached
    brpc --> RTMP
    brpc --> HLS
    brpc --> Custom

    brpc --> Status_Service
    brpc --> Vars_Service
    brpc --> Connections_Service
    brpc --> Flags_Service
    brpc --> RPCZ_Service
    brpc --> Profilers_Service

    Clients --> SyncAsync_Client
    Clients --> Combo_Channel
    Clients --> brpc

    Servers --> brpc

    Plugin_Interfaces --> Custom_Protocol_Points

    rpc_press --> Clients
    rpc_replay --> Servers
    rpc_view --> Servers

    Testing --> brpc
    Testing --> bthread
    Testing --> butil
    Testing --> bvar

    Examples --> brpc

    Docs_EN --> brpc
    Docs_CN --> brpc

    Bazel --> brpc
    CMake --> brpc
    Make --> brpc

    GitHub --> brpc
    WORKSPACE --> brpc
    Module_Bazel --> brpc

    %% Click Events
    click brpc "https://github.com/apache/brpc/tree/master/src/brpc/"
    click bthread "https://github.com/apache/brpc/tree/master/src/bthread/"
    click butil "https://github.com/apache/brpc/tree/master/src/butil/"
    click bvar "https://github.com/apache/brpc/tree/master/src/bvar/"
    
    click HTTP "https://github.com/apache/brpc/blob/master/src/brpc/policy/http_rpc_protocol.cpp"
    click HTTP "https://github.com/apache/brpc/blob/master/src/brpc/policy/http_rpc_protocol.h"
    click gRPC "https://github.com/apache/brpc/blob/master/src/brpc/policy/grpc_protocol.cpp"
    click gRPC "https://github.com/apache/brpc/blob/master/src/brpc/policy/grpc_protocol.h"
    click Thrift "https://github.com/apache/brpc/blob/master/src/brpc/policy/thrift_protocol.cpp"
    click Thrift "https://github.com/apache/brpc/blob/master/src/brpc/policy/thrift_protocol.h"
    click Redis "https://github.com/apache/brpc/blob/master/src/brpc/policy/redis_protocol.cpp"
    click Redis "https://github.com/apache/brpc/blob/master/src/brpc/policy/redis_protocol.h"
    click Memcached "https://github.com/apache/brpc/blob/master/src/brpc/policy/memcache_binary_protocol.cpp"
    click Memcached "https://github.com/apache/brpc/blob/master/src/brpc/policy/memcache_binary_protocol.h"
    click RTMP "https://github.com/apache/brpc/blob/master/src/brpc/policy/rtmp_protocol.cpp"
    click RTMP "https://github.com/apache/brpc/blob/master/src/brpc/policy/rtmp_protocol.h"
    
    click Status_Service "https://github.com/apache/brpc/blob/master/src/brpc/builtin/status_service.cpp"
    click Status_Service "https://github.com/apache/brpc/blob/master/src/brpc/builtin/status_service.h"
    click Vars_Service "https://github.com/apache/brpc/blob/master/src/brpc/builtin/vars_service.cpp"
    click Vars_Service "https://github.com/apache/brpc/blob/master/src/brpc/builtin/vars_service.h"
    click Connections_Service "https://github.com/apache/brpc/blob/master/src/brpc/builtin/connections_service.cpp"
    click Connections_Service "https://github.com/apache/brpc/blob/master/src/brpc/builtin/connections_service.h"
    click Flags_Service "https://github.com/apache/brpc/blob/master/src/brpc/builtin/flags_service.cpp"
    click Flags_Service "https://github.com/apache/brpc/blob/master/src/brpc/builtin/flags_service.h"
    click RPCZ_Service "https://github.com/apache/brpc/blob/master/src/brpc/builtin/rpcz_service.cpp"
    click RPCZ_Service "https://github.com/apache/brpc/blob/master/src/brpc/builtin/rpcz_service.h"
    click Profilers_Service "https://github.com/apache/brpc/blob/master/src/brpc/builtin/pprof_service.cpp"
    click Profilers_Service "https://github.com/apache/brpc/blob/master/src/brpc/builtin/pprof_service.h"
    
    click SyncAsync_Client "https://github.com/apache/brpc/blob/master/src/brpc/channel.cpp"
    click SyncAsync_Client "https://github.com/apache/brpc/blob/master/src/brpc/channel.h"
    click Combo_Channel "https://github.com/apache/brpc/blob/master/src/brpc/parallel_channel.cpp"
    click Combo_Channel "https://github.com/apache/brpc/blob/master/src/brpc/parallel_channel.h"
    
    click rpc_press "https://github.com/apache/brpc/tree/master/tools/rpc_press/"
    click rpc_replay "https://github.com/apache/brpc/tree/master/tools/rpc_replay/"
    click rpc_view "https://github.com/apache/brpc/tree/master/tools/rpc_view/"
    
    click Testing "https://github.com/apache/brpc/tree/master/test/"
    
    click Examples "https://github.com/apache/brpc/tree/master/example/"
    
    click Docs_EN "https://github.com/apache/brpc/tree/master/docs/en/"
    click Docs_CN "https://github.com/apache/brpc/tree/master/docs/cn/"
    
    click Bazel "https://github.com/apache/brpc/blob/master/BUILD.bazel"
    click CMake "https://github.com/apache/brpc/blob/master/CMakeLists.txt"
    click Make "https://github.com/apache/brpc/tree/master/Makefile"
    
    click GitHub "https://github.com/apache/brpc/tree/master/.github/"
    click WORKSPACE "https://github.com/apache/brpc/tree/master/WORKSPACE"
    click Module_Bazel "https://github.com/apache/brpc/blob/master/MODULE.bazel"
    
    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:2px
    classDef monitoring fill:#ff9,stroke:#333,stroke-width:2px
    classDef protocol fill:#ccf,stroke:#333,stroke-width:2px
    classDef service fill:#cfc,stroke:#333,stroke-width:2px
    classDef client fill:#fcf,stroke:#333,stroke-width:2px
    classDef server fill:#cff,stroke:#333,stroke-width:2px
    classDef client_interface fill:#ccf,stroke:#333,stroke-width:2px
    classDef tool fill:#f6f,stroke:#333,stroke-width:2px
    classDef testing fill:#faa,stroke:#333,stroke-width:2px
    classDef examples fill:#aaf,stroke:#333,stroke-width:2px
    classDef docs fill:#afa,stroke:#333,stroke-width:2px
    classDef build fill:#aaf,stroke:#333,stroke-width:2px
    classDef config fill:#fea,stroke:#333,stroke-width:2px
```
