# apache/fluss architecture

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

## Overview

Apache Fluss is a streaming-storage system that unifies low-latency table access with lakehouse storage. The principal workflow is an engine or application writing records to Fluss tables, then reading streaming or historical data through scans and lake integrations; administrators also manage cluster and table metadata. The repository includes client APIs, server-side coordination and tablet services, lake-format integrations, and Flink adapters. Some central implementations are not excerpted, so uncertain internal calls are omitted; README-documented capabilities are retained without asserting unsupported wiring.

Main entry points: [`fluss-server/src/main/java/org/apache/fluss/server/tablet/TabletService.java`](https://github.com/apache/fluss/blob/main/fluss-server/src/main/java/org/apache/fluss/server/tablet/TabletService.java) (Tablet service), [`fluss-common/src/main/java/org/apache/fluss/lake/lakestorage/PluginLakeStorageWrapper.java`](https://github.com/apache/fluss/blob/main/fluss-common/src/main/java/org/apache/fluss/lake/lakestorage/PluginLakeStorageWrapper.java) (Lake storage contract), [`fluss-client/src/main/java/org/apache/fluss/client/table/FlussTable.java`](https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/table/FlussTable.java) (Table API), [`fluss-client/src/main/java/org/apache/fluss/client/FlussConnection.java`](https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/FlussConnection.java) (Client connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client access"]
  node_connection["Client connection"]
  node_admin["Admin operations<br/>[FlussAdmin.java]"]
  node_table["Table API<br/>[FlussTable.java]"]
  node_writers["Table writers"]
  node_scanners["Table scanners"]
  node_lookup["Point lookup"]
  node_offsets["Offset initialization"]
end

subgraph group_server["Fluss services"]
  node_coordinator["Coordinator"]
  node_tablet["Tablet service<br/>[TabletService.java]"]
  node_kv["KV management<br/>[KvManager.java]"]
  node_replica["Replica management"]
  node_remote["Remote log storage"]
end

subgraph group_lake["Lakehouse storage"]
  node_lakeapi["Lake storage contract"]
  node_paimon["Paimon integration"]
  node_iceberg["Iceberg integration"]
  node_lance["Lance integration"]
  node_hudi["Hudi compaction"]
  node_lakewriter["Lake tiering<br/>[LakeStorage.java]"]
end

subgraph group_engines["Compute integrations"]
  node_flink["Flink integration"]
end

node_application(("Engine or app"))

node_application -->|"connects"| node_connection
node_connection -.->|"opens tables"| node_table
node_connection -.->|"administers"| node_admin
node_table -.->|"writes through"| node_writers
node_table -.->|"scans through"| node_scanners
node_table -.->|"looks up"| node_lookup
node_scanners -.->|"starts at"| node_offsets
node_writers -.->|"ingests records"| node_tablet
node_scanners -.->|"reads records"| node_tablet
node_lookup -.->|"queries tables"| node_tablet
node_admin -.->|"manages metadata"| node_coordinator
node_coordinator -.->|"coordinates"| node_tablet
node_tablet -.->|"serves state"| node_kv
node_tablet -.->|"uses replicas"| node_replica
node_tablet -.->|"uses remote logs"| node_remote
node_coordinator -.->|"configures tiering"| node_lakeapi
node_lakeapi -->|"supports"| node_paimon
node_lakeapi -->|"supports"| node_iceberg
node_lakeapi -->|"supports"| node_lance
node_lakewriter -->|"creates tiering"| node_lakeapi
node_lakewriter -.->|"compacts data"| node_hudi
node_flink -.->|"integrates with"| node_connection
node_application -->|"processes data"| node_flink

click node_connection "https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/FlussConnection.java"
click node_admin "https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/admin/FlussAdmin.java"
click node_table "https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/table/FlussTable.java"
click node_writers "https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/table/writer/AppendWriterImpl.java"
click node_scanners "https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/table/scanner/log/LogScannerImpl.java"
click node_lookup "https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/lookup/TypedLookuperImpl.java"
click node_offsets "https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/initializer/OffsetsInitializer.java"
click node_coordinator "https://github.com/apache/fluss/blob/main/fluss-server/src/main/java/org/apache/fluss/server/coordinator/CoordinatorService.java"
click node_tablet "https://github.com/apache/fluss/blob/main/fluss-server/src/main/java/org/apache/fluss/server/tablet/TabletService.java"
click node_kv "https://github.com/apache/fluss/blob/main/fluss-server/src/main/java/org/apache/fluss/server/kv/KvManager.java"
click node_replica "https://github.com/apache/fluss/blob/main/fluss-server/src/main/java/org/apache/fluss/server/replica/ReplicaManager.java"
click node_remote "https://github.com/apache/fluss/blob/main/fluss-server/src/main/java/org/apache/fluss/server/log/remote/DefaultRemoteLogStorage.java"
click node_lakeapi "https://github.com/apache/fluss/blob/main/fluss-common/src/main/java/org/apache/fluss/lake/lakestorage/PluginLakeStorageWrapper.java"
click node_paimon "https://github.com/apache/fluss/blob/main/fluss-lake/fluss-lake-paimon/src/main/java/org/apache/fluss/lake/paimon/PaimonLakeStorage.java"
click node_iceberg "https://github.com/apache/fluss/blob/main/fluss-lake/fluss-lake-iceberg/src/main/java/org/apache/fluss/lake/iceberg/IcebergLakeStorage.java"
click node_lance "https://github.com/apache/fluss/blob/main/fluss-lake/fluss-lake-lance/src/main/java/org/apache/fluss/lake/lance/LanceLakeStorage.java"
click node_hudi "https://github.com/apache/fluss/blob/main/fluss-lake/fluss-lake-hudi/src/main/java/org/apache/fluss/lake/hudi/tiering/HudiCompactionService.java"
click node_flink "https://github.com/apache/fluss/blob/main/fluss-flink/fluss-flink-common/src/main/java/org/apache/fluss/flink/source/reader/fetcher/FlinkSourceFetcherManager.java"
click node_lakewriter "https://github.com/apache/fluss/blob/main/fluss-common/src/main/java/org/apache/fluss/lake/lakestorage/LakeStorage.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_connection,node_admin,node_table,node_writers,node_scanners,node_lookup,node_offsets toneBlue
class node_coordinator,node_tablet,node_kv,node_replica,node_remote toneAmber
class node_lakeapi,node_paimon,node_iceberg,node_lance,node_hudi,node_lakewriter toneMint
class node_flink toneRose
class node_application toneIndigo
```

## Components

### Client access

- [Client connection](https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/FlussConnection.java): `fluss-client/src/main/java/org/apache/fluss/client/FlussConnection.java`
- [Admin operations](https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/admin/FlussAdmin.java): `fluss-client/src/main/java/org/apache/fluss/client/admin/FlussAdmin.java`
- [Table API](https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/table/FlussTable.java): `fluss-client/src/main/java/org/apache/fluss/client/table/FlussTable.java`
- [Table writers](https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/table/writer/AppendWriterImpl.java): `fluss-client/src/main/java/org/apache/fluss/client/table/writer/AppendWriterImpl.java`
- [Table scanners](https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/table/scanner/log/LogScannerImpl.java): `fluss-client/src/main/java/org/apache/fluss/client/table/scanner/log/LogScannerImpl.java`
- [Point lookup](https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/lookup/TypedLookuperImpl.java): `fluss-client/src/main/java/org/apache/fluss/client/lookup/TypedLookuperImpl.java`
- [Offset initialization](https://github.com/apache/fluss/blob/main/fluss-client/src/main/java/org/apache/fluss/client/initializer/OffsetsInitializer.java): `fluss-client/src/main/java/org/apache/fluss/client/initializer/OffsetsInitializer.java`

### Fluss services

- [Coordinator](https://github.com/apache/fluss/blob/main/fluss-server/src/main/java/org/apache/fluss/server/coordinator/CoordinatorService.java): `fluss-server/src/main/java/org/apache/fluss/server/coordinator/CoordinatorService.java`
- [Tablet service](https://github.com/apache/fluss/blob/main/fluss-server/src/main/java/org/apache/fluss/server/tablet/TabletService.java): `fluss-server/src/main/java/org/apache/fluss/server/tablet/TabletService.java`
- [KV management](https://github.com/apache/fluss/blob/main/fluss-server/src/main/java/org/apache/fluss/server/kv/KvManager.java): `fluss-server/src/main/java/org/apache/fluss/server/kv/KvManager.java`
- [Replica management](https://github.com/apache/fluss/blob/main/fluss-server/src/main/java/org/apache/fluss/server/replica/ReplicaManager.java): `fluss-server/src/main/java/org/apache/fluss/server/replica/ReplicaManager.java`
- [Remote log storage](https://github.com/apache/fluss/blob/main/fluss-server/src/main/java/org/apache/fluss/server/log/remote/DefaultRemoteLogStorage.java): `fluss-server/src/main/java/org/apache/fluss/server/log/remote/DefaultRemoteLogStorage.java`

### Lakehouse storage

- [Lake storage contract](https://github.com/apache/fluss/blob/main/fluss-common/src/main/java/org/apache/fluss/lake/lakestorage/PluginLakeStorageWrapper.java): `fluss-common/src/main/java/org/apache/fluss/lake/lakestorage/PluginLakeStorageWrapper.java`
- [Paimon integration](https://github.com/apache/fluss/blob/main/fluss-lake/fluss-lake-paimon/src/main/java/org/apache/fluss/lake/paimon/PaimonLakeStorage.java): `fluss-lake/fluss-lake-paimon/src/main/java/org/apache/fluss/lake/paimon/PaimonLakeStorage.java`
- [Iceberg integration](https://github.com/apache/fluss/blob/main/fluss-lake/fluss-lake-iceberg/src/main/java/org/apache/fluss/lake/iceberg/IcebergLakeStorage.java): `fluss-lake/fluss-lake-iceberg/src/main/java/org/apache/fluss/lake/iceberg/IcebergLakeStorage.java`
- [Lance integration](https://github.com/apache/fluss/blob/main/fluss-lake/fluss-lake-lance/src/main/java/org/apache/fluss/lake/lance/LanceLakeStorage.java): `fluss-lake/fluss-lake-lance/src/main/java/org/apache/fluss/lake/lance/LanceLakeStorage.java`
- [Hudi compaction](https://github.com/apache/fluss/blob/main/fluss-lake/fluss-lake-hudi/src/main/java/org/apache/fluss/lake/hudi/tiering/HudiCompactionService.java): `fluss-lake/fluss-lake-hudi/src/main/java/org/apache/fluss/lake/hudi/tiering/HudiCompactionService.java`
- [Lake tiering](https://github.com/apache/fluss/blob/main/fluss-common/src/main/java/org/apache/fluss/lake/lakestorage/LakeStorage.java): `fluss-common/src/main/java/org/apache/fluss/lake/lakestorage/LakeStorage.java`

### Compute integrations

- [Flink integration](https://github.com/apache/fluss/blob/main/fluss-flink/fluss-flink-common/src/main/java/org/apache/fluss/flink/source/reader/fetcher/FlinkSourceFetcherManager.java): `fluss-flink/fluss-flink-common/src/main/java/org/apache/fluss/flink/source/reader/fetcher/FlinkSourceFetcherManager.java`

### Other components

- **Engine or app**

## Connections

- Engine or app → Client connection: connects
- Client connection → Table API: opens tables
- Client connection → Admin operations: administers
- Table API → Table writers: writes through
- Table API → Table scanners: scans through
- Table API → Point lookup: looks up
- Table scanners → Offset initialization: starts at
- Table writers → Tablet service: ingests records
- Table scanners → Tablet service: reads records
- Point lookup → Tablet service: queries tables
- Admin operations → Coordinator: manages metadata
- Coordinator → Tablet service: coordinates
- Tablet service → KV management: serves state
- Tablet service → Replica management: uses replicas
- Tablet service → Remote log storage: uses remote logs
- Coordinator → Lake storage contract: configures tiering
- Lake storage contract → Paimon integration: supports (evidence: `fluss-lake/fluss-lake-paimon/src/main/java/org/apache/fluss/lake/paimon/PaimonLakeStorage.java`)
- Lake storage contract → Iceberg integration: supports (evidence: `fluss-lake/fluss-lake-iceberg/src/main/java/org/apache/fluss/lake/iceberg/IcebergLakeStorage.java`)
- Lake storage contract → Lance integration: supports (evidence: `fluss-lake/fluss-lake-lance/src/main/java/org/apache/fluss/lake/lance/LanceLakeStorage.java`)
- Lake tiering → Lake storage contract: creates tiering (evidence: `fluss-common/src/main/java/org/apache/fluss/lake/lakestorage/PluginLakeStorageWrapper.java`)
- Lake tiering → Hudi compaction: compacts data
- Flink integration → Client connection: integrates with
- Engine or app → Flink integration: processes data