# containerd/ttrpc architecture

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

- Interactive diagram: https://gitdiagram.com/containerd/ttrpc
- Repository: https://github.com/containerd/ttrpc

## Overview

##### Project type and purpose
- This is a Go-based RPC library and toolchain (“ttrpc”) designed to generate and run lightweight RPC services in low-memory environments.
- It includes:
– Two protoc plugins (protoc-gen-go-ttrpc, protoc-gen-gogottrpc) for code generation
– A Go runtime library (client, server, channel, stream, interceptor, metadata, errors) implementing a custom framing protocol
– Example application and integration tests demonstrating usage

##### File structure
Top-level directories and roles:
- cmd/… — CLI tools that register with protoc to generate ttrpc code
- plugin/ — shared code for writing new code-gen plugins
- internal/ — low-level generated pb.go files for tests
- example/ — a sample client/server app using ttrpc
- integration/ — end-to-end streaming tests
- script/ — helpers (e.g., install-protobuf)
- proto/ — shared .proto definitions for status and requests
- root Go files (channel.go, client.go, server.go, etc.) implement the core library

Key configuration and build files:
- Makefile / Protobuild.toml — orchestrate build of .proto → .pb.go and .ttrpc.pb.go
- go.mod / go.sum — module dependencies

##### README for additional insights
- Purpose: reduce dependency on net/http, http2 and grpc package for smaller binaries
- Protocol spec in PROTOCOL.md defines framing, error handling, streaming
- Usage: plug into protoc (or Protobuild) to generate both client and server stubs

