# trpc-group/trpc-cpp architecture

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

- Interactive diagram: https://gitdiagram.com/trpc-group/trpc-cpp
- Repository: https://github.com/trpc-group/trpc-cpp

## Overview

##### Project Type and Purpose
- This is a C++ RPC framework (tRPC-Cpp) that provides a layered, plugin-based RPC engine (not a standalone app), intended for embedding into C++ services or clients.
- It is composed of a “framework core” (runtime, transport, RPC) plus a rich plugin ecosystem (protocol codecs, serialization, compressor, naming, config, logging, metrics, tracing, telemetry, tools).

##### File-Structure Analysis
- Top-level: README, docs, examples, tests, third_party, cmake, BUILD/WORKSPACE for Bazel, CMakeLists for CMake.
- “trpc/” directory holds the core engine, subdivided into modules: runtime, transport, rpc, codec, common, filter, overload_control, metrics, naming, serialization, server, client, stream, tools, telemetry, tracing.
- “plugins” are implemented under each module: e.g., trpc/codec/grpc, trpc/codec/http, trpc/serialization/pb, etc.
- Examples under “examples/” show how to drive the framework as a client or server for various protocols.

##### Key README Insights
- Core layers:
- Runtime (thread‐model, io‐model)
- Transport (network I/O, protocol framing)
- RPC (service proxies, handlers, sync/async/stream)
- Admin interface for management.
- Plugin types: protocol codec, serialization, compressor, naming, config, logging, metrics, tracing, telemetry, plus tools (admin, tvar, rpcz).

##### Main Components
- Runtime Layer
- Thread-model (thread, fiber)
- IO-model (reactor for network, async‐io for disk)
- Transport Layer
- Client transport (TCP/UDP/SSL/Unix‐socket)
- Server transport
- Codec manager (selects protocol codec plugin)
- RPC Layer
- Client side: Service proxy, client context, call patterns (sync/future/fiber)
- Server side: Service dispatcher, method handlers (unary, streaming, non-RPC, one-way)
- Admin Interface (over RPC)

- Protocol codecs: trpc, http, grpc, rpcz, flatbuffers_protocol, third-party protocol
- Serialization: pb, flatbuffers, json, noop
- Compression: gzip, zlib, snappy, lz4
- Naming: registry, load balance strategies
- Config: local file, etcd plugin support
- Logging: default, cls plugin
- Metrics: built-in, Prometheus plugin
- Tracing: built-in, Jaeger plugin
- Telemetry: built-in, OpenTelemetry plugin
- Tools: admin service, tvar, rpcz

c. External Systems
- Backends for plugins, e.g., etcd, Prometheus server, Jaeger collector, OpenTelemetry collector, Redis, Polarismesh

##### Relationships & Interactions
- Runtime schedules CPU and IO tasks for Transport and RPC layers.
- Transport uses Runtime to send/receive bytes, then hands off to the codec manager.
- Codec manager invokes a protocol plugin to decode/encode messages.
- RPC layer calls the decoded message into a service handler or constructs a request via the service proxy.
- Admin and tool APIs are just special RPC services running on the same transport.
- Plugins register via factory or plugin manager in common modules.

##### Architectural Patterns
- Layered architecture (Runtime → Transport → RPC).
- Plugin/Factory pattern for codecs, serializers, compressors, naming, config, logging, metrics, tracing, telemetry.
- Reactor/M:N coroutine for concurrency.
- Service Proxy and Service Handler abstractions for decoupling.

