# higress-group/higress architecture

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

- Interactive diagram: https://gitdiagram.com/higress-group/higress
- Repository: https://github.com/higress-group/higress

## Overview

Higress is a cloud-native AI API gateway built on Istio and Envoy, with Kubernetes Ingress and Gateway API controllers, configurable Wasm extensions, and MCP hosting. The principal workflow is Kubernetes configuration entering the controller, being translated into gateway configuration, and reaching Envoy through xDS; operators can also manage deployments with hgctl. The graph includes documented AI and MCP capabilities alongside sampled controller modules. Some controller wiring and plugin dispatch are documented but not shown in the excerpts, so those links are marked dashed.

Main entry points: [`pkg/bootstrap/server.go`](https://github.com/higress-group/higress/blob/main/pkg/bootstrap/server.go) (xDS server), [`pkg/kube/client.go`](https://github.com/higress-group/higress/blob/main/pkg/kube/client.go) (Kubernetes client), [`pkg/ingress/kube/common/controller.go`](https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/common/controller.go) (Ingress controller core), [`pkg/ingress/kube/gateway/controller.go`](https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/gateway/controller.go) (Gateway API controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_cmd["Serve command<br/>[server.go]"]
  node_bootstrap["Server bootstrap<br/>[server.go]"]
  node_xds["xDS server<br/>[server.go]"]
  node_kubeclient["Kubernetes client<br/>[client.go]"]
end

subgraph group_ingress["Kubernetes configuration"]
  node_common["Ingress controller core<br/>[controller.go]"]
  node_ingressv1["Ingress controller<br/>[controller.go]"]
  node_ingressv1api["Ingress v1 controller<br/>[controller.go]"]
  node_gateway["Gateway API controller<br/>[controller.go]"]
  node_istio["Istio Gateway controller<br/>[controller.go]"]
  node_kingress["KIngress controller<br/>[controller.go]"]
  node_configmap["ConfigMap controller<br/>[controller.go]"]
  node_wasmctl["Wasm plugin controller<br/>[controller.go]"]
end

subgraph group_ai["AI gateway"]
  node_aiproxy["AI model proxy<br/>[main.go]"]
  node_aisearch["AI search<br/>[main.go]"]
  node_aiagent["AI agent<br/>[main.go]"]
  node_aiextensions["AI extensions"]
end

subgraph group_mcp["MCP hosting"]
  node_mcpfilter["MCP filter<br/>[main.go]"]
  node_mcpservers["MCP servers"]
  node_rag["RAG client<br/>[rag_client.go]"]
end

subgraph group_ops["Operations"]
  node_hgctl["Deployment manager<br/>[installer.go]"]
end

node_operator(("Operator"))
node_kube[("Kubernetes resources")]
node_cli["Higress CLI<br/>[main.go]"]

node_operator -->|"runs"| node_cli
node_cli -->|"executes"| node_cmd
node_cmd -->|"starts"| node_bootstrap
node_bootstrap -->|"starts"| node_xds
node_bootstrap -.->|"configures"| node_kubeclient
node_kube -.->|"provides resources"| node_kubeclient
node_kubeclient -.->|"supplies client"| node_ingressv1
node_kubeclient -.->|"supplies client"| node_gateway
node_kubeclient -.->|"supplies client"| node_kingress
node_kubeclient -.->|"supplies client"| node_configmap
node_kubeclient -->|"supplies client"| node_wasmctl
node_ingressv1 -->|"uses"| node_common
node_ingressv1api -->|"uses"| node_common
node_kingress -->|"uses"| node_common
node_gateway -->|"constructs"| node_istio
node_gateway -->|"uses"| node_common
node_bootstrap -->|"sets up translation"| node_common
node_istio -->|"pushes configuration"| node_xds
node_wasmctl -.->|"manages plugins"| node_kube
node_xds -.->|"dispatches plugins"| node_aiproxy
node_xds -.->|"dispatches plugins"| node_aisearch
node_xds -.->|"dispatches plugins"| node_aiagent
node_xds -.->|"dispatches plugins"| node_aiextensions
node_xds -.->|"hosts MCP"| node_mcpfilter
node_mcpfilter -->|"registers servers"| node_mcpservers
node_mcpservers -.->|"offers retrieval"| node_rag
node_operator -.->|"manages deployment"| node_hgctl
node_hgctl -.->|"deploys to"| node_kube

click node_cli "https://github.com/higress-group/higress/blob/main/cmd/higress/main.go"
click node_cmd "https://github.com/higress-group/higress/blob/main/pkg/cmd/server.go"
click node_bootstrap "https://github.com/higress-group/higress/blob/main/pkg/bootstrap/server.go"
click node_xds "https://github.com/higress-group/higress/blob/main/pkg/bootstrap/server.go"
click node_kubeclient "https://github.com/higress-group/higress/blob/main/pkg/kube/client.go"
click node_common "https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/common/controller.go"
click node_ingressv1 "https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/ingress/controller.go"
click node_ingressv1api "https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/ingressv1/controller.go"
click node_gateway "https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/gateway/controller.go"
click node_istio "https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/gateway/istio/controller.go"
click node_kingress "https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/kingress/controller.go"
click node_configmap "https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/configmap/controller.go"
click node_wasmctl "https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/wasmplugin/controller.go"
click node_aiproxy "https://github.com/higress-group/higress/blob/main/plugins/wasm-go/extensions/ai-proxy/main.go"
click node_aisearch "https://github.com/higress-group/higress/blob/main/plugins/wasm-go/extensions/ai-search/main.go"
click node_aiagent "https://github.com/higress-group/higress/blob/main/plugins/wasm-go/extensions/ai-agent/main.go"
click node_aiextensions "https://github.com/higress-group/higress/tree/main/plugins/wasm-go/extensions"
click node_mcpfilter "https://github.com/higress-group/higress/blob/main/plugins/golang-filter/main.go"
click node_mcpservers "https://github.com/higress-group/higress/tree/main/plugins/golang-filter/mcp-server"
click node_rag "https://github.com/higress-group/higress/blob/main/plugins/golang-filter/mcp-server/servers/rag/rag_client.go"
click node_hgctl "https://github.com/higress-group/higress/blob/main/hgctl/pkg/installer/installer.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_cmd,node_bootstrap,node_xds,node_kubeclient toneBlue
class node_common,node_ingressv1,node_ingressv1api,node_gateway,node_istio,node_kingress,node_configmap,node_wasmctl,node_kube toneAmber
class node_aiproxy,node_aisearch,node_aiagent,node_aiextensions toneMint
class node_mcpfilter,node_mcpservers,node_rag toneRose
class node_hgctl,node_operator toneIndigo
class node_cli toneTeal
```

## Components

### Control plane

- [Serve command](https://github.com/higress-group/higress/blob/main/pkg/cmd/server.go): `pkg/cmd/server.go`
- [Server bootstrap](https://github.com/higress-group/higress/blob/main/pkg/bootstrap/server.go): `pkg/bootstrap/server.go`
- [xDS server](https://github.com/higress-group/higress/blob/main/pkg/bootstrap/server.go): `pkg/bootstrap/server.go`
- [Kubernetes client](https://github.com/higress-group/higress/blob/main/pkg/kube/client.go): `pkg/kube/client.go`

### Kubernetes configuration

- [Ingress controller core](https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/common/controller.go): `pkg/ingress/kube/common/controller.go`
- [Ingress controller](https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/ingress/controller.go): `pkg/ingress/kube/ingress/controller.go`
- [Ingress v1 controller](https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/ingressv1/controller.go): `pkg/ingress/kube/ingressv1/controller.go`
- [Gateway API controller](https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/gateway/controller.go): `pkg/ingress/kube/gateway/controller.go`
- [Istio Gateway controller](https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/gateway/istio/controller.go): `pkg/ingress/kube/gateway/istio/controller.go`
- [KIngress controller](https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/kingress/controller.go): `pkg/ingress/kube/kingress/controller.go`
- [ConfigMap controller](https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/configmap/controller.go): `pkg/ingress/kube/configmap/controller.go`
- [Wasm plugin controller](https://github.com/higress-group/higress/blob/main/pkg/ingress/kube/wasmplugin/controller.go): `pkg/ingress/kube/wasmplugin/controller.go`

### AI gateway

- [AI model proxy](https://github.com/higress-group/higress/blob/main/plugins/wasm-go/extensions/ai-proxy/main.go): `plugins/wasm-go/extensions/ai-proxy/main.go`
- [AI search](https://github.com/higress-group/higress/blob/main/plugins/wasm-go/extensions/ai-search/main.go): `plugins/wasm-go/extensions/ai-search/main.go`
- [AI agent](https://github.com/higress-group/higress/blob/main/plugins/wasm-go/extensions/ai-agent/main.go): `plugins/wasm-go/extensions/ai-agent/main.go`
- [AI extensions](https://github.com/higress-group/higress/tree/main/plugins/wasm-go/extensions): `plugins/wasm-go/extensions`

### MCP hosting

- [MCP filter](https://github.com/higress-group/higress/blob/main/plugins/golang-filter/main.go): `plugins/golang-filter/main.go`
- [MCP servers](https://github.com/higress-group/higress/tree/main/plugins/golang-filter/mcp-server): `plugins/golang-filter/mcp-server`
- [RAG client](https://github.com/higress-group/higress/blob/main/plugins/golang-filter/mcp-server/servers/rag/rag_client.go): `plugins/golang-filter/mcp-server/servers/rag/rag_client.go`

### Operations

- [Deployment manager](https://github.com/higress-group/higress/blob/main/hgctl/pkg/installer/installer.go): `hgctl/pkg/installer/installer.go`

### Other components

- **Operator**
- **Kubernetes resources**
- [Higress CLI](https://github.com/higress-group/higress/blob/main/cmd/higress/main.go): `cmd/higress/main.go`

## Connections

- Operator → Higress CLI: runs (evidence: `cmd/higress/main.go`)
- Higress CLI → Serve command: executes (evidence: `cmd/higress/main.go`)
- Serve command → Server bootstrap: starts (evidence: `pkg/cmd/server.go`)
- Server bootstrap → xDS server: starts (evidence: `pkg/bootstrap/server.go`)
- Server bootstrap → Kubernetes client: configures
- Kubernetes resources → Kubernetes client: provides resources
- Kubernetes client → Ingress controller: supplies client
- Kubernetes client → Gateway API controller: supplies client
- Kubernetes client → KIngress controller: supplies client
- Kubernetes client → ConfigMap controller: supplies client
- Kubernetes client → Wasm plugin controller: supplies client (evidence: `pkg/ingress/kube/wasmplugin/controller.go`)
- Ingress controller → Ingress controller core: uses (evidence: `pkg/ingress/kube/ingress/controller.go`)
- Ingress v1 controller → Ingress controller core: uses (evidence: `pkg/ingress/kube/ingressv1/controller.go`)
- KIngress controller → Ingress controller core: uses (evidence: `pkg/ingress/kube/kingress/controller.go`)
- Gateway API controller → Istio Gateway controller: constructs (evidence: `pkg/ingress/kube/gateway/controller.go`)
- Gateway API controller → Ingress controller core: uses (evidence: `pkg/ingress/kube/gateway/controller.go`)
- Server bootstrap → Ingress controller core: sets up translation (evidence: `pkg/bootstrap/server.go`)
- Istio Gateway controller → xDS server: pushes configuration (evidence: `pkg/ingress/kube/gateway/istio/controller.go`)
- Wasm plugin controller → Kubernetes resources: manages plugins
- xDS server → AI model proxy: dispatches plugins
- xDS server → AI search: dispatches plugins
- xDS server → AI agent: dispatches plugins
- xDS server → AI extensions: dispatches plugins
- xDS server → MCP filter: hosts MCP
- MCP filter → MCP servers: registers servers (evidence: `plugins/golang-filter/main.go`)
- MCP servers → RAG client: offers retrieval (evidence: `plugins/golang-filter/mcp-server/servers/rag/rag_client.go`)
- Operator → Deployment manager: manages deployment
- Deployment manager → Kubernetes resources: deploys to