- Plugin registration hook (cmd/... → plugin/generator.go)
- Interceptor chain wrapping Channel.Invoke
- Framing protocol layer replacing HTTP/2 in grpc-go
- PROTOCOL.md reference near the transport layer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build-Time Code Generation
    subgraph "Build-Time Code Generation" 
        direction TB
        PROTOS[".proto Definitions"]:::codegen
        PROTOS -->|used by| PROTOC["protoc"]:::external
        PROTOC -->|loads plugins| PLUGINGEN["plugin/generator.go"]:::codegen
        PROTOC -->|loads plugin| PROTOCTTRPC["protoc-gen-go-ttrpc"]:::codegen
        PROTOC -->|loads plugin| PROTOCGOGO["protoc-gen-gogottrpc"]:::codegen
        PROTOC -->|generates| GENCODE["Generated Code (.pb.go, _ttrpc.pb.go)"]:::artifact
    end

    %% Runtime Library
    subgraph "Runtime Library" 
        direction TB
        PROTOCOL["PROTOCOL.md"]:::doc
        CODEC["codec.go"]:::runtime
        PROTOCOL --> CODEC
        CHANNEL["channel.go"]:::runtime
        CLIENT["client.go"]:::runtime
        SERVER["server.go"]:::runtime
        STREAMSUP["stream.go"]:::runtime
        STREAMSRV["stream_server.go"]:::runtime
        INTERCEPT["interceptor.go"]:::runtime
        META["metadata.go"]:::runtime
        ERRORS["errors.go"]:::runtime
        CONFIG["config.go"]:::runtime
        SERVICES["services.go"]:::runtime
        %% Runtime flow
        CLIENT -->|Invoke| INTERCEPT
        INTERCEPT -->|calls| CHANNEL
        CHANNEL -->|dispatch| SERVER
        SERVER -->|routes| SERVICES
        SERVER -->|wrap via| INTERCEPT
        CHANNEL --> CODEC
    end

    %% Application & Tests
    subgraph "Application & Tests"
        direction TB
        EX_PROTO["example/example.proto"]:::app
        EX_PB["example/example.pb.go"]:::artifact
        EX_TTRPC["example/example_ttrpc.pb.go"]:::artifact
        EX_MAIN["example/cmd/main.go"]:::app
        EX_HAND_L["example/cmd/handshaker_linux.go"]:::app
        EX_HAND_O["example/cmd/handshaker_other.go"]:::app
        INT_PROTO["integration/streaming/test.proto"]:::app
        INT_PB["integration/streaming/test.pb.go"]:::artifact
        INT_TTRPC["integration/streaming/test_ttrpc.pb.go"]:::artifact
        INT_TEST["integration/streaming/streaming_test.go"]:::app
        INT_INTERNAL["internal/test.pb.go"]:::artifact
        SCRIPT["script/install-protobuf"]:::app
        %% Application flow
        PROTOS --> EX_PROTO
        EX_PROTO --> EX_PB
        EX_PROTO --> EX_TTRPC
        EX_MAIN -->|imports| GENCODE
        EX_MAIN -->|imports| CLIENT
        INT_PROTO --> INT_PB
        INT_PROTO --> INT_TTRPC
        INT_TEST -->|uses| INT_TTRPC
        SCRIPT -->|setup| PROTOC
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        GOCTX["Go context package"]:::external
        GOGOPROTO["gogo-protobuf runtime"]:::external
        PROTOC
        PROTOBUILD["Protobuild.toml"]:::external
        MAKE["Makefile"]:::external
        GOCTX --> CLIENT
        GOGOPROTO --> GENCODE
        PROTOBUILD --> PROTOC
        MAKE --> PROTOC
    end

    %% Connections
    PROTOS --> PROTOC
    GENCODE -->|compiled with| CLIENT
    GENCODE -->|compiled with| SERVER
    GENCODE -->|used by| EX_MAIN

    %% Click Events
    click PROTOCTTRPC "https://github.com/containerd/ttrpc/tree/main/cmd/protoc-gen-go-ttrpc/"
    click PROTOCGOGO "https://github.com/containerd/ttrpc/tree/main/cmd/protoc-gen-gogottrpc/"
    click PLUGINGEN "https://github.com/containerd/ttrpc/blob/main/plugin/generator.go"
    click CODEC "https://github.com/containerd/ttrpc/blob/main/codec.go"
    click CHANNEL "https://github.com/containerd/ttrpc/blob/main/channel.go"
    click CLIENT "https://github.com/containerd/ttrpc/blob/main/client.go"
    click SERVER "https://github.com/containerd/ttrpc/blob/main/server.go"
    click STREAMSUP "https://github.com/containerd/ttrpc/blob/main/stream.go"
    click STREAMSRV "https://github.com/containerd/ttrpc/blob/main/stream_server.go"
    click INTERCEPT "https://github.com/containerd/ttrpc/blob/main/interceptor.go"
    click META "https://github.com/containerd/ttrpc/blob/main/metadata.go"
    click ERRORS "https://github.com/containerd/ttrpc/blob/main/errors.go"
    click CONFIG "https://github.com/containerd/ttrpc/blob/main/config.go"
    click SERVICES "https://github.com/containerd/ttrpc/blob/main/services.go"
    click PROTOCOL "https://github.com/containerd/ttrpc/blob/main/PROTOCOL.md"
    click GOMOD "https://github.com/containerd/ttrpc/blob/main/go.mod"
    click GOSUM "https://github.com/containerd/ttrpc/blob/main/go.sum"
    click MAKE "https://github.com/containerd/ttrpc/tree/main/Makefile"
    click PROTOBUILD "https://github.com/containerd/ttrpc/blob/main/Protobuild.toml"
    click EX_PROTO "https://github.com/containerd/ttrpc/blob/main/example/example.proto"
    click EX_PB "https://github.com/containerd/ttrpc/blob/main/example/example.pb.go"
    click EX_TTRPC "https://github.com/containerd/ttrpc/blob/main/example/example_ttrpc.pb.go"
    click EX_MAIN "https://github.com/containerd/ttrpc/blob/main/example/cmd/main.go"
    click EX_HAND_L "https://github.com/containerd/ttrpc/blob/main/example/cmd/handshaker_linux.go"
    click EX_HAND_O "https://github.com/containerd/ttrpc/blob/main/example/cmd/handshaker_other.go"
    click INT_PROTO "https://github.com/containerd/ttrpc/blob/main/integration/streaming/test.proto"
    click INT_PB "https://github.com/containerd/ttrpc/blob/main/integration/streaming/test.pb.go"
    click INT_TTRPC "https://github.com/containerd/ttrpc/blob/main/integration/streaming/test_ttrpc.pb.go"
    click INT_TEST "https://github.com/containerd/ttrpc/blob/main/integration/streaming/streaming_test.go"
    click INT_INTERNAL "https://github.com/containerd/ttrpc/blob/main/internal/test.pb.go"
    click PROTO_STATUS "https://github.com/containerd/ttrpc/blob/main/proto/status.proto"
    click PROTO_REQ "https://github.com/containerd/ttrpc/blob/main/proto/request.proto"
    click REQ_PB "https://github.com/containerd/ttrpc/blob/main/proto/request.pb.go"
    click SCRIPT "https://github.com/containerd/ttrpc/tree/main/script/install-protobuf"

    %% Styles
    classDef codegen fill:#D6EFFF,stroke:#0384fc,color:#000;
    classDef runtime fill:#daffd6,stroke:#35b536,color:#000;
    classDef app fill:#fff5b1,stroke:#d4b000,color:#000;
    classDef external fill:#eeeeee,stroke:#999999,color:#000;
    classDef artifact fill:#ffffff,stroke:#6666ff,color:#000,stroke-dasharray: 5 5;
    classDef doc fill:#ffe6e6,stroke:#ff4d4d,color:#000;
```
