# grpc/grpc-go architecture

> Architecture diagram of the GitHub repository grpc/grpc-go, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grpc/grpc-go
- Repository: https://github.com/grpc/grpc-go

## Overview

gRPC-Go is a Go RPC framework. Its main workflow is a client issuing an RPC through connection setup and load balancing to an HTTP/2 transport, where a server dispatches it to a registered service and returns a response. The repository also provides xDS-based client and server configuration, authorization, observability, and administrative services. The graph emphasizes those product stages; unsampled implementation links are omitted or marked dashed rather than inferred from package names.

Main entry points: [`server.go`](https://github.com/grpc/grpc-go/blob/master/server.go) (gRPC Server), [`clientconn.go`](https://github.com/grpc/grpc-go/blob/master/clientconn.go) (Client Connection), [`internal/transport/http2_client.go`](https://github.com/grpc/grpc-go/blob/master/internal/transport/http2_client.go) (Client HTTP/2), [`xds/server.go`](https://github.com/grpc/grpc-go/blob/master/xds/server.go) (xDS Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rpc["RPC Runtime"]
  node_client["RPC Client<br/>[call.go]"]
  node_connection["Client Connection<br/>[clientconn.go]"]
  node_clienttransport["Client HTTP/2<br/>[http2_client.go]"]
  node_server["gRPC Server<br/>[server.go]"]
  node_servertransport["Server Transport<br/>[handler_server.go]"]
  node_encoding["Message Encoding<br/>[encoding.go]"]
  node_service["Interop Service<br/>[server.go]"]
end

subgraph group_control["Discovery and Routing"]
  node_resolver["Name Resolver<br/>[resolver.go]"]
  node_balancer["Load Balancers<br/>[balancer.go]"]
end

subgraph group_xds["xDS and Security"]
  node_xdsserver["xDS Server<br/>[server.go]"]
  node_xdsside["xDS Server Routing"]
  node_dependency["xDS Dependencies"]
  node_xdsclient["xDS Client"]
  node_rbac["RBAC Engine<br/>[rbac_engine.go]"]
  node_authz["Server Authorization"]
end

subgraph group_ops["Operations and Telemetry"]
  node_health["Health Service<br/>[server.go]"]
  node_admin["Admin Services<br/>[admin.go]"]
  node_stats["Stats Handlers<br/>[handlers.go]"]
  node_otel["OpenTelemetry<br/>[opentelemetry.go]"]
end

node_caller(("Application Caller"))
node_network(("HTTP/2 Peer"))
node_management(("xDS Management"))

node_caller -.->|"invokes"| node_client
node_connection -.->|"resolves names"| node_resolver
node_connection -.->|"selects policy"| node_balancer
node_client -.->|"uses connection"| node_connection
node_clienttransport -.->|"exchanges frames"| node_network
node_server -->|"serves transport"| node_servertransport
node_server -->|"combines handlers"| node_stats
node_service -->|"registers service"| node_server
node_xdsserver -->|"delegates routing"| node_xdsside
node_dependency -->|"watches resources"| node_xdsclient
node_dependency -->|"builds DNS resolver"| node_resolver
node_xdsserver -.->|"communicates xDS"| node_management
node_server -.->|"registers optionally"| node_health
node_server -.->|"registers optionally"| node_admin
node_rbac -.->|"authorizes RPCs"| node_network
node_otel -.->|"records telemetry"| node_stats
node_encoding -.->|"encodes messages"| node_clienttransport
node_clienttransport -.->|"serves RPC calls"| node_connection

click node_client "https://github.com/grpc/grpc-go/blob/master/call.go"
click node_connection "https://github.com/grpc/grpc-go/blob/master/clientconn.go"
click node_resolver "https://github.com/grpc/grpc-go/blob/master/resolver/resolver.go"
click node_balancer "https://github.com/grpc/grpc-go/blob/master/balancer/balancer.go"
click node_clienttransport "https://github.com/grpc/grpc-go/blob/master/internal/transport/http2_client.go"
click node_server "https://github.com/grpc/grpc-go/blob/master/server.go"
click node_servertransport "https://github.com/grpc/grpc-go/blob/master/internal/transport/handler_server.go"
click node_encoding "https://github.com/grpc/grpc-go/blob/master/encoding/encoding.go"
click node_service "https://github.com/grpc/grpc-go/blob/master/interop/server/server.go"
click node_xdsserver "https://github.com/grpc/grpc-go/blob/master/xds/server.go"
click node_xdsside "https://github.com/grpc/grpc-go/tree/master/internal/xds/server"
click node_dependency "https://github.com/grpc/grpc-go/blob/master/internal/xds/xdsdepmgr/xds_dependency_manager.go"
click node_xdsclient "https://github.com/grpc/grpc-go/tree/master/internal/xds/xdsclient"
click node_rbac "https://github.com/grpc/grpc-go/blob/master/internal/xds/rbac/rbac_engine.go"
click node_authz "https://github.com/grpc/grpc-go/blob/master/authz/grpc_authz_server_interceptors.go"
click node_health "https://github.com/grpc/grpc-go/blob/master/health/server.go"
click node_admin "https://github.com/grpc/grpc-go/blob/master/admin/admin.go"
click node_stats "https://github.com/grpc/grpc-go/blob/master/stats/handlers.go"
click node_otel "https://github.com/grpc/grpc-go/blob/master/stats/opentelemetry/opentelemetry.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_connection,node_clienttransport,node_server,node_servertransport,node_encoding,node_service toneBlue
class node_resolver,node_balancer toneAmber
class node_xdsserver,node_xdsside,node_dependency,node_xdsclient,node_rbac,node_authz toneMint
class node_health,node_admin,node_stats,node_otel toneRose
class node_caller,node_network,node_management toneIndigo
```

## Components

### RPC Runtime

- [RPC Client](https://github.com/grpc/grpc-go/blob/master/call.go): `call.go`
- [Client Connection](https://github.com/grpc/grpc-go/blob/master/clientconn.go): `clientconn.go`
- [Client HTTP/2](https://github.com/grpc/grpc-go/blob/master/internal/transport/http2_client.go): `internal/transport/http2_client.go`
- [gRPC Server](https://github.com/grpc/grpc-go/blob/master/server.go): `server.go`
- [Server Transport](https://github.com/grpc/grpc-go/blob/master/internal/transport/handler_server.go): `internal/transport/handler_server.go`
- [Message Encoding](https://github.com/grpc/grpc-go/blob/master/encoding/encoding.go): `encoding/encoding.go`
- [Interop Service](https://github.com/grpc/grpc-go/blob/master/interop/server/server.go): `interop/server/server.go`

### Discovery and Routing

- [Name Resolver](https://github.com/grpc/grpc-go/blob/master/resolver/resolver.go): `resolver/resolver.go`
- [Load Balancers](https://github.com/grpc/grpc-go/blob/master/balancer/balancer.go): `balancer/balancer.go`

### xDS and Security

- [xDS Server](https://github.com/grpc/grpc-go/blob/master/xds/server.go): `xds/server.go`
- [xDS Server Routing](https://github.com/grpc/grpc-go/tree/master/internal/xds/server): `internal/xds/server`
- [xDS Dependencies](https://github.com/grpc/grpc-go/blob/master/internal/xds/xdsdepmgr/xds_dependency_manager.go): `internal/xds/xdsdepmgr/xds_dependency_manager.go`
- [xDS Client](https://github.com/grpc/grpc-go/tree/master/internal/xds/xdsclient): `internal/xds/xdsclient`
- [RBAC Engine](https://github.com/grpc/grpc-go/blob/master/internal/xds/rbac/rbac_engine.go): `internal/xds/rbac/rbac_engine.go`
- [Server Authorization](https://github.com/grpc/grpc-go/blob/master/authz/grpc_authz_server_interceptors.go): `authz/grpc_authz_server_interceptors.go`

### Operations and Telemetry

- [Health Service](https://github.com/grpc/grpc-go/blob/master/health/server.go): `health/server.go`
- [Admin Services](https://github.com/grpc/grpc-go/blob/master/admin/admin.go): `admin/admin.go`
- [Stats Handlers](https://github.com/grpc/grpc-go/blob/master/stats/handlers.go): `stats/handlers.go`
- [OpenTelemetry](https://github.com/grpc/grpc-go/blob/master/stats/opentelemetry/opentelemetry.go): `stats/opentelemetry/opentelemetry.go`

### Other components

- **Application Caller**
- **HTTP/2 Peer**
- **xDS Management**

## Connections

- Application Caller → RPC Client: invokes
- Client Connection → Name Resolver: resolves names
- Client Connection → Load Balancers: selects policy
- RPC Client → Client Connection: uses connection
- Client HTTP/2 → HTTP/2 Peer: exchanges frames
- gRPC Server → Server Transport: serves transport (evidence: `server.go`)
- gRPC Server → Stats Handlers: combines handlers (evidence: `server.go`)
- Interop Service → gRPC Server: registers service (evidence: `interop/server/server.go`)
- xDS Server → xDS Server Routing: delegates routing (evidence: `xds/server.go`)
- xDS Dependencies → xDS Client: watches resources (evidence: `internal/xds/xdsdepmgr/xds_dependency_manager.go`)
- xDS Dependencies → Name Resolver: builds DNS resolver (evidence: `internal/xds/xdsdepmgr/xds_dependency_manager.go`)
- xDS Server → xDS Management: communicates xDS
- gRPC Server → Health Service: registers optionally
- gRPC Server → Admin Services: registers optionally
- RBAC Engine → HTTP/2 Peer: authorizes RPCs
- OpenTelemetry → Stats Handlers: records telemetry
- Message Encoding → Client HTTP/2: encodes messages
- Client HTTP/2 → Client Connection: serves RPC calls
