# centrifugal/centrifugo architecture

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

- Interactive diagram: https://gitdiagram.com/centrifugal/centrifugo
- Repository: https://github.com/centrifugal/centrifugo

## Overview

#### Purpose and entry points
Centrifugo is a Go real-time PUB/SUB server: application backends publish or manage subscriptions through HTTP/gRPC APIs; connected clients receive channel traffic over WebSocket, HTTP streaming, SSE, gRPC, or experimental WebTransport. Process startup is `main.go`, with CLI command wiring in `internal/app/cmd.go` and server lifecycle assembly in `internal/app/run.go`.

#### Bootstrap, configuration, and server composition
The `serve` command loads, migrates, and validates configuration, then constructs shared dependencies and listeners. `internal/app/engine.go` owns the central real-time engine integration; `internal/app/mux.go` composes HTTP routes/transports; `internal/app/grpc.go` configures gRPC; `internal/config/config.go` and `internal/config/validate.go` define the configuration boundary. TLS, origins, logging, telemetry, brokers, and optional services are configured before serving.

#### Client connection and transport boundary
Client traffic enters transport-specific adapters which normalize it into common connection/session behavior. Bidirectional WebSocket is implemented under `internal/websocket/`; unidirectional HTTP-streaming, SSE, gRPC, and WebTransport adapters are respectively `internal/unihttpstream/transport.go`, `internal/unisse/transport.go`, `internal/unigrpc/transport.go`, and `internal/wt/transport.go`. `internal/client/client.go` and `internal/client/handler.go` implement client protocol handling, subscriptions, commands, and message delivery.

#### Authentication and request policy
HTTP/client requests pass middleware for protocol enforcement, observability, connection limiting, CORS, and auth. Core paths include `internal/middleware/auth.go`, `internal/middleware/auththrottle.go`, and `internal/middleware/otel.go`. JWT validation supports signing keys/JWKS through `internal/jwtverify/token_verifier_jwt.go` and `internal/jwks/manager.go`; proxy/origin integration is represented by `internal/app/proxy.go` and `internal/origin/origin.go`. This boundary separates untrusted client credentials and backend authorization decisions from the messaging engine.

#### Backend API and proxy operations
Backends call generated HTTP and gRPC APIs to publish, inspect connections, refresh credentials/subscriptions, and issue RPC-related operations. Public API dispatch is in `internal/api/api.go`, `internal/api/handler.go`, and `internal/api/grpc.go`; wire contracts are generated from `internal/apiproto/api.proto`. `internal/proxy/` implements outbound calls to an application backend for connect, subscribe, publish, refresh, and RPC hooks, with HTTP and gRPC variants.

#### Distribution, persistence, and ingestion
The engine scales publications, presence, history, and cross-node control via pluggable brokers. Redis/NATS options are under `internal/redisnatsbroker/broker.go`, `internal/natsbroker/broker.go`, and `internal/pubsub/`; PostgreSQL-backed map and stream brokers are `internal/pgmapbroker/pgmapbroker.go` and `internal/pgstreambroker/pgstreambroker.go`. External event ingestion supports Kafka, PostgreSQL, Redis Streams, NATS JetStream, AWS SQS, Google Pub/Sub, and Azure Service Bus in `internal/consuming/`. PostgreSQL outbox workers in `internal/pgoutbox/` support transactional-outbox/CDC delivery.

#### Operations and observability
The service exposes health and runtime operations through `internal/health/health.go` and embedded admin handling in `internal/admin/handlers.go`. Metrics are centralized in `internal/metrics/metrics.go`, with optional Graphite export at `internal/metrics/graphite/graphite.go`; OpenTelemetry provider setup is `internal/telemetry/provider.go`. Deployment targets include a container image (`Dockerfile`), local dependency composition (`docker-compose.yml`), and release packaging (`.goreleaser.yml`).

