# apache/shenyu architecture

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

- Interactive diagram: https://gitdiagram.com/apache/shenyu
- Repository: https://github.com/apache/shenyu

## Overview

Apache ShenYu is a service-proxy gateway with an Admin control plane. A client request enters the gateway, is handled through its extensible plugin chain, and is proxied to an upstream; separately, operators configure routes in Admin, which persists configuration and distributes updates for gateway replicas to apply. The README documents protocol conversion, registration/discovery, security and traffic controls, caching and transformation, observability, and AI/MCP features. Those capabilities are represented at subsystem level; sampled source details are limited, so undocumented internal call edges are omitted.

Main entry points: [`shenyu-web/src/main/java/org/apache/shenyu/web/loader/ShenyuLoaderService.java`](https://github.com/apache/shenyu/blob/master/shenyu-web/src/main/java/org/apache/shenyu/web/loader/ShenyuLoaderService.java) (Plugin chain), [`shenyu-admin/src/main/java/org/apache/shenyu/admin/controller/PluginController.java`](https://github.com/apache/shenyu/blob/master/shenyu-admin/src/main/java/org/apache/shenyu/admin/controller/PluginController.java) (Admin API), [`shenyu-admin/src/main/java/org/apache/shenyu/admin/mapper/PluginMapper.java`](https://github.com/apache/shenyu/blob/master/shenyu-admin/src/main/java/org/apache/shenyu/admin/mapper/PluginMapper.java) (Configuration store), [`shenyu-web/src/main/java/org/apache/shenyu/web/endpoint/ShenyuControllerEndpoint.java`](https://github.com/apache/shenyu/blob/master/shenyu-web/src/main/java/org/apache/shenyu/web/endpoint/ShenyuControllerEndpoint.java) (Gateway ingress)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway runtime"]
  node_gateway_entry["Gateway ingress"]
  node_plugin_chain["Plugin chain"]
  node_gateway_cache["Gateway config cache"]
end

subgraph group_admin["Admin control plane"]
  node_admin_api["Admin API"]
  node_admin_store[("Configuration store<br/>[PluginMapper.java]")]
  node_admin_auth["Authorization management"]
end

subgraph group_sync["Configuration sync"]
  node_sync_dispatch["Admin change dispatch"]
  node_sync_transport["Sync transports"]
  node_gateway_sync["Gateway sync service"]
end

subgraph group_extensions["Gateway capabilities"]
  node_security["Security controls<br/>[SignService.java]"]
  node_traffic["Traffic controls"]
  node_transform_cache["Transform and cache"]
  node_protocols["Protocol proxying"]
  node_ai_mcp["AI and MCP<br/>[AiProxyEngine.java]"]
end

subgraph group_operations["Registration and operations"]
  node_registration["Client registration"]
  node_discovery["Service discovery"]
  node_observability["Metrics and logging"]
  node_alerts["Admin alerts"]
end

node_caller(("API caller"))
node_upstream["Backend services"]
node_admin_user(("Operator"))

node_caller -->|"sends request"| node_gateway_entry
node_gateway_entry -->|"enters plugins"| node_plugin_chain
node_plugin_chain -->|"proxies request"| node_upstream
node_admin_user -->|"configures routes"| node_admin_api
node_admin_api -.->|"persists config"| node_admin_store
node_admin_api -.->|"manages auth"| node_admin_auth
node_registration -.->|"registers metadata"| node_admin_api
node_discovery -.->|"updates upstreams"| node_admin_store
node_admin_store -.->|"drives changes"| node_sync_dispatch
node_sync_dispatch -.->|"publishes updates"| node_sync_transport
node_sync_transport -->|"delivers updates"| node_gateway_sync
node_gateway_sync -->|"updates caches"| node_gateway_cache
node_gateway_cache -.->|"supplies config"| node_plugin_chain
node_plugin_chain -->|"applies controls"| node_security
node_plugin_chain -->|"selects upstream"| node_traffic
node_plugin_chain -->|"transforms requests"| node_transform_cache
node_plugin_chain -->|"converts protocols"| node_protocols
node_plugin_chain -->|"handles AI traffic"| node_ai_mcp
node_plugin_chain -->|"emits telemetry"| node_observability
node_admin_api -->|"sends alerts"| node_alerts

click node_gateway_entry "https://github.com/apache/shenyu/blob/master/shenyu-web/src/main/java/org/apache/shenyu/web/endpoint/ShenyuControllerEndpoint.java"
click node_plugin_chain "https://github.com/apache/shenyu/blob/master/shenyu-web/src/main/java/org/apache/shenyu/web/loader/ShenyuLoaderService.java"
click node_admin_api "https://github.com/apache/shenyu/blob/master/shenyu-admin/src/main/java/org/apache/shenyu/admin/controller/PluginController.java"
click node_admin_store "https://github.com/apache/shenyu/blob/master/shenyu-admin/src/main/java/org/apache/shenyu/admin/mapper/PluginMapper.java"
click node_admin_auth "https://github.com/apache/shenyu/blob/master/shenyu-admin/src/main/java/org/apache/shenyu/admin/service/AppAuthService.java"
click node_registration "https://github.com/apache/shenyu/blob/master/shenyu-admin/src/main/java/org/apache/shenyu/admin/service/register/AbstractContextPathRegisterService.java"
click node_discovery "https://github.com/apache/shenyu/blob/master/shenyu-admin/src/main/java/org/apache/shenyu/admin/discovery/DefaultDiscoveryProcessor.java"
click node_sync_dispatch "https://github.com/apache/shenyu/blob/master/shenyu-admin/src/main/java/org/apache/shenyu/admin/listener/DataChangedEventDispatcher.java"
click node_sync_transport "https://github.com/apache/shenyu/blob/master/shenyu-sync-data-center/shenyu-sync-data-websocket/src/main/java/org/apache/shenyu/plugin/sync/data/websocket/WebsocketSyncDataService.java"
click node_gateway_sync "https://github.com/apache/shenyu/blob/master/shenyu-sync-data-center/shenyu-sync-data-api/src/main/java/org/apache/shenyu/sync/data/core/AbstractNodeDataSyncService.java"
click node_gateway_cache "https://github.com/apache/shenyu/blob/master/shenyu-plugin/shenyu-plugin-base/src/main/java/org/apache/shenyu/plugin/base/cache/CommonPluginDataSubscriber.java"
click node_security "https://github.com/apache/shenyu/blob/master/shenyu-plugin/shenyu-plugin-security/shenyu-plugin-sign/src/main/java/org/apache/shenyu/plugin/sign/service/SignService.java"
click node_traffic "https://github.com/apache/shenyu/blob/master/shenyu-loadbalancer/src/main/java/org/apache/shenyu/loadbalancer/cache/UpstreamCacheManager.java"
click node_transform_cache "https://github.com/apache/shenyu/blob/master/shenyu-plugin/shenyu-plugin-context-path/src/main/java/org/apache/shenyu/plugin/context/path/handler/ContextPathPluginDataHandler.java"
click node_protocols "https://github.com/apache/shenyu/blob/master/shenyu-plugin/shenyu-plugin-proxy/shenyu-plugin-rpc/shenyu-plugin-dubbo/shenyu-plugin-apache-dubbo/src/main/java/org/apache/shenyu/plugin/apache/dubbo/proxy/ApacheDubboProxyService.java"
click node_ai_mcp "https://github.com/apache/shenyu/blob/master/shenyu-plugin/shenyu-plugin-ai/shenyu-plugin-ai-proxy/src/main/java/org/apache/shenyu/plugin/ai/proxy/enhanced/service/AiProxyEngine.java"
click node_observability "https://github.com/apache/shenyu/blob/master/shenyu-plugin/shenyu-plugin-metrics/src/main/java/org/apache/shenyu/plugin/metrics/prometheus/PrometheusMetricsService.java"
click node_alerts "https://github.com/apache/shenyu/blob/master/shenyu-alert/src/main/java/org/apache/shenyu/alert/AlertNotifyHandler.java"

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_gateway_entry,node_plugin_chain,node_gateway_cache toneBlue
class node_admin_api,node_admin_store,node_admin_auth toneAmber
class node_sync_dispatch,node_sync_transport,node_gateway_sync,node_caller toneMint
class node_security,node_traffic,node_transform_cache,node_protocols,node_ai_mcp toneRose
class node_registration,node_discovery,node_observability,node_alerts,node_upstream,node_admin_user toneIndigo
```

## Components

### Gateway runtime

- [Gateway ingress](https://github.com/apache/shenyu/blob/master/shenyu-web/src/main/java/org/apache/shenyu/web/endpoint/ShenyuControllerEndpoint.java): `shenyu-web/src/main/java/org/apache/shenyu/web/endpoint/ShenyuControllerEndpoint.java`
- [Plugin chain](https://github.com/apache/shenyu/blob/master/shenyu-web/src/main/java/org/apache/shenyu/web/loader/ShenyuLoaderService.java): `shenyu-web/src/main/java/org/apache/shenyu/web/loader/ShenyuLoaderService.java`
- [Gateway config cache](https://github.com/apache/shenyu/blob/master/shenyu-plugin/shenyu-plugin-base/src/main/java/org/apache/shenyu/plugin/base/cache/CommonPluginDataSubscriber.java): `shenyu-plugin/shenyu-plugin-base/src/main/java/org/apache/shenyu/plugin/base/cache/CommonPluginDataSubscriber.java`

### Admin control plane

- [Admin API](https://github.com/apache/shenyu/blob/master/shenyu-admin/src/main/java/org/apache/shenyu/admin/controller/PluginController.java): `shenyu-admin/src/main/java/org/apache/shenyu/admin/controller/PluginController.java`
- [Configuration store](https://github.com/apache/shenyu/blob/master/shenyu-admin/src/main/java/org/apache/shenyu/admin/mapper/PluginMapper.java): `shenyu-admin/src/main/java/org/apache/shenyu/admin/mapper/PluginMapper.java`
- [Authorization management](https://github.com/apache/shenyu/blob/master/shenyu-admin/src/main/java/org/apache/shenyu/admin/service/AppAuthService.java): `shenyu-admin/src/main/java/org/apache/shenyu/admin/service/AppAuthService.java`

### Configuration sync

- [Admin change dispatch](https://github.com/apache/shenyu/blob/master/shenyu-admin/src/main/java/org/apache/shenyu/admin/listener/DataChangedEventDispatcher.java): `shenyu-admin/src/main/java/org/apache/shenyu/admin/listener/DataChangedEventDispatcher.java`
- [Sync transports](https://github.com/apache/shenyu/blob/master/shenyu-sync-data-center/shenyu-sync-data-websocket/src/main/java/org/apache/shenyu/plugin/sync/data/websocket/WebsocketSyncDataService.java): `shenyu-sync-data-center/shenyu-sync-data-websocket/src/main/java/org/apache/shenyu/plugin/sync/data/websocket/WebsocketSyncDataService.java`
- [Gateway sync service](https://github.com/apache/shenyu/blob/master/shenyu-sync-data-center/shenyu-sync-data-api/src/main/java/org/apache/shenyu/sync/data/core/AbstractNodeDataSyncService.java): `shenyu-sync-data-center/shenyu-sync-data-api/src/main/java/org/apache/shenyu/sync/data/core/AbstractNodeDataSyncService.java`

### Gateway capabilities

- [Security controls](https://github.com/apache/shenyu/blob/master/shenyu-plugin/shenyu-plugin-security/shenyu-plugin-sign/src/main/java/org/apache/shenyu/plugin/sign/service/SignService.java): `shenyu-plugin/shenyu-plugin-security/shenyu-plugin-sign/src/main/java/org/apache/shenyu/plugin/sign/service/SignService.java`
- [Traffic controls](https://github.com/apache/shenyu/blob/master/shenyu-loadbalancer/src/main/java/org/apache/shenyu/loadbalancer/cache/UpstreamCacheManager.java): `shenyu-loadbalancer/src/main/java/org/apache/shenyu/loadbalancer/cache/UpstreamCacheManager.java`
- [Transform and cache](https://github.com/apache/shenyu/blob/master/shenyu-plugin/shenyu-plugin-context-path/src/main/java/org/apache/shenyu/plugin/context/path/handler/ContextPathPluginDataHandler.java): `shenyu-plugin/shenyu-plugin-context-path/src/main/java/org/apache/shenyu/plugin/context/path/handler/ContextPathPluginDataHandler.java`
- [Protocol proxying](https://github.com/apache/shenyu/blob/master/shenyu-plugin/shenyu-plugin-proxy/shenyu-plugin-rpc/shenyu-plugin-dubbo/shenyu-plugin-apache-dubbo/src/main/java/org/apache/shenyu/plugin/apache/dubbo/proxy/ApacheDubboProxyService.java): `shenyu-plugin/shenyu-plugin-proxy/shenyu-plugin-rpc/shenyu-plugin-dubbo/shenyu-plugin-apache-dubbo/src/main/java/org/apache/shenyu/plugin/apache/dubbo/proxy/ApacheDubboProxyService.java`
- [AI and MCP](https://github.com/apache/shenyu/blob/master/shenyu-plugin/shenyu-plugin-ai/shenyu-plugin-ai-proxy/src/main/java/org/apache/shenyu/plugin/ai/proxy/enhanced/service/AiProxyEngine.java): `shenyu-plugin/shenyu-plugin-ai/shenyu-plugin-ai-proxy/src/main/java/org/apache/shenyu/plugin/ai/proxy/enhanced/service/AiProxyEngine.java`

### Registration and operations

- [Client registration](https://github.com/apache/shenyu/blob/master/shenyu-admin/src/main/java/org/apache/shenyu/admin/service/register/AbstractContextPathRegisterService.java): `shenyu-admin/src/main/java/org/apache/shenyu/admin/service/register/AbstractContextPathRegisterService.java`
- [Service discovery](https://github.com/apache/shenyu/blob/master/shenyu-admin/src/main/java/org/apache/shenyu/admin/discovery/DefaultDiscoveryProcessor.java): `shenyu-admin/src/main/java/org/apache/shenyu/admin/discovery/DefaultDiscoveryProcessor.java`
- [Metrics and logging](https://github.com/apache/shenyu/blob/master/shenyu-plugin/shenyu-plugin-metrics/src/main/java/org/apache/shenyu/plugin/metrics/prometheus/PrometheusMetricsService.java): `shenyu-plugin/shenyu-plugin-metrics/src/main/java/org/apache/shenyu/plugin/metrics/prometheus/PrometheusMetricsService.java`
- [Admin alerts](https://github.com/apache/shenyu/blob/master/shenyu-alert/src/main/java/org/apache/shenyu/alert/AlertNotifyHandler.java): `shenyu-alert/src/main/java/org/apache/shenyu/alert/AlertNotifyHandler.java`

### Other components

- **API caller**
- **Backend services**
- **Operator**

## Connections

- API caller → Gateway ingress: sends request (evidence: `README.md`)
- Gateway ingress → Plugin chain: enters plugins (evidence: `README.md`)
- Plugin chain → Backend services: proxies request (evidence: `README.md`)
- Operator → Admin API: configures routes (evidence: `README.md`)
- Admin API → Configuration store: persists config
- Admin API → Authorization management: manages auth
- Client registration → Admin API: registers metadata
- Service discovery → Configuration store: updates upstreams
- Configuration store → Admin change dispatch: drives changes
- Admin change dispatch → Sync transports: publishes updates
- Sync transports → Gateway sync service: delivers updates (evidence: `README.md`)
- Gateway sync service → Gateway config cache: updates caches (evidence: `shenyu-sync-data-center/shenyu-sync-data-api/src/main/java/org/apache/shenyu/sync/data/core/AbstractNodeDataSyncService.java`)
- Gateway config cache → Plugin chain: supplies config (evidence: `shenyu-web/src/main/java/org/apache/shenyu/web/loader/ShenyuLoaderService.java`)
- Plugin chain → Security controls: applies controls (evidence: `README.md`)
- Plugin chain → Traffic controls: selects upstream (evidence: `README.md`)
- Plugin chain → Transform and cache: transforms requests (evidence: `README.md`)
- Plugin chain → Protocol proxying: converts protocols (evidence: `README.md`)
- Plugin chain → AI and MCP: handles AI traffic (evidence: `README.md`)
- Plugin chain → Metrics and logging: emits telemetry (evidence: `README.md`)
- Admin API → Admin alerts: sends alerts (evidence: `README.md`)