# Cloud Storage Engine Architecture

Cloud Storage Engine (CSE) is the storage engine used by the cloud-native,
shared-storage architecture of TiDB X. It keeps TiDB's transactional
model and Raft-based replication, while moving the persistent data path toward
shared object storage and separating heavier background work from the hot OLTP
serving path.

This document is a high-level architecture entry point. It is intended to help
readers build the right mental model before diving into feature docs or code.

## Why this architecture looks different from the classic architecture

CSE inherits many ideas from its upstream lineage, but it is not just a small
variant of the original project. The main differences are
structural:

- persistent data is built around shared object storage rather than only local
  disk
- each Region/shard owns an independent LSM tree
- background work can be delegated to worker services instead of always being
  done on the hot CSE node
- the repository contains storage features and operational paths that do not
  exist in the classic local-storage architecture, such as IA tiering, remote coprocessor execution, and
  tighter worker-oriented integration

## System model

At a high level, CSE combines four main parts:

1. **TiDB and clients**
   - issue SQL and KV requests
   - rely on the transactional semantics provided by CSE

2. **`cloud_server`**
   - hosts the main server process
   - exposes gRPC and HTTP endpoints
   - wires transport, routing, Raft, storage, and worker integration together

3. **Replicated storage components**
   - `rfstore`: Raft groups, proposals, apply, peer lifecycle, split/merge,
     heartbeats, and replicated metadata changes
   - `kvengine`: per-shard LSM trees, file lifecycle, object-storage
     interaction, caches, and advanced storage features
   - `rfengine`: durable Raft-log persistence

4. **Worker services**
   - `cloud_worker` and related workers for heavier or more elastic workflows,
     such as data loading, remote coprocessor execution, schema work, backup,
     and some encryption-related tasks

## Key architectural ideas

### Shared object storage is the durable backbone

CSE is built around shared object storage as the long-lived persistent layer for
user data. Local disks are still important, but are used more for hot working
state, caches, logs, and transient local processing.

### Each Region/shard owns an independent LSM tree

Instead of one large node-wide LSM tree, CSE uses an LSM forest. Each
Region/shard has its own storage structures, which helps localize file work,
compaction effects, and some maintenance operations.

### Foreground and background work are separated

CSE tries to keep the online serving path lightweight and pushes heavier work to
background workers where possible. This improves workload isolation and helps
reduce interference between OLTP traffic and maintenance or bulk-processing
jobs.

### Raft still defines correctness

Even though storage is more cloud-oriented and file work is more distributed,
correctness still comes from Raft replication and deterministic state-machine
updates. Metadata changes, storage-class changes, and file lifecycle transitions
must still preserve replicated consistency.

## Main feature families

The same architecture supports several major feature families, including
transactional row-store, remote coprocessor offload, txn file, IA,
columnar/vector/FTS paths, CMEK, and native backup/restore.

## What to read next

This document is intentionally brief. For deeper topic-specific details, go to
these feature docs:

- [`doc/features/txn_file.md`](../features/txn_file.md)
- [`doc/features/remote_coprocessor.md`](../features/remote_coprocessor.md)
- [`doc/features/schema_manager.md`](../features/schema_manager.md)
- [`doc/features/rfengine_design.md`](../features/rfengine_design.md)
- [`doc/features/keyspace_level_cpu_throttle.md`](../features/keyspace_level_cpu_throttle.md)
- [`doc/features/blob_store.md`](../features/blob_store.md)