# gaomind/htnn architecture

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

- Interactive diagram: https://gitdiagram.com/gaomind/htnn
- Repository: https://github.com/gaomind/htnn

## Overview

##### Project type and purpose
- HTNN is a cloud-native, cross-layer networking solution built on Envoy and Istio.
- It consists of two main logical subsystems:
a. A **Control Plane** (the “controller” component) that runs in Kubernetes, watches custom resources (CRDs), and generates XDS/EnvoyFilter configurations.
b. A **Data Plane** (the “api” component) that plugs into Envoy via Go extensions to enforce network policies, plugins, and filters at runtime.
- Supporting subsystems: CRD definitions (“types”), plugin implementations, service‐registry connectors, Helm charts (“manifests”), documentation site, and test suites (unit, integration, e2e).

##### File structure
- Top‐level dirs:
- `api` – Go library implementing the data-plane API, filters, plugin state, cookie handling, proto definitions, and filter manager.
- `controller` – Kubernetes controller with subpackages for config, reconcilers (consumer, dynamicconfig, filterpolicy, serviceregistry), translation logic, Istio/EnvoyFilter generation, metrics, and logging.
- `types` – Kubernetes CRD API definitions (Go types, clientsets, deep-copy, validation).
- `plugins` – Example plugin host and dynamicconfigs loader, plus plugin SDK `pkg`, integration tests.
- `manifests` – Helm charts for deploying HTNN controller and gateway, Docker images, and K8s manifests (CRDs, RBAC, deployments, webhooks).
- `e2e`, `api/tests`, `controller/tests`, `plugins/tests` – Full integration and end-to-end test suites.
- `site` – Hugo-based documentation website.
- `patch` – Patches against various Istio releases.
- Key architecture patterns:
- **Kubernetes Operator** pattern for the control plane.
- **Envoy Filter Extension** for the data plane.
- **Plugin framework**—dynamic plugin registration via protobuf + Go runtime.
- **Service Registry Adapters** (Consul, Nacos).
- Deployment helpers: Helm charts, `Makefile`, CI workflows.

##### README
- Confirms HTNN’s purpose: cloud-native cross-layer networking, extensible via Go runtime, multi-cluster support.
- References documentation on dataplane support, quick start, architecture sections in the `site` folder.

