# apache/hbase architecture

> Architecture diagram of the GitHub repository apache/hbase, 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/apache/hbase
- Repository: https://github.com/apache/hbase

## Overview

Apache HBase is a distributed, versioned, column-oriented store modeled after Bigtable and built on Hadoop storage. Its principal workflow is a client issuing table operations against regions hosted by region servers, where stores manage persisted data. The graph also preserves major runtime capabilities visible in the repository tree: cluster placement, replication, backup and restore, access control, and service interfaces. Several connections are dashed because the relevant runtime wiring is not shown in the excerpts; the README establishes HBase’s Hadoop-backed storage model.

Main entry points: [`hbase-client/src/main/java/org/apache/hadoop/hbase/client/Table.java`](https://github.com/apache/hbase/blob/master/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Table.java) (Table client API), [`hbase-server/src/main/java/org/apache/hadoop/hbase/master`](https://github.com/apache/hbase/tree/master/hbase-server/src/main/java/org/apache/hadoop/hbase/master) (Master services), [`hbase-server/src/main/java/org/apache/hadoop/hbase/regionserver`](https://github.com/apache/hbase/tree/master/hbase-server/src/main/java/org/apache/hadoop/hbase/regionserver) (Region server), [`hbase-server/src/main/java/org/apache/hadoop/hbase/regionserver/StoreEngine.java`](https://github.com/apache/hbase/blob/master/hbase-server/src/main/java/org/apache/hadoop/hbase/regionserver/StoreEngine.java) (Store engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client access"]
  node_client_api["Table client API<br/>[Table.java]"]
  node_region_info["Region metadata<br/>[RegionInfo.java]"]
  node_cell_model["Cell data model<br/>[Cell.java]"]
end

subgraph group_cluster["Cluster runtime"]
  node_master["Master services"]
  node_balancer["Region balancing"]
  node_regionserver["Region server"]
  node_event_executor["Event execution"]
  node_chore_scheduler["Periodic chores<br/>[ChoreService.java]"]
end

subgraph group_storage["Data storage"]
  node_store_engine["Store engine<br/>[StoreEngine.java]"]
  node_hadoop_fs[("Hadoop storage")]
  node_async_output["Async filesystem output<br/>[AsyncFSOutput.java]"]
end

subgraph group_protection["Data protection"]
  node_replication[("Replication queues")]
  node_replication_migration["Queue migration"]
  node_backup["Backup and restore"]
  node_backup_coord["Backup log coordination"]
  node_permissions[("Access permissions")]
end

subgraph group_interfaces["Service interfaces"]
  node_rest["REST service"]
  node_thrift["Thrift service"]
end

node_user(("HBase user"))
node_external_app(("External application"))
node_zookeeper[("ZooKeeper")]

node_user -.->|"issues operations"| node_client_api
node_client_api -.->|"uses region metadata"| node_region_info
node_client_api -.->|"routes operations"| node_regionserver
node_regionserver -.->|"accesses stores"| node_store_engine
node_store_engine -.->|"persists data"| node_hadoop_fs
node_store_engine -.->|"writes asynchronously"| node_async_output
node_master -.->|"assigns regions"| node_balancer
node_master -.->|"coordinates cluster"| node_regionserver
node_regionserver -.->|"submits events"| node_event_executor
node_chore_scheduler -.->|"schedules chores"| node_master
node_replication -->|"reads and writes tables"| node_client_api
node_replication_migration -->|"reads queue state"| node_zookeeper
node_backup -.->|"stores backup data"| node_hadoop_fs
node_backup_coord -->|"coordinates log roll"| node_master
node_backup_coord -->|"coordinates procedure"| node_zookeeper
node_permissions -->|"reads and writes ACL table"| node_client_api
node_external_app -.->|"calls API"| node_rest
node_external_app -.->|"calls API"| node_thrift

click node_client_api "https://github.com/apache/hbase/blob/master/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Table.java"
click node_region_info "https://github.com/apache/hbase/blob/master/hbase-client/src/main/java/org/apache/hadoop/hbase/client/RegionInfo.java"
click node_cell_model "https://github.com/apache/hbase/blob/master/hbase-common/src/main/java/org/apache/hadoop/hbase/Cell.java"
click node_master "https://github.com/apache/hbase/tree/master/hbase-server/src/main/java/org/apache/hadoop/hbase/master"
click node_balancer "https://github.com/apache/hbase/tree/master/hbase-balancer/src/main/java/org/apache/hadoop/hbase/master/balancer"
click node_regionserver "https://github.com/apache/hbase/tree/master/hbase-server/src/main/java/org/apache/hadoop/hbase/regionserver"
click node_event_executor "https://github.com/apache/hbase/blob/master/hbase-server/src/main/java/org/apache/hadoop/hbase/executor/ExecutorService.java"
click node_chore_scheduler "https://github.com/apache/hbase/blob/master/hbase-common/src/main/java/org/apache/hadoop/hbase/ChoreService.java"
click node_store_engine "https://github.com/apache/hbase/blob/master/hbase-server/src/main/java/org/apache/hadoop/hbase/regionserver/StoreEngine.java"
click node_async_output "https://github.com/apache/hbase/blob/master/hbase-asyncfs/src/main/java/org/apache/hadoop/hbase/io/asyncfs/AsyncFSOutput.java"
click node_replication "https://github.com/apache/hbase/blob/master/hbase-replication/src/main/java/org/apache/hadoop/hbase/replication/TableReplicationQueueStorage.java"
click node_replication_migration "https://github.com/apache/hbase/blob/master/hbase-replication/src/main/java/org/apache/hadoop/hbase/replication/ZKReplicationQueueStorageForMigration.java"
click node_backup "https://github.com/apache/hbase/tree/master/hbase-backup/src/main/java/org/apache/hadoop/hbase/backup"
click node_backup_coord "https://github.com/apache/hbase/blob/master/hbase-backup/src/main/java/org/apache/hadoop/hbase/backup/master/LogRollMasterProcedureManager.java"
click node_permissions "https://github.com/apache/hbase/blob/master/hbase-server/src/main/java/org/apache/hadoop/hbase/security/access/PermissionStorage.java"
click node_rest "https://github.com/apache/hbase/tree/master/hbase-rest/src/main/java/org/apache/hadoop/hbase/rest"
click node_thrift "https://github.com/apache/hbase/tree/master/hbase-thrift/src/main/java/org/apache/hadoop/hbase/thrift"

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_client_api,node_region_info,node_cell_model,node_user toneBlue
class node_master,node_balancer,node_regionserver,node_event_executor,node_chore_scheduler,node_zookeeper toneAmber
class node_store_engine,node_hadoop_fs,node_async_output toneMint
class node_replication,node_replication_migration,node_backup,node_backup_coord,node_permissions toneRose
class node_rest,node_thrift,node_external_app toneIndigo
```

## Components

### Client access

- [Table client API](https://github.com/apache/hbase/blob/master/hbase-client/src/main/java/org/apache/hadoop/hbase/client/Table.java): `hbase-client/src/main/java/org/apache/hadoop/hbase/client/Table.java`
- [Region metadata](https://github.com/apache/hbase/blob/master/hbase-client/src/main/java/org/apache/hadoop/hbase/client/RegionInfo.java): `hbase-client/src/main/java/org/apache/hadoop/hbase/client/RegionInfo.java`
- [Cell data model](https://github.com/apache/hbase/blob/master/hbase-common/src/main/java/org/apache/hadoop/hbase/Cell.java): `hbase-common/src/main/java/org/apache/hadoop/hbase/Cell.java`

### Cluster runtime

- [Master services](https://github.com/apache/hbase/tree/master/hbase-server/src/main/java/org/apache/hadoop/hbase/master): `hbase-server/src/main/java/org/apache/hadoop/hbase/master`
- [Region balancing](https://github.com/apache/hbase/tree/master/hbase-balancer/src/main/java/org/apache/hadoop/hbase/master/balancer): `hbase-balancer/src/main/java/org/apache/hadoop/hbase/master/balancer`
- [Region server](https://github.com/apache/hbase/tree/master/hbase-server/src/main/java/org/apache/hadoop/hbase/regionserver): `hbase-server/src/main/java/org/apache/hadoop/hbase/regionserver`
- [Event execution](https://github.com/apache/hbase/blob/master/hbase-server/src/main/java/org/apache/hadoop/hbase/executor/ExecutorService.java): `hbase-server/src/main/java/org/apache/hadoop/hbase/executor/ExecutorService.java`
- [Periodic chores](https://github.com/apache/hbase/blob/master/hbase-common/src/main/java/org/apache/hadoop/hbase/ChoreService.java): `hbase-common/src/main/java/org/apache/hadoop/hbase/ChoreService.java`

### Data storage

- [Store engine](https://github.com/apache/hbase/blob/master/hbase-server/src/main/java/org/apache/hadoop/hbase/regionserver/StoreEngine.java): `hbase-server/src/main/java/org/apache/hadoop/hbase/regionserver/StoreEngine.java`
- **Hadoop storage**
- [Async filesystem output](https://github.com/apache/hbase/blob/master/hbase-asyncfs/src/main/java/org/apache/hadoop/hbase/io/asyncfs/AsyncFSOutput.java): `hbase-asyncfs/src/main/java/org/apache/hadoop/hbase/io/asyncfs/AsyncFSOutput.java`

### Data protection

- [Replication queues](https://github.com/apache/hbase/blob/master/hbase-replication/src/main/java/org/apache/hadoop/hbase/replication/TableReplicationQueueStorage.java): `hbase-replication/src/main/java/org/apache/hadoop/hbase/replication/TableReplicationQueueStorage.java`
- [Queue migration](https://github.com/apache/hbase/blob/master/hbase-replication/src/main/java/org/apache/hadoop/hbase/replication/ZKReplicationQueueStorageForMigration.java): `hbase-replication/src/main/java/org/apache/hadoop/hbase/replication/ZKReplicationQueueStorageForMigration.java`
- [Backup and restore](https://github.com/apache/hbase/tree/master/hbase-backup/src/main/java/org/apache/hadoop/hbase/backup): `hbase-backup/src/main/java/org/apache/hadoop/hbase/backup`
- [Backup log coordination](https://github.com/apache/hbase/blob/master/hbase-backup/src/main/java/org/apache/hadoop/hbase/backup/master/LogRollMasterProcedureManager.java): `hbase-backup/src/main/java/org/apache/hadoop/hbase/backup/master/LogRollMasterProcedureManager.java`
- [Access permissions](https://github.com/apache/hbase/blob/master/hbase-server/src/main/java/org/apache/hadoop/hbase/security/access/PermissionStorage.java): `hbase-server/src/main/java/org/apache/hadoop/hbase/security/access/PermissionStorage.java`

### Service interfaces

- [REST service](https://github.com/apache/hbase/tree/master/hbase-rest/src/main/java/org/apache/hadoop/hbase/rest): `hbase-rest/src/main/java/org/apache/hadoop/hbase/rest`
- [Thrift service](https://github.com/apache/hbase/tree/master/hbase-thrift/src/main/java/org/apache/hadoop/hbase/thrift): `hbase-thrift/src/main/java/org/apache/hadoop/hbase/thrift`

### Other components

- **HBase user**
- **External application**
- **ZooKeeper**

## Connections

- HBase user → Table client API: issues operations
- Table client API → Region metadata: uses region metadata
- Table client API → Region server: routes operations
- Region server → Store engine: accesses stores (evidence: `hbase-server/src/main/java/org/apache/hadoop/hbase/regionserver/StoreEngine.java`)
- Store engine → Hadoop storage: persists data
- Store engine → Async filesystem output: writes asynchronously
- Master services → Region balancing: assigns regions
- Master services → Region server: coordinates cluster (evidence: `hbase-server/src/main/java/org/apache/hadoop/hbase/master/replication/OfflineTableReplicationQueueStorage.java`)
- Region server → Event execution: submits events (evidence: `hbase-server/src/main/java/org/apache/hadoop/hbase/regionserver/StoreEngine.java`)
- Periodic chores → Master services: schedules chores
- Replication queues → Table client API: reads and writes tables (evidence: `hbase-replication/src/main/java/org/apache/hadoop/hbase/replication/TableReplicationQueueStorage.java`)
- Queue migration → ZooKeeper: reads queue state (evidence: `hbase-replication/src/main/java/org/apache/hadoop/hbase/replication/ZKReplicationQueueStorageForMigration.java`)
- Backup and restore → Hadoop storage: stores backup data
- Backup log coordination → Master services: coordinates log roll (evidence: `hbase-backup/src/main/java/org/apache/hadoop/hbase/backup/master/LogRollMasterProcedureManager.java`)
- Backup log coordination → ZooKeeper: coordinates procedure (evidence: `hbase-backup/src/main/java/org/apache/hadoop/hbase/backup/master/LogRollMasterProcedureManager.java`)
- Access permissions → Table client API: reads and writes ACL table (evidence: `hbase-server/src/main/java/org/apache/hadoop/hbase/security/access/PermissionStorage.java`)
- External application → REST service: calls API
- External application → Thrift service: calls API