# alibaba/higress architecture

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

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

## Overview

##### Main components
- Core Gateway: The primary service that interacts with clients, handles HTTP/HTTPS routing (listening on ports like 8080/8443) and provides the UI console (port 8001). Look into the “cmd/higress” for the main entry point.
- Control Plane: This includes configuration management, dynamic updates, and distribution of settings. The “pkg/config”, “pkg/cmd”, and parts of “client” help manage how gateway configurations are formed and distributed. The existence of “istio” and “envoy” directories indicates tight integration with these data/control plane components.
- Wasm Plugin Framework: There is an extensive plugin directory (under “plugins/”) that contains many sub‑directories for plugins in Go, Rust, AssemblyScript, and C++, which indicates that the system has a plug-in architecture for extending functionality.
- Auxiliary CLI Tools: Specifically “hgctl” acts as a command line tool for controlling, installing, performing configuration updates, and managing flows.
- Kubernetes/Helm Integration: The “helm” directory, and associated CRD configurations in the “api” and “client” folders, add an extra layer for Kubernetes deployments and interactions.
- Test and CI/CD: Directories like “.github” and “test” provide CI/CD and end‑to‑end testing which indicate continuous integration but are less part of runtime architecture.

- UI Console component as a separate service/module that interacts with the core (e.g., via API calls or configuration management) and listens on Port 8001.
- An “API/Configuration Management” component that integrates with the “client”, “api”, and “pkg/config” areas. This component can be shown interacting with both the core gateway and the CLI tool.
- Integration with service registries (Nacos, ZooKeeper, Consul, Eureka) as part of the microservice or security gateway functionalities. This can be depicted as external systems that the core gateway queries for service discovery.
- An “Observability & Monitoring” block (which can cover metrics/logs from Envoy, Istio, and plugins) as indicated by the project’s emphasis on high-availability and observability.

##### Architectural patterns and technologies
- Microservices and cloud‑native: Clearly separate the data plane (the actual ingress data flow) from the control plane (configuration, management, and dynamic updates).
- Plugin-based extensibility: Use a layered approach where the core gateway handles traffic, while Wasm-based plugins (with support for multiple languages) sit in an extensible chain.
- API-driven configuration (via CRDs and CLI “hgctl”): Emphasize the API endpoint for configuration distribution.
- Use of standard tools and integrations: Show that the gateway is built on top of Istio/Envoy and deployable via Kubernetes (Helm charts, CRDs, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Clients["Clients"]:::external

    %% Gateway Layer
    subgraph "Gateway Layer"
        GatewayCore["Higress API Gateway Core"]:::core
        UIConsole["UI Console (Port 8001)"]:::core
    end

    %% Control Plane & Configuration Management
    subgraph "Control Plane"
        Config["Config (pkg/config)"]:::control
        Commands["Commands (pkg/cmd)"]:::control
        APICRD["API CRD (api)"]:::control
        ClientCRD["Client CRD (client)"]:::control
    end

    %% Wasm Plugin Framework
    subgraph "Wasm Plugin Manager"
        WasmGo["Wasm Plugin - Go"]:::plugin
        WasmRust["Wasm Plugin - Rust"]:::plugin
        WasmAssembly["Wasm Plugin - AssemblyScript"]:::plugin
        WasmCpp["Wasm Plugin - C++"]:::plugin
    end

    %% Auxiliary CLI Tools
    subgraph "Auxiliary Tools"
        AuxCLI["Auxiliary CLI Tools (hgctl)"]:::aux
    end

    %% Deployment, CI/CD and Testing
    subgraph "Deployment & Testing"
        K8sHelm["Kubernetes/Helm Integration"]:::deploy
        subgraph "CI/CD & Testing"
            GitHubCI["CI/CD Pipeline (.github)"]:::deploy
            TestingSuite["Testing Suite (test)"]:::deploy
        end
    end

    %% External Services & Integrations
    subgraph "External Services"
        Envoy["Envoy"]:::external
        Istio["Istio"]:::external
        ServiceDiscovery["Service Discovery (Registries)"]:::external
        Observability["Observability & Monitoring"]:::external
    end

    %% Connections
    Clients -->|"HTTP/HTTPS-request"| GatewayCore
    GatewayCore -->|"Serves-UI"| UIConsole

    Config -->|"ProvidesConfig"| GatewayCore
    Commands -->|"ProvidesCommands"| GatewayCore
    APICRD -->|"DistributesConfig"| GatewayCore
    ClientCRD -->|"DistributesConfig"| GatewayCore

    AuxCLI -->|"ExecutesCommands"| Commands

    GatewayCore -->|"Loads-GoPlugin"| WasmGo
    GatewayCore -->|"Loads-RustPlugin"| WasmRust
    GatewayCore -->|"Loads-AssemblyScriptPlugin"| WasmAssembly
    GatewayCore -->|"Loads-CPPPlugin"| WasmCpp

    K8sHelm -->|"DeploysGateway"| GatewayCore
    GitHubCI -->|"Builds&Deploys"| K8sHelm
    TestingSuite -->|"RunsTests"| GitHubCI

    GatewayCore -->|"QueriesRegistry"| ServiceDiscovery
    GatewayCore ---|"IntegratesWith"| Envoy
    GatewayCore ---|"IntegratesWith"| Istio
    GatewayCore -->|"SendsMetrics"| Observability

    %% Styling Classes
    classDef core fill:#f6d186,stroke:#d68a00,stroke-width:2px;
    classDef control fill:#c6e2ff,stroke:#5b8bd1,stroke-width:2px;
    classDef plugin fill:#d5f5e3,stroke:#28a745,stroke-width:2px;
    classDef aux fill:#fadadd,stroke:#d6336c,stroke-width:2px;
    classDef deploy fill:#e2d5f5,stroke:#6f42c1,stroke-width:2px;
    classDef external fill:#eeeeee,stroke:#bbbbbb,stroke-width:2px;

    %% Click Events
    click GatewayCore "https://github.com/alibaba/higress/blob/main/cmd/higress/main.go"
    click Config "https://github.com/alibaba/higress/tree/main/pkg/config"
    click Commands "https://github.com/alibaba/higress/tree/main/pkg/cmd"
    click APICRD "https://github.com/alibaba/higress/tree/main/api"
    click ClientCRD "https://github.com/alibaba/higress/tree/main/client"
    click WasmGo "https://github.com/alibaba/higress/tree/main/plugins/wasm-go"
    click WasmRust "https://github.com/alibaba/higress/tree/main/plugins/wasm-rust"
    click WasmAssembly "https://github.com/alibaba/higress/tree/main/plugins/wasm-assemblyscript"
    click WasmCpp "https://github.com/alibaba/higress/tree/main/plugins/wasm-cpp"
    click AuxCLI "https://github.com/alibaba/higress/blob/main/hgctl/cmd/hgctl/main.go"
    click K8sHelm "https://github.com/alibaba/higress/tree/main/helm/core"
    click GitHubCI "https://github.com/alibaba/higress/tree/main/.github/"
    click TestingSuite "https://github.com/alibaba/higress/tree/main/test/"
```
