# envoyproxy/envoy architecture

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

- Interactive diagram: https://gitdiagram.com/envoyproxy/envoy
- Repository: https://github.com/envoyproxy/envoy

## Overview

Envoy is a cloud-native proxy that accepts downstream traffic, applies configured protocol handling and routing, and connects to upstream services; its APIs also support dynamic configuration. The tree and excerpts show HTTP connection management, cluster management, listener management, and mobile-engine setup, while the README characterizes the product broadly as an edge, middle, and service proxy. The excerpts do not establish a complete server startup-to-request call chain, so uncertain runtime links are omitted. Core interfaces and shared runtime facilities are included as internal layers.

Main entry points: [`source/common/http/conn_manager_impl.cc`](https://github.com/envoyproxy/envoy/blob/main/source/common/http/conn_manager_impl.cc) (HTTP connection manager), [`source/common/upstream/cluster_manager_impl.cc`](https://github.com/envoyproxy/envoy/blob/main/source/common/upstream/cluster_manager_impl.cc) (Cluster manager), [`source/exe/main.cc`](https://github.com/envoyproxy/envoy/blob/main/source/exe/main.cc) (Envoy server), [`mobile/library/common/internal_engine.cc`](https://github.com/envoyproxy/envoy/blob/main/mobile/library/common/internal_engine.cc) (Mobile engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Startup and mobile"]
  node_server["Envoy server<br/>[main.cc]"]
  node_mobile_builder["Mobile builder<br/>[engine_builder.cc]"]
  node_mobile_engine["Mobile engine<br/>[internal_engine.cc]"]
end

subgraph group_traffic["Traffic handling"]
  node_http_manager["HTTP connection manager"]
  node_rbac["RBAC engine<br/>[engine_impl.cc]"]
  node_ai_transcoding["AI transcoding"]
  node_regex["Regex engine<br/>[regex_engine.cc]"]
end

subgraph group_config["Configuration and upstreams"]
  node_api_defs["Proxy APIs"]
  node_xds["xDS manager<br/>[xds_manager.h]"]
  node_listeners["Listener manager<br/>[listener_manager.h]"]
  node_clusters["Cluster manager"]
  node_cluster_api["Cluster interface<br/>[cluster_manager.h]"]
end

subgraph group_runtime["Runtime foundations"]
  node_dispatcher["Event dispatcher<br/>[dispatcher.h]"]
  node_buffer["Buffer API<br/>[buffer.h]"]
  node_stats["Stats scopes<br/>[scope.h]"]
  node_ssl["TLS contexts<br/>[context_manager.h]"]
  node_assertions["Assertions<br/>[assert.h]"]
  node_common_utils["Common utilities<br/>[utility.h]"]
  node_runtime_flags["Runtime features<br/>[runtime_features.h]"]
end

node_user(("Proxy user"))
node_external_control(("Control plane"))
node_upstream_services(("Upstream services"))

node_user -.->|"configures"| node_server
node_user -.->|"configures"| node_mobile_builder
node_mobile_builder -->|"configures"| node_mobile_engine
node_mobile_engine -->|"uses listener API"| node_listeners
node_external_control -.->|"supplies configuration"| node_xds
node_api_defs -.->|"defines config"| node_xds
node_xds -->|"uses interface"| node_cluster_api
node_server -.->|"initializes"| node_clusters
node_server -.->|"starts listeners"| node_listeners
node_user -.->|"sends traffic"| node_http_manager
node_http_manager -.->|"routes upstream"| node_clusters
node_clusters -.->|"connects upstream"| node_upstream_services
node_http_manager -.->|"applies policy"| node_rbac
node_http_manager -.->|"transcodes requests"| node_ai_transcoding
node_dispatcher -->|"dispatches work"| node_mobile_engine
node_http_manager -->|"processes data"| node_buffer
node_http_manager -->|"records metrics"| node_stats
node_clusters -->|"uses event loop"| node_dispatcher
node_regex -->|"uses utilities"| node_common_utils
node_runtime_flags -.->|"uses runtime helpers"| node_common_utils

click node_server "https://github.com/envoyproxy/envoy/blob/main/source/exe/main.cc"
click node_mobile_builder "https://github.com/envoyproxy/envoy/blob/main/mobile/library/cc/engine_builder.cc"
click node_mobile_engine "https://github.com/envoyproxy/envoy/blob/main/mobile/library/common/internal_engine.cc"
click node_api_defs "https://github.com/envoyproxy/envoy/blob/main/api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto"
click node_xds "https://github.com/envoyproxy/envoy/blob/main/envoy/config/xds_manager.h"
click node_listeners "https://github.com/envoyproxy/envoy/blob/main/envoy/server/listener_manager.h"
click node_clusters "https://github.com/envoyproxy/envoy/blob/main/source/common/upstream/cluster_manager_impl.cc"
click node_cluster_api "https://github.com/envoyproxy/envoy/blob/main/envoy/upstream/cluster_manager.h"
click node_http_manager "https://github.com/envoyproxy/envoy/blob/main/source/common/http/conn_manager_impl.cc"
click node_rbac "https://github.com/envoyproxy/envoy/blob/main/source/extensions/filters/common/rbac/engine_impl.cc"
click node_ai_transcoding "https://github.com/envoyproxy/envoy/blob/main/source/extensions/filters/http/ai_protocol_manager/transcoding_engine.cc"
click node_regex "https://github.com/envoyproxy/envoy/blob/main/source/server/regex_engine.cc"
click node_dispatcher "https://github.com/envoyproxy/envoy/blob/main/envoy/event/dispatcher.h"
click node_buffer "https://github.com/envoyproxy/envoy/blob/main/envoy/buffer/buffer.h"
click node_stats "https://github.com/envoyproxy/envoy/blob/main/envoy/stats/scope.h"
click node_ssl "https://github.com/envoyproxy/envoy/blob/main/envoy/ssl/context_manager.h"
click node_assertions "https://github.com/envoyproxy/envoy/blob/main/source/common/common/assert.h"
click node_common_utils "https://github.com/envoyproxy/envoy/blob/main/source/common/common/utility.h"
click node_runtime_flags "https://github.com/envoyproxy/envoy/blob/main/source/common/runtime/runtime_features.h"

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_server,node_mobile_builder,node_mobile_engine,node_user toneBlue
class node_http_manager,node_rbac,node_ai_transcoding,node_regex toneAmber
class node_api_defs,node_xds,node_listeners,node_clusters,node_cluster_api toneMint
class node_dispatcher,node_buffer,node_stats,node_ssl,node_assertions,node_common_utils,node_runtime_flags toneRose
class node_external_control,node_upstream_services toneIndigo
```

## Components

### Startup and mobile

- [Envoy server](https://github.com/envoyproxy/envoy/blob/main/source/exe/main.cc): `source/exe/main.cc`
- [Mobile builder](https://github.com/envoyproxy/envoy/blob/main/mobile/library/cc/engine_builder.cc): `mobile/library/cc/engine_builder.cc`
- [Mobile engine](https://github.com/envoyproxy/envoy/blob/main/mobile/library/common/internal_engine.cc): `mobile/library/common/internal_engine.cc`

### Traffic handling

- [HTTP connection manager](https://github.com/envoyproxy/envoy/blob/main/source/common/http/conn_manager_impl.cc): `source/common/http/conn_manager_impl.cc`
- [RBAC engine](https://github.com/envoyproxy/envoy/blob/main/source/extensions/filters/common/rbac/engine_impl.cc): `source/extensions/filters/common/rbac/engine_impl.cc`
- [AI transcoding](https://github.com/envoyproxy/envoy/blob/main/source/extensions/filters/http/ai_protocol_manager/transcoding_engine.cc): `source/extensions/filters/http/ai_protocol_manager/transcoding_engine.cc`
- [Regex engine](https://github.com/envoyproxy/envoy/blob/main/source/server/regex_engine.cc): `source/server/regex_engine.cc`

### Configuration and upstreams

- [Proxy APIs](https://github.com/envoyproxy/envoy/blob/main/api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto): `api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto`
- [xDS manager](https://github.com/envoyproxy/envoy/blob/main/envoy/config/xds_manager.h): `envoy/config/xds_manager.h`
- [Listener manager](https://github.com/envoyproxy/envoy/blob/main/envoy/server/listener_manager.h): `envoy/server/listener_manager.h`
- [Cluster manager](https://github.com/envoyproxy/envoy/blob/main/source/common/upstream/cluster_manager_impl.cc): `source/common/upstream/cluster_manager_impl.cc`
- [Cluster interface](https://github.com/envoyproxy/envoy/blob/main/envoy/upstream/cluster_manager.h): `envoy/upstream/cluster_manager.h`

### Runtime foundations

- [Event dispatcher](https://github.com/envoyproxy/envoy/blob/main/envoy/event/dispatcher.h): `envoy/event/dispatcher.h`
- [Buffer API](https://github.com/envoyproxy/envoy/blob/main/envoy/buffer/buffer.h): `envoy/buffer/buffer.h`
- [Stats scopes](https://github.com/envoyproxy/envoy/blob/main/envoy/stats/scope.h): `envoy/stats/scope.h`
- [TLS contexts](https://github.com/envoyproxy/envoy/blob/main/envoy/ssl/context_manager.h): `envoy/ssl/context_manager.h`
- [Assertions](https://github.com/envoyproxy/envoy/blob/main/source/common/common/assert.h): `source/common/common/assert.h`
- [Common utilities](https://github.com/envoyproxy/envoy/blob/main/source/common/common/utility.h): `source/common/common/utility.h`
- [Runtime features](https://github.com/envoyproxy/envoy/blob/main/source/common/runtime/runtime_features.h): `source/common/runtime/runtime_features.h`

### Other components

- **Proxy user**
- **Control plane**
- **Upstream services**

## Connections

- Proxy user → Envoy server: configures (evidence: `README.md`)
- Proxy user → Mobile builder: configures
- Mobile builder → Mobile engine: configures (evidence: `mobile/library/cc/engine_builder.cc`)
- Mobile engine → Listener manager: uses listener API (evidence: `mobile/library/common/internal_engine.cc`)
- Control plane → xDS manager: supplies configuration
- Proxy APIs → xDS manager: defines config
- xDS manager → Cluster interface: uses interface (evidence: `envoy/config/xds_manager.h`)
- Envoy server → Cluster manager: initializes
- Envoy server → Listener manager: starts listeners
- Proxy user → HTTP connection manager: sends traffic (evidence: `README.md`)
- HTTP connection manager → Cluster manager: routes upstream
- Cluster manager → Upstream services: connects upstream
- HTTP connection manager → RBAC engine: applies policy
- HTTP connection manager → AI transcoding: transcodes requests
- Event dispatcher → Mobile engine: dispatches work (evidence: `mobile/library/common/internal_engine.cc`)
- HTTP connection manager → Buffer API: processes data (evidence: `source/common/http/conn_manager_impl.cc`)
- HTTP connection manager → Stats scopes: records metrics (evidence: `source/common/http/conn_manager_impl.cc`)
- Cluster manager → Event dispatcher: uses event loop (evidence: `source/common/upstream/cluster_manager_impl.cc`)
- Regex engine → Common utilities: uses utilities (evidence: `source/server/regex_engine.cc`)
- Runtime features → Common utilities: uses runtime helpers
