# apache/helix architecture

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

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

## Overview

Apache Helix is a cluster-management framework for partitioned, replicated resources. The principal workflow starts with an operator or application configuring a cluster, proceeds through controller-driven assignment and failure recovery, and reaches participants that execute state transitions; Helix publishes resulting cluster state for clients to observe. The repository also includes messaging, REST management, and a gRPC gateway. The README documents the high-level workflow and capabilities; sampled source and the source index support selected internal relationships, while unsampled subsystem internals are represented conservatively.

Main entry points: [`helix-core/src/main/java/org/apache/helix/controller/GenericHelixController.java`](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/controller/GenericHelixController.java) (Controller event loop), [`helix-core/src/main/java/org/apache/helix/HelixManager.java`](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/HelixManager.java) (Cluster manager), [`helix-rest/src/main/java/org/apache/helix/rest/server/service/ClusterService.java`](https://github.com/apache/helix/blob/master/helix-rest/src/main/java/org/apache/helix/rest/server/service/ClusterService.java) (REST cluster services), [`helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java`](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java) (Cluster data access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Cluster APIs"]
  node_manager["Cluster manager<br/>[HelixManager.java]"]
  node_admin["Cluster administration<br/>[HelixAdmin.java]"]
  node_config["Config access"]
  node_dataaccess["Cluster data access"]
  node_zk[("ZooKeeper coordination<br/>[ZkClient.java]")]
end

subgraph group_control["Controller"]
  node_controller["Controller event loop"]
  node_cache["Cluster state cache"]
  node_rebalance["Rebalancers"]
  node_strategy["Assignment strategies"]
  node_externalview["External view"]
end

subgraph group_participant["Participants"]
  node_messaging["Cluster messaging"]
  node_engine["State machine engine"]
  node_state["Participant state<br/>[Message.java]"]
end

subgraph group_extensions["Services"]
  node_gateway["gRPC gateway"]
  node_gatewaychannel["Gateway channel"]
  node_rest["REST cluster services"]
  node_maintenance["Maintenance checks"]
  node_topology["Virtual topology"]
end

node_operator(("Operator / app"))
node_client(("Gateway client"))

node_operator -->|"connects"| node_manager
node_operator -->|"manages cluster"| node_admin
node_admin -.->|"sets configuration"| node_config
node_manager -.->|"accesses state"| node_dataaccess
node_dataaccess -.->|"reads and writes"| node_zk
node_controller -.->|"loads state"| node_cache
node_controller -->|"computes placement"| node_rebalance
node_rebalance -.->|"selects assignments"| node_strategy
node_controller -.->|"dispatches transitions"| node_messaging
node_messaging -->|"delivers messages"| node_engine
node_engine -->|"executes transitions"| node_state
node_state -.->|"persists state"| node_dataaccess
node_controller -.->|"generates view"| node_externalview
node_externalview -->|"exposes cluster state"| node_operator
node_client -->|"connects by gRPC"| node_gatewaychannel
node_gatewaychannel -->|"routes events"| node_gateway
node_gateway -->|"joins cluster"| node_manager
node_operator -.->|"requests management"| node_rest
node_rest -->|"checks stoppability"| node_maintenance
node_rest -->|"configures topology"| node_topology
node_manager -.->|"observes cluster state"| node_externalview

click node_manager "https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/HelixManager.java"
click node_admin "https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/HelixAdmin.java"
click node_config "https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/ConfigAccessor.java"
click node_dataaccess "https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java"
click node_zk "https://github.com/apache/helix/blob/master/zookeeper-api/src/main/java/org/apache/helix/zookeeper/zkclient/ZkClient.java"
click node_controller "https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/controller/GenericHelixController.java"
click node_cache "https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/common/caches/BasicClusterDataCache.java"
click node_rebalance "https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/controller/rebalancer/AutoRebalancer.java"
click node_strategy "https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/controller/rebalancer/strategy/ConstraintRebalanceStrategy.java"
click node_externalview "https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/controller/ExternalViewGenerator.java"
click node_messaging "https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/messaging/DefaultMessagingService.java"
click node_engine "https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/participant/HelixStateMachineEngine.java"
click node_state "https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/model/Message.java"
click node_gateway "https://github.com/apache/helix/blob/master/helix-gateway/src/main/java/org/apache/helix/gateway/service/GatewayServiceManager.java"
click node_gatewaychannel "https://github.com/apache/helix/blob/master/helix-gateway/src/main/java/org/apache/helix/gateway/channel/HelixGatewayServicePollModeChannel.java"
click node_rest "https://github.com/apache/helix/blob/master/helix-rest/src/main/java/org/apache/helix/rest/server/service/ClusterService.java"
click node_maintenance "https://github.com/apache/helix/blob/master/helix-rest/src/main/java/org/apache/helix/rest/clusterMaintenanceService/MaintenanceManagementService.java"
click node_topology "https://github.com/apache/helix/blob/master/helix-rest/src/main/java/org/apache/helix/rest/server/service/VirtualTopologyGroupService.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_manager,node_admin,node_config,node_dataaccess,node_zk,node_client toneBlue
class node_controller,node_cache,node_rebalance,node_strategy,node_externalview toneAmber
class node_messaging,node_engine,node_state toneMint
class node_gateway,node_gatewaychannel,node_rest,node_maintenance,node_topology toneRose
class node_operator toneIndigo
```

## Components

### Cluster APIs

- [Cluster manager](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/HelixManager.java): `helix-core/src/main/java/org/apache/helix/HelixManager.java`
- [Cluster administration](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/HelixAdmin.java): `helix-core/src/main/java/org/apache/helix/HelixAdmin.java`
- [Config access](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/ConfigAccessor.java): `helix-core/src/main/java/org/apache/helix/ConfigAccessor.java`
- [Cluster data access](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java): `helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java`
- [ZooKeeper coordination](https://github.com/apache/helix/blob/master/zookeeper-api/src/main/java/org/apache/helix/zookeeper/zkclient/ZkClient.java): `zookeeper-api/src/main/java/org/apache/helix/zookeeper/zkclient/ZkClient.java`

### Controller

- [Controller event loop](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/controller/GenericHelixController.java): `helix-core/src/main/java/org/apache/helix/controller/GenericHelixController.java`
- [Cluster state cache](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/common/caches/BasicClusterDataCache.java): `helix-core/src/main/java/org/apache/helix/common/caches/BasicClusterDataCache.java`
- [Rebalancers](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/controller/rebalancer/AutoRebalancer.java): `helix-core/src/main/java/org/apache/helix/controller/rebalancer/AutoRebalancer.java`
- [Assignment strategies](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/controller/rebalancer/strategy/ConstraintRebalanceStrategy.java): `helix-core/src/main/java/org/apache/helix/controller/rebalancer/strategy/ConstraintRebalanceStrategy.java`
- [External view](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/controller/ExternalViewGenerator.java): `helix-core/src/main/java/org/apache/helix/controller/ExternalViewGenerator.java`

### Participants

- [Cluster messaging](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/messaging/DefaultMessagingService.java): `helix-core/src/main/java/org/apache/helix/messaging/DefaultMessagingService.java`
- [State machine engine](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/participant/HelixStateMachineEngine.java): `helix-core/src/main/java/org/apache/helix/participant/HelixStateMachineEngine.java`
- [Participant state](https://github.com/apache/helix/blob/master/helix-core/src/main/java/org/apache/helix/model/Message.java): `helix-core/src/main/java/org/apache/helix/model/Message.java`

### Services

- [gRPC gateway](https://github.com/apache/helix/blob/master/helix-gateway/src/main/java/org/apache/helix/gateway/service/GatewayServiceManager.java): `helix-gateway/src/main/java/org/apache/helix/gateway/service/GatewayServiceManager.java`
- [Gateway channel](https://github.com/apache/helix/blob/master/helix-gateway/src/main/java/org/apache/helix/gateway/channel/HelixGatewayServicePollModeChannel.java): `helix-gateway/src/main/java/org/apache/helix/gateway/channel/HelixGatewayServicePollModeChannel.java`
- [REST cluster services](https://github.com/apache/helix/blob/master/helix-rest/src/main/java/org/apache/helix/rest/server/service/ClusterService.java): `helix-rest/src/main/java/org/apache/helix/rest/server/service/ClusterService.java`
- [Maintenance checks](https://github.com/apache/helix/blob/master/helix-rest/src/main/java/org/apache/helix/rest/clusterMaintenanceService/MaintenanceManagementService.java): `helix-rest/src/main/java/org/apache/helix/rest/clusterMaintenanceService/MaintenanceManagementService.java`
- [Virtual topology](https://github.com/apache/helix/blob/master/helix-rest/src/main/java/org/apache/helix/rest/server/service/VirtualTopologyGroupService.java): `helix-rest/src/main/java/org/apache/helix/rest/server/service/VirtualTopologyGroupService.java`

### Other components

- **Operator / app**
- **Gateway client**

## Connections

- Operator / app → Cluster manager: connects (evidence: `helix-core/src/main/java/org/apache/helix/HelixManager.java`)
- Operator / app → Cluster administration: manages cluster (evidence: `README.md`)
- Cluster administration → Config access: sets configuration
- Cluster manager → Cluster data access: accesses state (evidence: `helix-core/src/main/java/org/apache/helix/HelixManager.java`)
- Cluster data access → ZooKeeper coordination: reads and writes
- Controller event loop → Cluster state cache: loads state
- Controller event loop → Rebalancers: computes placement (evidence: `README.md`)
- Rebalancers → Assignment strategies: selects assignments
- Controller event loop → Cluster messaging: dispatches transitions
- Cluster messaging → State machine engine: delivers messages (evidence: `helix-core/src/main/java/org/apache/helix/messaging/DefaultMessagingService.java`)
- State machine engine → Participant state: executes transitions (evidence: `helix-core/src/main/java/org/apache/helix/participant/HelixStateMachineEngine.java`)
- Participant state → Cluster data access: persists state (evidence: `helix-core/src/main/java/org/apache/helix/HelixDataAccessor.java`)
- Controller event loop → External view: generates view
- External view → Operator / app: exposes cluster state (evidence: `README.md`)
- Gateway client → Gateway channel: connects by gRPC (evidence: `README.md`)
- Gateway channel → gRPC gateway: routes events (evidence: `helix-gateway/src/main/java/org/apache/helix/gateway/channel/HelixGatewayServicePollModeChannel.java`)
- gRPC gateway → Cluster manager: joins cluster (evidence: `README.md`)
- Operator / app → REST cluster services: requests management
- REST cluster services → Maintenance checks: checks stoppability (evidence: `helix-rest/src/main/java/org/apache/helix/rest/clusterMaintenanceService/MaintenanceManagementService.java`)
- REST cluster services → Virtual topology: configures topology (evidence: `helix-rest/src/main/java/org/apache/helix/rest/server/service/VirtualTopologyGroupService.java`)
- Cluster manager → External view: observes cluster state
