diff --git a/README.md b/README.md
index 37e6a9bcd..acd6d54ee 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,24 @@
+# Chaintable write node
+
+> Fork of [paradigmxyz/reth](https://github.com/paradigmxyz/reth), with Chaintable pipeline patches.
+
+## Architecture
+
+This repo runs the chain's execution layer with the [Chaintable pipeline](https://github.com/Chaintable/pipeline) tracer embedded. The tracer extracts block data — block headers, transactions, call traces, receipts, events, and state diffs — and ships it to **S3 + Kafka** (see pipeline's [architecture](https://github.com/Chaintable/pipeline/blob/main/docs/architecture.md)). Two consumption paths:
+
+- **Block headers + state diffs** → Kafka + S3 → [leafage-evm](https://github.com/Chaintable/leafage-evm): a lightweight EVM executor serving state queries (`eth_call`, `eth_estimateGas`, …), no P2P sync, no tx storage (see its [architecture](https://github.com/Chaintable/leafage-evm#architecture)).
+- **Block files** (transactions · call traces · receipts · events) → S3 → Chaintable's transaction/trace indexing pipeline.
+
+```
+Chaintable write node (this repo · producer, embeds pipeline tracer)
+        │
+        ├─ block headers + state diffs ──────────────────→ Kafka + S3 ─→ leafage-evm (EVM state queries)
+        │
+        └─ block files (tx · trace · receipts · events) ──→ S3 ─→ Chaintable indexing pipeline (tx/trace data)
+```
+
+---
+
 # reth
 
 [![bench status](https://github.com/paradigmxyz/reth/actions/workflows/bench.yml/badge.svg)](https://github.com/paradigmxyz/reth/actions/workflows/bench.yml)
@@ -94,8 +115,8 @@ To fully test Reth, you will need to have [Geth installed](https://geth.ethereum
 First, clone the repository:
 
 ```sh
-git clone https://github.com/paradigmxyz/reth
-cd reth
+git clone https://github.com/Chaintable/reth-x
+cd reth-x
 ```
 
 Next, run the tests: