# apache/dubbo-go-pixiu architecture

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

- Interactive diagram: https://gitdiagram.com/apache/dubbo-go-pixiu
- Repository: https://github.com/apache/dubbo-go-pixiu

## Overview

Based on our review of the file tree and the README, the Dubbo-Go-Pixiu project is a high-performance API gateway and multi-language sidecar within the Dubbo ecosystem. In essence, it acts as a protocol converter and gateway – receiving external HTTP/gRPC requests, translating these to Dubbo (or other protocol) calls, and forwarding them to your backend Dubbo clusters. It is architected as a modular, highly extensible gateway that integrates registry support, traffic management, observability, and a control plane (forked from Istio).

##### Main Components
- Command & Entry Point: The key starting point is in the “cmd/pixiu” directory. This contains the main executable (e.g. pixiu.go) that bootstraps the application.
- Configuration Management: The “configs” folder and the “configcenter” package handle configuration loading (both static from YAML and dynamic with Nacos). Also, the “pkg/config” and “pkg/config/xds” directories indicate support for dynamic resource configuration (using xDS APIs).
- Listener & Server Layers: The “pkg/listener” directories (including subfolders for HTTP, HTTP2, TCP, and Triple) indicate that the project supports multiple network entry protocols. The “pkg/server” package manages core server logic, including adapter and cluster management.
- Filter Chains & Middleware: The “pkg/filter” directories (and “pkg/filterchain”) show a rich filter chain mechanism that processes incoming requests. These filters handle access logging, authentication (JWT, header filters, etc.), CORS, fail injection, metrics, traffic management, tracing, and more.
- Clustering, Load Balancing & Health Check: The “pkg/cluster” directory includes cluster management, load balancer implementations (e.g., round-robin, ring hash, maglev), and health check mechanisms.
- Observability, Tracing & Logging: There are dedicated packages (for example, “pkg/tracing”, “pkg/logger”, “pkg/prometheus”) that integrate with Jaeger, OpenTelemetry, and Prometheus to provide distributed tracing, log management, and metrics.
- Plugin & Extension System: The “pkg/common/extension” area shows how the project supports third-party plugins and adapter extensions – critical for a customizable gateway solution.

##### Out Relationships and Data Flow
- These requests hit the Listener layer (HTTP, TCP, etc.) where initial protocol-specific handling occurs.
- The requests then flow into the Filter Chain, where multiple middleware components process them (security, traffic management, rate limiting, logging, etc.).
- Post filtering, the Core Server component routes the requests to the appropriate service endpoint. This stage leverages protocol adapters (located in the “pkg/adapter” and “pkg/client” directories) to translate and forward the request into, for example, Dubbo invocations.
- Load Balancers and Cluster Managers (in “pkg/cluster”) determine the exact backend service instance, possibly using health checks.
- On the outbound path, responses traverse the reverse path, possibly passing through additional filters for logging and tracing before returning to the client.
- Configuration and dynamic resource management (via “configcenter” and “pkg/config/xds”) interact with external registries (such as Nacos or Zookeeper, as seen in the “pkg/adapter/dubboregistry/registry” directories) and control plane elements, providing up-to-date service metadata and enabling dynamic routing updates.

##### Architectural Patterns and Technology Choices
- Modular/Plugin Architecture: The clear separation of concerns (listeners, filters, adapters, client modules) indicates a modular design that is well-suited for extension.
- Multi-Protocol Support: With dedicated protocols handled separately (HTTP, Dubbo, triple, gRPC), the system follows a strategy of protocol abstraction.
- Dynamic Configuration Management: Using YAML-based configurations and dynamic configuration loading (with Nacos-specific support) shows an emphasis on flexibility and runtime configuration.
- Integration with Observability Tools: Incorporation of tracing (Jaeger, OTLP), metrics (Prometheus), and logging ensures robust monitoring and logging for production deployments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    EC["External Clients (HTTP, gRPC)"]:::external

    %% Entry & Listener Layer
    subgraph "Entry & Listener Layer"
        GE["cmd/pixiu (Gateway Entry)"]:::entry
        HL["HTTP Listener"]:::listener
        H2["HTTP2 Listener"]:::listener
        TL["TCP Listener"]:::listener
        TRL["Triple Listener"]:::listener
    end

    %% Processing & Filter Chain
    subgraph "Processing & Filter Chain"
        FC["Filter Chain (Middleware)"]:::filter
        SC["Server Core"]:::core
    end

    %% Protocol Adapters & Client Invocation
    subgraph "Protocol Adapters & Client Invocation"
        PA["Protocol Adapter (Dubbo/SpringCloud)"]:::adapter
        CC["Client Connectors (Dubbo,HTTP,MQ,Triple)"]:::client
    end

    %% Clustering, Load Balancing & Health Check
    subgraph "Clustering, Load Balancing & Health Check"
        CL["Cluster Manager & Load Balancer"]:::cluster
    end

    %% Backend Services
    subgraph "Backend Services"
        BS["Backend Services (Dubbo Clusters)"]:::backend
    end

    %% Configuration & Control Plane
    subgraph "Configuration & Control Plane"
        SCONF["Static Config (YAML)"]:::config
        DNC["Dynamic Config (Nacos)"]:::config
        DXDS["Dynamic xDS Config"]:::config
    end

    %% Observability, Tracing & Logging
    subgraph "Observability, Tracing & Logging"
        OBS["Observability (Tracing,Metrics,Logging)"]:::observability
    end

    %% Plugin & Extension System
    subgraph "Plugin & Extension System"
        PE["Plugin & Extension System"]:::plugin
    end

    %% Data Flow Connections
    EC --> GE
    GE --> HL
    GE --> H2
    GE --> TL
    GE --> TRL

    HL --> FC
    H2 --> FC
    TL --> FC
    TRL --> FC

    FC --> SC
    SC --> PA
    PA --> CC
    CC --> CL
    CL --> BS

    %% Configuration feeds into Server Core
    SCONF -.-> SC
    DNC -.-> SC
    DXDS -.-> SC

    %% Observability monitors Filter Chain and Server Core
    OBS -.-> FC
    OBS -.-> SC

    %% Plugin system hooks into Server Core
    PE -.-> SC

    %% Styles
    classDef external fill:#E5E8E8,stroke:#7F8C8D,stroke-width:2px;
    classDef entry fill:#F9E79F,stroke:#F39C12,stroke-width:2px;
    classDef listener fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef filter fill:#ABEBC6,stroke:#27AE60,stroke-width:2px;
    classDef core fill:#FAD7A0,stroke:#F39C12,stroke-width:2px;
    classDef adapter fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef client fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
    classDef cluster fill:#F6E3B4,stroke:#D4AC0D,stroke-width:2px;
    classDef backend fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef config fill:#F0B27A,stroke:#E67E22,stroke-width:2px;
    classDef observability fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef plugin fill:#FAD7A0,stroke:#F39C12,stroke-width:2px;

    %% Click Events
    click GE "https://github.com/apache/dubbo-go-pixiu/blob/develop/cmd/pixiu/pixiu.go"
    click SCONF "https://github.com/apache/dubbo-go-pixiu/blob/develop/configs/conf.yaml"
    click DNC "https://github.com/apache/dubbo-go-pixiu/blob/develop/configcenter/nacos_load.go"
    click DXDS "https://github.com/apache/dubbo-go-pixiu/blob/develop/pkg/config/xds/xds.go"
    click SC "https://github.com/apache/dubbo-go-pixiu/blob/develop/pkg/server/pixiu_start.go"
    click FC "https://github.com/apache/dubbo-go-pixiu/blob/develop/pkg/filterchain/network_filter_chain.go"
    click PA "https://github.com/apache/dubbo-go-pixiu/tree/develop/pkg/adapter"
    click CC "https://github.com/apache/dubbo-go-pixiu/tree/develop/pkg/client"
    click CL "https://github.com/apache/dubbo-go-pixiu/blob/develop/pkg/cluster/cluster.go"
    click OBS "https://github.com/apache/dubbo-go-pixiu/blob/develop/pkg/logger/logger.go"
    click OBS "https://github.com/apache/dubbo-go-pixiu/blob/develop/pkg/prometheus/prometheus.go"
    click PE "https://github.com/apache/dubbo-go-pixiu/tree/develop/pkg/common/extension"
```
