# zzl-qz/rover-suite architecture

> Architecture diagram of the GitHub repository zzl-qz/rover-suite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zzl-qz/rover-suite
- Repository: https://github.com/zzl-qz/rover-suite

## Overview

Rover-Suite combines service registration/discovery, an HTTP gateway, and an optional runtime Admin console. The principal flow is provider registration with Nameserver, registry snapshot push to gateway-side clients, then request routing to a healthy instance and proxying its response. Separate branches cover runtime visibility/configuration and extension points. Some links are based on README descriptions because their implementations were not sampled; dashed edges mark those unverified connections.

Main entry points: [`rover-gateway-core/src/main/java/com/rover/gateway/core/filter/RouteAndProxyFilter.java`](https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-core/src/main/java/com/rover/gateway/core/filter/RouteAndProxyFilter.java) (Route and Proxy), [`rover-gateway-core/src/main/java/com/rover/gateway/core/server/GatewayHttpServer.java`](https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-core/src/main/java/com/rover/gateway/core/server/GatewayHttpServer.java) (Gateway HTTP Server), [`rover-nameserver-core/src/main/java/com/rover/nameserver/core/registration/RegistrationService.java`](https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-core/src/main/java/com/rover/nameserver/core/registration/RegistrationService.java) (Registration Service), [`rover-admin/src/main/resources/static/js/app.js`](https://github.com/zzl-qz/rover-suite/blob/dev/rover-admin/src/main/resources/static/js/app.js) (Admin Console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_registration["Registration and Discovery"]
  node_starter["Java Starter"]
  node_ns_api["Nameserver APIs"]
  node_registration_service["Registration Service"]
  node_registry[("Service Registry")]
  node_push["Snapshot Push<br/>[PushService.java]"]
  node_client["Nameserver Client"]
  node_client_handler["Client Message Handler"]
  node_instance_cache[("Instance Cache<br/>[InstanceCache.java]")]
  node_nacos["Nacos Discovery"]
end

subgraph group_gateway["Gateway Runtime"]
  node_gateway_server["Gateway HTTP Server"]
  node_filters["Gateway Filters"]
  node_route_proxy["Route and Proxy"]
  node_load_balance["Load Balancing"]
  node_upstream["Upstream Proxy"]
end

subgraph group_operations["Operations and Config"]
  node_admin_ui["Admin Console<br/>[app.js]"]
  node_admin_api["Admin API"]
  node_admin_service["Admin Config Service"]
  node_manage_api["Manage APIs"]
  node_runtime_config["Runtime Configuration"]
end

subgraph group_shared["Shared Protocol"]
  node_protocol["Shared Protocol<br/>[RoverMessage.java]"]
end

node_providers(("Service Providers"))
node_gateway_callers(("HTTP Callers"))
node_admin_user(("Admin Operator"))

node_providers -->|"registers via"| node_starter
node_providers -->|"registers via"| node_ns_api
node_ns_api -.->|"delegates lifecycle"| node_registration_service
node_registration_service -->|"updates"| node_registry
node_registration_service -->|"pushes changes"| node_push
node_push -->|"pushes snapshots"| node_client
node_client_handler -->|"updates cache"| node_instance_cache
node_client -->|"reads instances"| node_instance_cache
node_gateway_callers -->|"sends requests"| node_gateway_server
node_gateway_server -.->|"dispatches through"| node_filters
node_filters -.->|"routes requests"| node_route_proxy
node_route_proxy -->|"uses instances"| node_instance_cache
node_route_proxy -.->|"selects instance"| node_load_balance
node_route_proxy -.->|"proxies request"| node_upstream
node_upstream -->|"forwards HTTP"| node_providers
node_nacos -.->|"optional discovery"| node_gateway_server
node_admin_user -->|"views operations"| node_admin_ui
node_admin_ui -.->|"calls management"| node_admin_api
node_admin_api -.->|"delegates actions"| node_admin_service
node_admin_service -->|"queries components"| node_manage_api
node_admin_service -.->|"updates settings"| node_runtime_config
node_admin_ui -->|"shows runtime state"| node_gateway_server
node_protocol -.->|"carries messages"| node_client

click node_starter "https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-starter/src/main/java/com/rover/nameserver/starter/autoconfigure/NameserverAutoConfiguration.java"
click node_ns_api "https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-core/src/main/java/com/rover/nameserver/core/clientapi/NameserverClientApi.java"
click node_registration_service "https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-core/src/main/java/com/rover/nameserver/core/registration/RegistrationService.java"
click node_registry "https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-core/src/main/java/com/rover/nameserver/core/registry/InMemoryServiceRegistry.java"
click node_push "https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-core/src/main/java/com/rover/nameserver/core/push/PushService.java"
click node_client "https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-client/src/main/java/com/rover/nameserver/client/connection/NameserverClient.java"
click node_client_handler "https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-client/src/main/java/com/rover/nameserver/client/handler/NameserverClientHandler.java"
click node_instance_cache "https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-client/src/main/java/com/rover/nameserver/client/cache/InstanceCache.java"
click node_gateway_server "https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-core/src/main/java/com/rover/gateway/core/server/GatewayHttpServer.java"
click node_filters "https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-core/src/main/java/com/rover/gateway/core/filter/GatewayFilterAssembler.java"
click node_route_proxy "https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-core/src/main/java/com/rover/gateway/core/filter/RouteAndProxyFilter.java"
click node_load_balance "https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-core/src/main/java/com/rover/gateway/core/loadbalance/LoadBalancerFactory.java"
click node_upstream "https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-core/src/main/java/com/rover/gateway/core/proxy/HttpProxyClient.java"
click node_nacos "https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-adapter-nacos/src/main/java/com/rover/gateway/adapter/nacos/NacosServiceDiscovery.java"
click node_admin_ui "https://github.com/zzl-qz/rover-suite/blob/dev/rover-admin/src/main/resources/static/js/app.js"
click node_admin_api "https://github.com/zzl-qz/rover-suite/blob/dev/rover-admin/src/main/java/com/rover/admin/web/AdminConfigController.java"
click node_admin_service "https://github.com/zzl-qz/rover-suite/blob/dev/rover-admin/src/main/java/com/rover/admin/service/AdminConfigService.java"
click node_manage_api "https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-core/src/main/java/com/rover/gateway/core/manage/GatewayManageApi.java"
click node_runtime_config "https://github.com/zzl-qz/rover-suite/blob/dev/rover-common/src/main/java/com/rover/common/config/AbstractRuntimeConfigManager.java"
click node_protocol "https://github.com/zzl-qz/rover-suite/blob/dev/rover-common/src/main/java/com/rover/common/protocol/RoverMessage.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_starter,node_ns_api,node_registration_service,node_registry,node_push,node_client,node_client_handler,node_instance_cache,node_nacos toneBlue
class node_gateway_server,node_filters,node_route_proxy,node_load_balance,node_upstream toneAmber
class node_admin_ui,node_admin_api,node_admin_service,node_manage_api,node_runtime_config toneMint
class node_protocol toneRose
class node_providers,node_gateway_callers,node_admin_user toneIndigo
```

## Components

### Registration and Discovery

- [Java Starter](https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-starter/src/main/java/com/rover/nameserver/starter/autoconfigure/NameserverAutoConfiguration.java): `rover-nameserver-starter/src/main/java/com/rover/nameserver/starter/autoconfigure/NameserverAutoConfiguration.java`
- [Nameserver APIs](https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-core/src/main/java/com/rover/nameserver/core/clientapi/NameserverClientApi.java): `rover-nameserver-core/src/main/java/com/rover/nameserver/core/clientapi/NameserverClientApi.java`
- [Registration Service](https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-core/src/main/java/com/rover/nameserver/core/registration/RegistrationService.java): `rover-nameserver-core/src/main/java/com/rover/nameserver/core/registration/RegistrationService.java`
- [Service Registry](https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-core/src/main/java/com/rover/nameserver/core/registry/InMemoryServiceRegistry.java): `rover-nameserver-core/src/main/java/com/rover/nameserver/core/registry/InMemoryServiceRegistry.java`
- [Snapshot Push](https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-core/src/main/java/com/rover/nameserver/core/push/PushService.java): `rover-nameserver-core/src/main/java/com/rover/nameserver/core/push/PushService.java`
- [Nameserver Client](https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-client/src/main/java/com/rover/nameserver/client/connection/NameserverClient.java): `rover-nameserver-client/src/main/java/com/rover/nameserver/client/connection/NameserverClient.java`
- [Client Message Handler](https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-client/src/main/java/com/rover/nameserver/client/handler/NameserverClientHandler.java): `rover-nameserver-client/src/main/java/com/rover/nameserver/client/handler/NameserverClientHandler.java`
- [Instance Cache](https://github.com/zzl-qz/rover-suite/blob/dev/rover-nameserver-client/src/main/java/com/rover/nameserver/client/cache/InstanceCache.java): `rover-nameserver-client/src/main/java/com/rover/nameserver/client/cache/InstanceCache.java`
- [Nacos Discovery](https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-adapter-nacos/src/main/java/com/rover/gateway/adapter/nacos/NacosServiceDiscovery.java): `rover-gateway-adapter-nacos/src/main/java/com/rover/gateway/adapter/nacos/NacosServiceDiscovery.java`

### Gateway Runtime

- [Gateway HTTP Server](https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-core/src/main/java/com/rover/gateway/core/server/GatewayHttpServer.java): `rover-gateway-core/src/main/java/com/rover/gateway/core/server/GatewayHttpServer.java`
- [Gateway Filters](https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-core/src/main/java/com/rover/gateway/core/filter/GatewayFilterAssembler.java): `rover-gateway-core/src/main/java/com/rover/gateway/core/filter/GatewayFilterAssembler.java`
- [Route and Proxy](https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-core/src/main/java/com/rover/gateway/core/filter/RouteAndProxyFilter.java): `rover-gateway-core/src/main/java/com/rover/gateway/core/filter/RouteAndProxyFilter.java`
- [Load Balancing](https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-core/src/main/java/com/rover/gateway/core/loadbalance/LoadBalancerFactory.java): `rover-gateway-core/src/main/java/com/rover/gateway/core/loadbalance/LoadBalancerFactory.java`
- [Upstream Proxy](https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-core/src/main/java/com/rover/gateway/core/proxy/HttpProxyClient.java): `rover-gateway-core/src/main/java/com/rover/gateway/core/proxy/HttpProxyClient.java`

### Operations and Config

- [Admin Console](https://github.com/zzl-qz/rover-suite/blob/dev/rover-admin/src/main/resources/static/js/app.js): `rover-admin/src/main/resources/static/js/app.js`
- [Admin API](https://github.com/zzl-qz/rover-suite/blob/dev/rover-admin/src/main/java/com/rover/admin/web/AdminConfigController.java): `rover-admin/src/main/java/com/rover/admin/web/AdminConfigController.java`
- [Admin Config Service](https://github.com/zzl-qz/rover-suite/blob/dev/rover-admin/src/main/java/com/rover/admin/service/AdminConfigService.java): `rover-admin/src/main/java/com/rover/admin/service/AdminConfigService.java`
- [Manage APIs](https://github.com/zzl-qz/rover-suite/blob/dev/rover-gateway-core/src/main/java/com/rover/gateway/core/manage/GatewayManageApi.java): `rover-gateway-core/src/main/java/com/rover/gateway/core/manage/GatewayManageApi.java`
- [Runtime Configuration](https://github.com/zzl-qz/rover-suite/blob/dev/rover-common/src/main/java/com/rover/common/config/AbstractRuntimeConfigManager.java): `rover-common/src/main/java/com/rover/common/config/AbstractRuntimeConfigManager.java`

### Shared Protocol

- [Shared Protocol](https://github.com/zzl-qz/rover-suite/blob/dev/rover-common/src/main/java/com/rover/common/protocol/RoverMessage.java): `rover-common/src/main/java/com/rover/common/protocol/RoverMessage.java`

### Other components

- **Service Providers**
- **HTTP Callers**
- **Admin Operator**

## Connections

- Service Providers → Java Starter: registers via (evidence: `README.md`)
- Service Providers → Nameserver APIs: registers via (evidence: `README.md`)
- Nameserver APIs → Registration Service: delegates lifecycle
- Registration Service → Service Registry: updates (evidence: `rover-nameserver-core/src/main/java/com/rover/nameserver/core/registration/RegistrationService.java`)
- Registration Service → Snapshot Push: pushes changes (evidence: `rover-nameserver-core/src/main/java/com/rover/nameserver/core/registration/RegistrationService.java`)
- Snapshot Push → Nameserver Client: pushes snapshots (evidence: `README.md`)
- Client Message Handler → Instance Cache: updates cache (evidence: `rover-nameserver-client/src/main/java/com/rover/nameserver/client/handler/NameserverClientHandler.java`)
- Nameserver Client → Instance Cache: reads instances (evidence: `rover-nameserver-client/src/main/java/com/rover/nameserver/client/connection/NameserverClient.java`)
- HTTP Callers → Gateway HTTP Server: sends requests (evidence: `README.md`)
- Gateway HTTP Server → Gateway Filters: dispatches through
- Gateway Filters → Route and Proxy: routes requests
- Route and Proxy → Instance Cache: uses instances (evidence: `README.md`)
- Route and Proxy → Load Balancing: selects instance
- Route and Proxy → Upstream Proxy: proxies request
- Upstream Proxy → Service Providers: forwards HTTP (evidence: `README.md`)
- Nacos Discovery → Gateway HTTP Server: optional discovery (evidence: `README.md`)
- Admin Operator → Admin Console: views operations (evidence: `README.md`)
- Admin Console → Admin API: calls management
- Admin API → Admin Config Service: delegates actions
- Admin Config Service → Manage APIs: queries components (evidence: `rover-admin/src/main/java/com/rover/admin/service/AdminConfigService.java`)
- Admin Config Service → Runtime Configuration: updates settings
- Admin Console → Gateway HTTP Server: shows runtime state (evidence: `README.md`)
- Shared Protocol → Nameserver Client: carries messages (evidence: `rover-nameserver-client/src/main/java/com/rover/nameserver/client/connection/NameserverClient.java`)