# cloudwego/kitex-benchmark architecture

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

- Interactive diagram: https://gitdiagram.com/cloudwego/kitex-benchmark
- Repository: https://github.com/cloudwego/kitex-benchmark

## Overview

- Code generation for stubs
- Per-protocol server implementations
- Per-protocol client harnesses
- A shared runner/profiling library
- Orchestration scripts that build, launch, measure, and report

##### Main components
a. CodeGen Module (codec/protobuf, codec/thrift)
b. Service Implementations (generic/, grpc/, protobuf/, thrift/, streaming/) – each contains a server
c. Client Harnesses (under each service folder’s client/ subdirectory)
d. Runner & Profiling Core (runner/, perf/) – implements pool, limiter, timer, pprof endpoints
e. Orchestration Scripts (scripts/) – build, launch servers/clients, collect metrics, generate reports
f. Reporting & Output (output/, scripts/reports/, docs/images/)

##### Relationships and data flows
- Build flow
– Scripts → invoke gen_code.sh → produce generated stubs → compile server & client binaries
- Execution flow
– Scripts → start multiple server services (each on its assigned port)
– Scripts → start client processes, which use the runner library to dispatch RPC calls over loopback or network
- Profiling flow
– Servers & clients expose `/debug/pprof` endpoints via perf/
– Scripts or manual pprof tools attach to these ports for CPU/memory profiles
- Reporting flow
– Scripts gather raw logs into `output/*.log` → transform to `*.csv` via reports/to_csv.sh → render graphs via render_images.py

##### Architectural patterns
– Modular, directory-per-protocol pattern
– Shared core library (runner & perf) reused across all services & clients
– Script-driven orchestration: clear separation of build, run, measure, report
– Grouping by transport protocol + message protocol

##### Details
– Label ports (8000–8005 for various services, 18888 for client pprof)
– Denote network boundary (loopback vs. cross-node) if illustrating external-network mode

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration
    Scripts["Orchestration Scripts"]:::scripts
    Scripts -->|dash build & gen_code| CodeGen
    Scripts -->|dash compile servers| Servers
    Scripts -->|dash compile clients| Clients
    Scripts -->|dash launch servers| Servers
    Scripts -->|dash launch clients| Clients
    Scripts -->|dash collect logs| Reporting

    %% CodeGen Module
    subgraph "CodeGen Module"
        direction TB
        GenProto["gen_code.sh (protobuf)"]:::codegen
        GenThrift["gen_code.sh (thrift)"]:::codegen
        KitexGenProto["kitex_gen (protobuf)"]:::codegen
        KitexGenThrift["kitex_gen (thrift)"]:::codegen
    end
    CodeGen["Stub Libraries"]:::codegen
    CodeGen -->|solid stub packages| Servers
    CodeGen -->|solid stub packages| Clients

    %% Server Implementations
    subgraph "Server Implementations"
        direction TB
        Generic["generic/"]:::servers
        Grpc["grpc/"]:::servers
        Protobuf["protobuf/"]:::servers
        Streaming["streaming/"]:::servers
        Thrift["thrift/"]:::servers
    end
    Servers["Services"]:::servers

    %% Client Harnesses
    subgraph "Client Harnesses"
        direction TB
        CGeneric["generic/ client"]:::clients
        CGrpc["grpc/ client"]:::clients
        CProtobuf["protobuf/ client"]:::clients
        CStreaming["streaming/ client"]:::clients
        CThrift["thrift/ client"]:::clients
    end
    Clients["Clients"]:::clients

    %% Runner & Profiling Core
    subgraph "Runner & Perf Core"
        direction TB
        Runner["runner/"]:::core
        Perf["perf/"]:::core
    end
    Servers -->|link runner/perf| Runner
    Clients -->|link runner/perf| Runner
    Servers -->|expose /debug/pprof| Perf
    Clients -->|expose /debug/pprof| Perf

    %% Reporting & Output
    subgraph "Reporting & Output"
        direction TB
        Logs["output/*.log"]:::output
        ToCSV["to_csv.sh"]:::output
        Render["render_images.py"]:::output
        Images["docs/images/"]:::output
    end
    Reporting --> Logs
    Logs --> ToCSV
    ToCSV --> Render
    Render --> Images

    %% Click Events
    click GenProto "https://github.com/cloudwego/kitex-benchmark/blob/main/codec/protobuf/gen_code.sh"
    click GenThrift "https://github.com/cloudwego/kitex-benchmark/blob/main/codec/thrift/gen_code.sh"
    click KitexGenProto "https://github.com/cloudwego/kitex-benchmark/tree/main/codec/protobuf/kitex_gen/"
    click KitexGenThrift "https://github.com/cloudwego/kitex-benchmark/tree/main/codec/thrift/kitex_gen/"
    click Runner "https://github.com/cloudwego/kitex-benchmark/blob/main/runner/runner.go"
    click Perf "https://github.com/cloudwego/kitex-benchmark/blob/main/perf/pprof.go"
    click Scripts "https://github.com/cloudwego/kitex-benchmark/tree/main/scripts/"
    click ToCSV "https://github.com/cloudwego/kitex-benchmark/blob/main/scripts/reports/to_csv.sh"
    click Render "https://github.com/cloudwego/kitex-benchmark/blob/main/scripts/reports/render_images.py"
    click Images "https://github.com/cloudwego/kitex-benchmark/tree/main/docs/images/"

    %% Styles
    classDef codegen fill:#ADD8E6,stroke:#000
    classDef servers fill:#90EE90,stroke:#000
    classDef clients fill:#FFFFE0,stroke:#000
    classDef core fill:#D8BFD8,stroke:#000
    classDef scripts fill:#FFA500,stroke:#000
    classDef output fill:#FFC0CB,stroke:#000
```
