# nutanix/envoyproxy-envoy architecture

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

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

## Overview

Envoy is a cloud-native edge, middle, and service proxy. Its main product workflow is to accept downstream network traffic, process HTTP streams through connection management and filters, then use upstream cluster and endpoint state to reach services. The repository also defines configuration APIs and supports dynamic xDS updates, observability, and mobile clients. The map emphasizes these documented product stages and sampled implementation links; many runtime relationships are not evidenced by the excerpts, so they are left unconnected.

Main entry points: [`source/common/http/conn_manager_impl.cc`](https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/http/conn_manager_impl.cc) (HTTP connection manager), [`source/common/upstream/cluster_manager_impl.cc`](https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/upstream/cluster_manager_impl.cc) (Cluster manager), [`source/common/config/xds_manager_impl.cc`](https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/config/xds_manager_impl.cc) (xDS management), [`api/envoy/config/bootstrap/v3/bootstrap.proto`](https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/config/bootstrap/v3/bootstrap.proto) (Bootstrap config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_config["Configuration and discovery"]
  node_bootstrap["Bootstrap config<br/>[bootstrap.proto]"]
  node_xds["xDS management"]
  node_discovery_api["Discovery APIs<br/>[discovery.proto]"]
  node_listener_config["Listener config<br/>[listener.proto]"]
end

subgraph group_traffic["Proxy traffic"]
  node_listener_manager["Listener manager<br/>[listener_manager.h]"]
  node_network["Network connections<br/>[connection.h]"]
  node_hcm_api["HTTP manager API"]
  node_http_manager["HTTP connection manager"]
  node_http_filters["HTTP filter APIs<br/>[router.proto]"]
  node_router["HTTP router<br/>[router.h]"]
  node_buffer["Buffer interface<br/>[buffer.h]"]
  node_event["Event dispatcher<br/>[dispatcher.h]"]
  node_network_filter["Network filter API<br/>[filter.h]"]
  node_listener_api["Listener API<br/>[listener.h]"]
  node_network_utility["Network utilities<br/>[utility.h]"]
end

subgraph group_upstream["Upstream connectivity"]
  node_cluster_manager["Cluster manager"]
  node_cluster_api["Cluster APIs<br/>[cluster.proto]"]
  node_endpoints["Endpoint config<br/>[endpoint.proto]"]
  node_upstream_service(("Upstream services"))
  node_upstream_api["Upstream interface<br/>[upstream.h]"]
end

subgraph group_ops["Security and observability"]
  node_tls["TLS contexts<br/>[context_manager.h]"]
  node_stats["Stats scopes<br/>[scope.h]"]
  node_admin["Admin APIs<br/>[config_dump.proto]"]
  node_access_logs["Access logging<br/>[accesslog.proto]"]
  node_tracing["Tracing APIs<br/>[tracer_manager.h]"]
  node_runtime["Runtime interface<br/>[runtime.h]"]
  node_stream_info["Stream information<br/>[stream_info.h]"]
  node_common_utility["Common utilities<br/>[utility.h]"]
  node_assertions["Assertions<br/>[assert.h]"]
  node_formatting["Formatting<br/>[fmt.h]"]
end

subgraph group_mobile["Mobile client"]
  node_mobile_builder["Engine builder<br/>[engine_builder.cc]"]
  node_mobile_engine["Internal engine<br/>[internal_engine.cc]"]
  node_mobile_api["Mobile APIs<br/>[EnvoyEngine.h]"]
end

node_operator(("Proxy operator"))

node_operator -->|"configures"| node_bootstrap
node_bootstrap -.->|"configures"| node_xds
node_discovery_api -.->|"defines resources"| node_xds
node_listener_config -.->|"configures"| node_listener_manager
node_listener_manager -.->|"accepts traffic"| node_network
node_network -.->|"dispatches HTTP"| node_http_manager
node_hcm_api -.->|"configures"| node_http_manager
node_http_manager -->|"uses"| node_router
node_http_filters -.->|"configures filters"| node_http_manager
node_http_manager -->|"logs streams"| node_access_logs
node_cluster_manager -->|"initializes"| node_xds
node_cluster_api -.->|"configures"| node_cluster_manager
node_endpoints -.->|"supplies endpoints"| node_cluster_manager
node_router -.->|"selects upstream"| node_cluster_manager
node_cluster_manager -.->|"connects upstream"| node_upstream_service
node_mobile_builder -->|"builds"| node_mobile_engine
node_mobile_engine -.->|"starts streams"| node_http_manager
node_mobile_api -.->|"configures engine"| node_mobile_builder
node_http_manager -->|"updates stream state"| node_stream_info
node_cluster_manager -->|"implements"| node_upstream_api

click node_bootstrap "https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/config/bootstrap/v3/bootstrap.proto"
click node_xds "https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/config/xds_manager_impl.cc"
click node_discovery_api "https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/api/v2/discovery.proto"
click node_listener_config "https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/config/listener/v3/listener.proto"
click node_listener_manager "https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/server/listener_manager.h"
click node_network "https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/network/connection.h"
click node_hcm_api "https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto"
click node_http_manager "https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/http/conn_manager_impl.cc"
click node_http_filters "https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/extensions/filters/http/router/v3/router.proto"
click node_router "https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/router/router.h"
click node_cluster_manager "https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/upstream/cluster_manager_impl.cc"
click node_cluster_api "https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/config/cluster/v3/cluster.proto"
click node_endpoints "https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/config/endpoint/v3/endpoint.proto"
click node_tls "https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/ssl/context_manager.h"
click node_stats "https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/stats/scope.h"
click node_admin "https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/admin/v3/config_dump.proto"
click node_access_logs "https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/config/accesslog/v3/accesslog.proto"
click node_tracing "https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/tracing/tracer_manager.h"
click node_mobile_builder "https://github.com/nutanix/envoyproxy-envoy/blob/main/mobile/library/cc/engine_builder.cc"
click node_mobile_engine "https://github.com/nutanix/envoyproxy-envoy/blob/main/mobile/library/common/internal_engine.cc"
click node_mobile_api "https://github.com/nutanix/envoyproxy-envoy/blob/main/mobile/library/objective-c/EnvoyEngine.h"
click node_buffer "https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/buffer/buffer.h"
click node_event "https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/event/dispatcher.h"
click node_runtime "https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/runtime/runtime.h"
click node_stream_info "https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/stream_info/stream_info.h"
click node_network_filter "https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/network/filter.h"
click node_listener_api "https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/network/listener.h"
click node_upstream_api "https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/upstream/upstream.h"
click node_common_utility "https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/common/utility.h"
click node_network_utility "https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/network/utility.h"
click node_assertions "https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/common/assert.h"
click node_formatting "https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/common/fmt.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_bootstrap,node_xds,node_discovery_api,node_listener_config toneBlue
class node_listener_manager,node_network,node_hcm_api,node_http_manager,node_http_filters,node_router,node_buffer,node_event,node_network_filter,node_listener_api,node_network_utility toneAmber
class node_cluster_manager,node_cluster_api,node_endpoints,node_upstream_service,node_upstream_api toneMint
class node_tls,node_stats,node_admin,node_access_logs,node_tracing,node_runtime,node_stream_info,node_common_utility,node_assertions,node_formatting toneRose
class node_mobile_builder,node_mobile_engine,node_mobile_api,node_operator toneIndigo
```

## Components

### Configuration and discovery

- [Bootstrap config](https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/config/bootstrap/v3/bootstrap.proto): `api/envoy/config/bootstrap/v3/bootstrap.proto`
- [xDS management](https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/config/xds_manager_impl.cc): `source/common/config/xds_manager_impl.cc`
- [Discovery APIs](https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/api/v2/discovery.proto): `api/envoy/api/v2/discovery.proto`
- [Listener config](https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/config/listener/v3/listener.proto): `api/envoy/config/listener/v3/listener.proto`

### Proxy traffic

- [Listener manager](https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/server/listener_manager.h): `envoy/server/listener_manager.h`
- [Network connections](https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/network/connection.h): `envoy/network/connection.h`
- [HTTP manager API](https://github.com/nutanix/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`
- [HTTP connection manager](https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/http/conn_manager_impl.cc): `source/common/http/conn_manager_impl.cc`
- [HTTP filter APIs](https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/extensions/filters/http/router/v3/router.proto): `api/envoy/extensions/filters/http/router/v3/router.proto`
- [HTTP router](https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/router/router.h): `envoy/router/router.h`
- [Buffer interface](https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/buffer/buffer.h): `envoy/buffer/buffer.h`
- [Event dispatcher](https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/event/dispatcher.h): `envoy/event/dispatcher.h`
- [Network filter API](https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/network/filter.h): `envoy/network/filter.h`
- [Listener API](https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/network/listener.h): `envoy/network/listener.h`
- [Network utilities](https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/network/utility.h): `source/common/network/utility.h`

### Upstream connectivity

- [Cluster manager](https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/upstream/cluster_manager_impl.cc): `source/common/upstream/cluster_manager_impl.cc`
- [Cluster APIs](https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/config/cluster/v3/cluster.proto): `api/envoy/config/cluster/v3/cluster.proto`
- [Endpoint config](https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/config/endpoint/v3/endpoint.proto): `api/envoy/config/endpoint/v3/endpoint.proto`
- **Upstream services**
- [Upstream interface](https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/upstream/upstream.h): `envoy/upstream/upstream.h`

### Security and observability

- [TLS contexts](https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/ssl/context_manager.h): `envoy/ssl/context_manager.h`
- [Stats scopes](https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/stats/scope.h): `envoy/stats/scope.h`
- [Admin APIs](https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/admin/v3/config_dump.proto): `api/envoy/admin/v3/config_dump.proto`
- [Access logging](https://github.com/nutanix/envoyproxy-envoy/blob/main/api/envoy/config/accesslog/v3/accesslog.proto): `api/envoy/config/accesslog/v3/accesslog.proto`
- [Tracing APIs](https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/tracing/tracer_manager.h): `envoy/tracing/tracer_manager.h`
- [Runtime interface](https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/runtime/runtime.h): `envoy/runtime/runtime.h`
- [Stream information](https://github.com/nutanix/envoyproxy-envoy/blob/main/envoy/stream_info/stream_info.h): `envoy/stream_info/stream_info.h`
- [Common utilities](https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/common/utility.h): `source/common/common/utility.h`
- [Assertions](https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/common/assert.h): `source/common/common/assert.h`
- [Formatting](https://github.com/nutanix/envoyproxy-envoy/blob/main/source/common/common/fmt.h): `source/common/common/fmt.h`

### Mobile client

- [Engine builder](https://github.com/nutanix/envoyproxy-envoy/blob/main/mobile/library/cc/engine_builder.cc): `mobile/library/cc/engine_builder.cc`
- [Internal engine](https://github.com/nutanix/envoyproxy-envoy/blob/main/mobile/library/common/internal_engine.cc): `mobile/library/common/internal_engine.cc`
- [Mobile APIs](https://github.com/nutanix/envoyproxy-envoy/blob/main/mobile/library/objective-c/EnvoyEngine.h): `mobile/library/objective-c/EnvoyEngine.h`

### Other components

- **Proxy operator**

## Connections

- Proxy operator → Bootstrap config: configures (evidence: `README.md`)
- Bootstrap config → xDS management: configures
- Discovery APIs → xDS management: defines resources
- Listener config → Listener manager: configures
- Listener manager → Network connections: accepts traffic
- Network connections → HTTP connection manager: dispatches HTTP
- HTTP manager API → HTTP connection manager: configures
- HTTP connection manager → HTTP router: uses (evidence: `source/common/http/conn_manager_impl.cc`)
- HTTP filter APIs → HTTP connection manager: configures filters
- HTTP connection manager → Access logging: logs streams (evidence: `source/common/http/conn_manager_impl.cc`)
- Cluster manager → xDS management: initializes (evidence: `source/common/upstream/cluster_manager_impl.cc`)
- Cluster APIs → Cluster manager: configures
- Endpoint config → Cluster manager: supplies endpoints
- HTTP router → Cluster manager: selects upstream
- Cluster manager → Upstream services: connects upstream
- Engine builder → Internal engine: builds (evidence: `mobile/library/cc/engine_builder.cc`)
- Internal engine → HTTP connection manager: starts streams
- Mobile APIs → Engine builder: configures engine
- HTTP connection manager → Stream information: updates stream state (evidence: `source/common/http/conn_manager_impl.cc`)
- Cluster manager → Upstream interface: implements (evidence: `source/common/upstream/cluster_manager_impl.cc`)