Main entry points: [`internal/app/run.go`](https://github.com/centrifugal/centrifugo/blob/master/internal/app/run.go) (Server assembly), [`internal/app/engine.go`](https://github.com/centrifugal/centrifugo/blob/master/internal/app/engine.go) (Real-time engine), [`internal/middleware/auth.go`](https://github.com/centrifugal/centrifugo/blob/master/internal/middleware/auth.go) (Request policy), [`internal/client/client.go`](https://github.com/centrifugal/centrifugo/blob/master/internal/client/client.go) (Client sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_main(("Process entry<br/>Go entrypoint<br/>[main.go]"))
  node_command["CLI serve command<br/>command wiring<br/>[cmd.go]"]
  node_runtime["Server assembly<br/>lifecycle<br/>[run.go]"]
  node_config["Configuration boundary<br/>config validation<br/>[config.go]"]
  node_engine{{"Real-time engine<br/>messaging core<br/>[engine.go]"}}
end

subgraph group_clients["Client access"]
  node_http_mux["HTTP transport mux<br/>route composition<br/>[mux.go]"]
  node_middleware["Request policy<br/>HTTP middleware<br/>[auth.go]"]
  node_jwt["JWT and JWKS validation<br/>credential validation"]
  node_websocket["WebSocket adapter<br/>bidirectional transport"]
  node_unidirectional["Streaming adapters<br/>HTTP/SSE/gRPC/WebTransport<br/>[transport.go]"]
  node_client["Client sessions<br/>protocol handler<br/>[client.go]"]
end

subgraph group_backend["Backend integration"]
  node_api["Backend API dispatch<br/>HTTP and gRPC API<br/>[api.go]"]
  node_contracts["API contracts<br/>protobuf schema<br/>[api.proto]"]
  node_proxy["Application hooks<br/>outbound proxy"]
end

subgraph group_distribution["Distribution &amp; ingestion"]
  node_brokers["Broker layer<br/>distribution abstraction"]
  node_broker_drivers["Broker implementations<br/>Redis/NATS/PostgreSQL<br/>[broker.go]"]
  node_consumers["External event consumers<br/>ingestion pipeline"]
  node_outbox[("PostgreSQL outbox<br/>transactional delivery")]
end

subgraph group_operations["Operations"]
  node_health_admin["Health and admin<br/>operations endpoints<br/>[health.go]"]
  node_telemetry["Metrics and telemetry<br/>observability<br/>[provider.go]"]
end

node_main -->|"initializes"| node_command
node_command -->|"loads and validates"| node_config
node_command -->|"runs"| node_runtime
node_config -->|"configures"| node_runtime
node_runtime -->|"constructs"| node_engine
node_runtime -->|"serves"| node_http_mux
node_runtime -->|"exposes"| node_api
node_runtime -->|"exposes"| node_health_admin
node_runtime -->|"initializes"| node_telemetry
node_http_mux -->|"applies"| node_middleware
node_middleware -->|"validates credentials with"| node_jwt
node_middleware -->|"protects"| node_websocket
node_middleware -->|"protects"| node_unidirectional
node_websocket -->|"creates sessions"| node_client
node_unidirectional -->|"normalizes into"| node_client
node_client -->|"subscribes and delivers via"| node_engine
node_api -->|"implements"| node_contracts
node_api -->|"publishes and manages"| node_engine
node_client -.->|"invokes hooks"| node_proxy
node_engine -->|"distributes through"| node_brokers
node_broker_drivers -->|"implements"| node_brokers
node_consumers -->|"ingests events into"| node_engine
node_outbox -->|"feeds transactional events"| node_consumers
node_engine -.->|"reports signals"| node_telemetry

click node_main "https://github.com/centrifugal/centrifugo/blob/master/main.go"
click node_command "https://github.com/centrifugal/centrifugo/blob/master/internal/app/cmd.go"
click node_runtime "https://github.com/centrifugal/centrifugo/blob/master/internal/app/run.go"
click node_config "https://github.com/centrifugal/centrifugo/blob/master/internal/config/config.go"
click node_engine "https://github.com/centrifugal/centrifugo/blob/master/internal/app/engine.go"
click node_http_mux "https://github.com/centrifugal/centrifugo/blob/master/internal/app/mux.go"
click node_middleware "https://github.com/centrifugal/centrifugo/blob/master/internal/middleware/auth.go"
click node_jwt "https://github.com/centrifugal/centrifugo/blob/master/internal/jwtverify/token_verifier_jwt.go"
click node_unidirectional "https://github.com/centrifugal/centrifugo/blob/master/internal/unihttpstream/transport.go"
click node_client "https://github.com/centrifugal/centrifugo/blob/master/internal/client/client.go"
click node_api "https://github.com/centrifugal/centrifugo/blob/master/internal/api/api.go"
click node_contracts "https://github.com/centrifugal/centrifugo/blob/master/internal/apiproto/api.proto"
click node_broker_drivers "https://github.com/centrifugal/centrifugo/blob/master/internal/redisnatsbroker/broker.go"
click node_health_admin "https://github.com/centrifugal/centrifugo/blob/master/internal/health/health.go"
click node_telemetry "https://github.com/centrifugal/centrifugo/blob/master/internal/telemetry/provider.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_main,node_command,node_runtime,node_config,node_engine toneBlue
class node_http_mux,node_middleware,node_jwt,node_websocket,node_unidirectional,node_client toneAmber
class node_api,node_contracts,node_proxy toneMint
class node_brokers,node_broker_drivers,node_consumers,node_outbox toneRose
class node_health_admin,node_telemetry toneIndigo
```

## Components

### Bootstrap

- [Process entry](https://github.com/centrifugal/centrifugo/blob/master/main.go): Go entrypoint · `main.go`
- [CLI serve command](https://github.com/centrifugal/centrifugo/blob/master/internal/app/cmd.go): command wiring · `internal/app/cmd.go`
- [Server assembly](https://github.com/centrifugal/centrifugo/blob/master/internal/app/run.go): lifecycle · Builds dependencies and starts listeners. · `internal/app/run.go`
- [Configuration boundary](https://github.com/centrifugal/centrifugo/blob/master/internal/config/config.go): config validation · `internal/config/config.go`
- [Real-time engine](https://github.com/centrifugal/centrifugo/blob/master/internal/app/engine.go): messaging core · Coordinates publications, subscriptions, presence, and history. · `internal/app/engine.go`

### Client access

- [HTTP transport mux](https://github.com/centrifugal/centrifugo/blob/master/internal/app/mux.go): route composition · `internal/app/mux.go`
- [Request policy](https://github.com/centrifugal/centrifugo/blob/master/internal/middleware/auth.go): HTTP middleware · Applies auth, throttling, CORS, limits, and observability. · `internal/middleware/auth.go`
- [JWT and JWKS validation](https://github.com/centrifugal/centrifugo/blob/master/internal/jwtverify/token_verifier_jwt.go): credential validation · `internal/jwtverify/token_verifier_jwt.go`
- **WebSocket adapter**: bidirectional transport
- [Streaming adapters](https://github.com/centrifugal/centrifugo/blob/master/internal/unihttpstream/transport.go): HTTP/SSE/gRPC/WebTransport · Normalizes unidirectional client transports. · `internal/unihttpstream/transport.go`
- [Client sessions](https://github.com/centrifugal/centrifugo/blob/master/internal/client/client.go): protocol handler · Handles commands, subscriptions, and delivery. · `internal/client/client.go`

### Backend integration

- [Backend API dispatch](https://github.com/centrifugal/centrifugo/blob/master/internal/api/api.go): HTTP and gRPC API · Serves publish, connection, refresh, and RPC operations. · `internal/api/api.go`
- [API contracts](https://github.com/centrifugal/centrifugo/blob/master/internal/apiproto/api.proto): protobuf schema · `internal/apiproto/api.proto`
- **Application hooks**: outbound proxy · Calls backend connect, subscribe, publish, refresh, and RPC hooks.

### Distribution & ingestion

- **Broker layer**: distribution abstraction · Distributes publications and cross-node control.
- [Broker implementations](https://github.com/centrifugal/centrifugo/blob/master/internal/redisnatsbroker/broker.go): Redis/NATS/PostgreSQL · `internal/redisnatsbroker/broker.go`
- **External event consumers**: ingestion pipeline · Ingests Kafka, streams, queues, and cloud pub/sub events.
- **PostgreSQL outbox**: transactional delivery

### Operations

- [Health and admin](https://github.com/centrifugal/centrifugo/blob/master/internal/health/health.go): operations endpoints · `internal/health/health.go`
- [Metrics and telemetry](https://github.com/centrifugal/centrifugo/blob/master/internal/telemetry/provider.go): observability · `internal/telemetry/provider.go`

## Connections

- Process entry → CLI serve command: initializes
- CLI serve command → Configuration boundary: loads and validates
- CLI serve command → Server assembly: runs
- Configuration boundary → Server assembly: configures
- Server assembly → Real-time engine: constructs
- Server assembly → HTTP transport mux: serves
- Server assembly → Backend API dispatch: exposes
- Server assembly → Health and admin: exposes
- Server assembly → Metrics and telemetry: initializes
- HTTP transport mux → Request policy: applies
- Request policy → JWT and JWKS validation: validates credentials with
- Request policy → WebSocket adapter: protects
- Request policy → Streaming adapters: protects
- WebSocket adapter → Client sessions: creates sessions
- Streaming adapters → Client sessions: normalizes into
- Client sessions → Real-time engine: subscribes and delivers via
- Backend API dispatch → API contracts: implements
- Backend API dispatch → Real-time engine: publishes and manages
- Client sessions → Application hooks: invokes hooks
- Real-time engine → Broker layer: distributes through
- Broker implementations → Broker layer: implements
- External event consumers → Real-time engine: ingests events into
- PostgreSQL outbox → External event consumers: feeds transactional events
- Real-time engine → Metrics and telemetry: reports signals