##### Final Advice
- Special interactions (e.g., async‐io based on io-uring, fiber vs. thread models).
- Review the official architecture image in docs/images/arch_design.png for inspiration on layout and iconography.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Framework Core
    subgraph "Framework Core"
        direction TB
        subgraph "Runtime Layer"
            direction TB
            Runtime["Runtime"]:::runtime
            ThreadModel["Thread-model\n(thread, fiber)"]:::runtime
            IOModel["IO-model\n(reactor, async-io)"]:::runtime
            Runtime --> ThreadModel
            Runtime --> IOModel
        end

        subgraph "Transport Layer"
            direction TB
            Transport["Transport"]:::transport
            ClientTrans["Client transport\n(TCP/UDP/SSL/Unix)"]:::transport
            ServerTrans["Server transport"]:::transport
            CodecMgr["Codec manager"]:::transport
            Transport --> ClientTrans
            Transport --> ServerTrans
            Transport --> CodecMgr
        end

        subgraph "RPC Layer"
            direction TB
            RPCClient["RPC Client\n(service proxy, context)"]:::rpc
            RPCServer["RPC Server\n(dispatcher, handlers)"]:::rpc
            AdminSvc["Admin Interface"]:::rpc
            RPCClient --> RPCServer
            RPCServer --> AdminSvc
        end

        %% Plugin Manager in common
        PluginMgr["Plugin Manager\n(factory registry)"]:::common
        CodecMgr --> PluginMgr
        RPCServer --> PluginMgr
        RPCClient --> PluginMgr
    end

    %% Plugins
    subgraph "Plugins"
        direction TB
        subgraph "Protocol Codecs" 
            direction TB
            Codecs["Protocol Codecs\n(trpc, http, grpc, rpcz, flatbuffers)"]:::plugin
        end
        subgraph "Serialization"
            direction TB
            Ser["Serialization\n(pb, flatbuffers, json, noop)"]:::plugin
        end
        subgraph "Compression"
            direction TB
            Comp["Compression\n(gzip, zlib, snappy, lz4)"]:::plugin
        end
        subgraph "Naming"
            direction TB
            Naming["Naming\n(registry, load-balance)"]:::plugin
        end
        subgraph "Config"
            direction TB
            Config["Config\n(file, etcd)"]:::plugin
        end
        subgraph "Logging"
            direction TB
            Log["Logging\n(default, cls)"]:::plugin
        end
        subgraph "Metrics"
            direction TB
            Metrics["Metrics\n(built-in, Prometheus)"]:::plugin
        end
        subgraph "Tracing"
            direction TB
            Tracing["Tracing\n(built-in, Jaeger)"]:::plugin
        end
        subgraph "Telemetry"
            direction TB
            Telemetry["Telemetry\n(built-in, OpenTelemetry)"]:::plugin
        end
        subgraph "Tools"
            direction TB
            Tools["Tools\n(admin, tvar, rpcz)"]:::plugin
        end
    end

    %% External Systems
    etcd["etcd"]:::external
    Prometheus["Prometheus"]:::external
    Jaeger["Jaeger"]:::external
    OTEL["OpenTelemetry\nCollector"]:::external
    Redis["Redis"]:::external
    Polarismesh["Polarismesh"]:::external

    %% Data Flow Arrows
    Runtime -->|sends/receives bytes| Transport
    Transport -->|frames bytes| RPCServer
    RPCClient -->|invokes| Transport
    RPCServer -->|handles| Runtime

    %% Plugin Hooks
    Transport -->|uses| Codecs
    Transport -->|uses| Ser
    Transport -->|uses| Comp
    RPCClient -->|uses| Naming
    RPCClient -->|uses| Config
    RPCServer -->|uses| Naming
    RPCServer -->|uses| Config
    RPCServer -->|uses| Log
    RPCServer -->|uses| Metrics
    RPCServer -->|uses| Tracing
    RPCServer -->|uses| Telemetry
    AdminSvc -->|uses| Tools

    %% External to Plugins
    etcd -->|backend| Config
    Prometheus -->|backend| Metrics
    Jaeger -->|backend| Tracing
    OTEL -->|backend| Telemetry
    Redis -->|backend| Naming
    Polarismesh -->|backend| Naming

    %% Click Events
    click Runtime "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/runtime"
    click Transport "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/transport"
    click RPCClient "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/client"
    click RPCServer "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/server"
    click AdminSvc "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/admin"
    click Codecs "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/codec"
    click Ser "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/serialization"
    click Comp "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/compressor"
    click Naming "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/naming"
    click Config "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/config"
    click Log "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/log"
    click Metrics "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/metrics"
    click Tracing "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/tracing"
    click Telemetry "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/telemetry"
    click Tools "https://github.com/trpc-group/trpc-cpp/tree/main/trpc/tools"

    %% Styles
    classDef runtime fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef transport fill:#f5c6cb,stroke:#721c24,color:#721c24;
    classDef rpc fill:#f1b0b7,stroke:#721c24,color:#721c24;
    classDef plugin fill:#cce5ff,stroke:#004085,color:#004085;
    classDef external fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
    classDef common fill:#fff3cd,stroke:#856404,color:#856404;
```