##### Diagramming the architecture
- Kubernetes API Server (CRDs for Consumer, DynamicConfig, FilterPolicy, HTTPFilterPolicy, ServiceRegistry).
- HTNN Controller (with subcomponents):
- ConsumerController
- DynamicConfigController
- FilterPolicyController
- ServiceRegistryController
- Translation Engine → EnvoyFilter generator
- Service Registries (Consul, Nacos adapters).
- Envoy Proxy (Data Plane) with HTNN Go Filter extension:
- filtermanager
- consumer plugins
- dynamicconfig loader
- pluginstate
- External Services: upstream services simulated in tests, registry back-ends.
- Helm/helm-chart deployment (manifests).
- CI/CD pipelines and test harness (unit, integration, e2e).
- Controllers watch CRDs → read from Kubernetes API → call translation → update EnvoyFilter resources.
- Envoy’s **EnvoyFilter** CRD injected → Envoy connects to XDS server → loads HTNN filter plugin.
- Data-plane plugin orders and executes registered plugins based on config.
- ServiceRegistryController talks to Consul/Nacos to fetch service info → feeds translation.
- Plugins (Go code) invoked within the data-plane filter chain.
c. Architectural patterns & principles:
- Operator/Controller pattern for control plane reliability and reconciliation loops.
- Plugin abstraction: common `plugins` API, dynamic loading via code‐generated protobuf interfaces.
- Separation of concerns: translation logic separate from K8s client code, separate from filter runtime.
d. Key technologies and frameworks:
- Go modules, client-go for K8s, controller-runtime libraries.
- Envoy XDS, EnvoyFilter CRD.
- Protobuf for plugin and config definitions.
- Helm charts for deployment.
- Hugo for documentation site.
- CI via GitHub Actions, codecov, golangci-lint.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Plane and Data Plane Overview
    APIServer["Kubernetes API Server<br/>(CRDs: Consumer, DynamicConfig, FilterPolicy, HTTPFilterPolicy, ServiceRegistry)"]:::external

    subgraph "Control Plane" 
        direction TB
        Controller["HTNN Controller"]:::control
        subgraph CP_Internal
            direction TB
            ConfigRecon["Config Management & Reconcilers"]:::control
            TransEngine["Translation Engine<br/>& EnvoyFilter Generator"]:::control
            ServiceReg["ServiceRegistry Controllers<br/>& Adapters"]:::control
            MetricsLog["Metrics & Logging"]:::control
        end
    end

    subgraph "Data Plane" 
        direction TB
        Envoy["Envoy Proxy<br/>(HTNN Filter Extension)"]:::data
        subgraph DP_Internal
            direction TB
            FilterMgr["Filter Manager & Phases"]:::data
            ConsumerState["Consumer Plugin & State Manager"]:::data
            PluginSDK["Plugin SDK & Proto Definitions"]:::data
        end
    end

    subgraph "External Systems"
        direction TB
        Consul["Consul Registry"]:::external
        Nacos["Nacos Registry"]:::external
        Upstream["Upstream Services"]:::external
    end

    subgraph "Artifacts & Support"
        direction TB
        Helm["Helm Charts & Manifests"]:::artifact
        Types["CRD Definitions"]:::artifact
        PluginsImpl["Plugin Implementations"]:::artifact
        ExamplePlugin["Example Plugin Project"]:::artifact
        Docs["Documentation Site"]:::artifact
        E2E["End-to-End Tests"]:::artifact
        APITests["API Unit & Integration Tests"]:::artifact
        ControllerTests["Controller Tests"]:::artifact
        PluginTests["Plugin Integration Tests"]:::artifact
        Patch["Istio Compatibility Patches"]:::artifact
        CI["Deployment Helpers & CI Workflows"]:::artifact
    end

    %% Interactions
    APIServer -->|Watch CRDs| ConfigRecon
    ConfigRecon -->|Trigger reconciliation| TransEngine
    ServiceReg -->|Fetch service info| TransEngine
    TransEngine -->|Generate EnvoyFilter CRD| APIServer
    APIServer -->|EnvoyFilter applies| Envoy
    TransEngine -->|EnvoyFilter Spec| Envoy
    Envoy -->|XDS stream & load filter| TransEngine
    Envoy -->|Execute filter chain| FilterMgr
    FilterMgr -->|Manage plugins| ConsumerState
    FilterMgr -->|Invoke plugin APIs| PluginSDK
    Consul -->|Registry adapter| ServiceReg
    Nacos -->|Registry adapter| ServiceReg
    Upstream -->|Traffic handled by| Envoy
    Helm -->|Deploys| Controller
    Helm -->|Deploys| Envoy
    Docs -->|Docs for| Controller
    Docs -->|Docs for| Envoy
    E2E -->|Validates| Envoy
    E2E -->|Validates| Controller
    APITests -->|Covers| API
    ControllerTests -->|Covers| Controller
    PluginTests -->|Covers| PluginsImpl
    Patch -->|Applied to| Envoy
    CI -->|Build & Release| Controller
    CI -->|Build & Release| API

    %% Click Events
    click Controller "https://github.com/gaomind/htnn/tree/main/controller/"
    click ConfigRecon "https://github.com/gaomind/htnn/tree/main/controller/internal/config/"
    click ConfigRecon "https://github.com/gaomind/htnn/tree/main/controller/internal/controller/"
    click TransEngine "https://github.com/gaomind/htnn/tree/main/controller/internal/translation/"
    click TransEngine "https://github.com/gaomind/htnn/blob/main/controller/internal/istio/envoyfilter.go"
    click ServiceReg "https://github.com/gaomind/htnn/blob/main/controller/internal/controller/serviceregistry_controller.go"
    click ServiceReg "https://github.com/gaomind/htnn/tree/main/controller/registries/consul/"
    click ServiceReg "https://github.com/gaomind/htnn/tree/main/controller/registries/nacos/"
    click MetricsLog "https://github.com/gaomind/htnn/blob/main/controller/internal/metrics/metrics.go"
    click MetricsLog "https://github.com/gaomind/htnn/blob/main/controller/internal/log/log.go"
    click Envoy "https://github.com/gaomind/htnn/tree/main/api/"
    click ConsumerState "https://github.com/gaomind/htnn/blob/main/api/internal/consumer/consumer_manager.go"
    click ConsumerState "https://github.com/gaomind/htnn/blob/main/api/internal/pluginstate/plugin_state.go"
    click FilterMgr "https://github.com/gaomind/htnn/tree/main/api/pkg/filtermanager/"
    click PluginSDK "https://github.com/gaomind/htnn/tree/main/api/pkg/plugins/"
    click PluginSDK "https://github.com/gaomind/htnn/tree/main/api/internal/proto/"
    click Types "https://github.com/gaomind/htnn/tree/main/types/apis/"
    click Types "https://github.com/gaomind/htnn/tree/main/types/pkg/client/"
    click PluginsImpl "https://github.com/gaomind/htnn/tree/main/plugins/plugins/"
    click PluginsImpl "https://github.com/gaomind/htnn/tree/main/plugins/pkg/"
    click ExamplePlugin "https://github.com/gaomind/htnn/tree/main/examples/dev_your_plugin/"
    click Helm "https://github.com/gaomind/htnn/tree/main/manifests/charts/htnn-controller/"
    click Helm "https://github.com/gaomind/htnn/tree/main/manifests/charts/htnn-gateway/"
    click Docs "https://github.com/gaomind/htnn/tree/main/site/"
    click E2E "https://github.com/gaomind/htnn/tree/main/e2e/"
    click APITests "https://github.com/gaomind/htnn/tree/main/api/tests/"
    click APITests "https://github.com/gaomind/htnn/tree/main/api/plugins/tests/"
    click ControllerTests "https://github.com/gaomind/htnn/tree/main/controller/tests/"
    click PluginTests "https://github.com/gaomind/htnn/tree/main/plugins/tests/integration/"
    click Patch "https://github.com/gaomind/htnn/tree/main/patch/istio/"
    click CI "https://github.com/gaomind/htnn/tree/main/Makefile"
    click CI "https://github.com/gaomind/htnn/tree/main/.github/workflows/"

    %% Styles
    classDef control fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef data fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef artifact fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
