docs(fundamentals): add Architecture and Database pages by bloxster · Pull Request #21508 · erigontech/erigon

bloxster · 2026-05-29T08:08:19Z

Summary

Adds two new Fundamentals pages: Architecture (staged sync, modular processes, flat-DB on MDBX, immutable snapshots, embedded CL) and Database (MDBX engine, datadir layout, snapshot files, real mainnet sizing numbers).
Includes a Mermaid "At-a-glance" diagram on the Architecture page.
Adds matching entries to llms.txt / llms-full.txt (root + docs/site/static).

This is the release/3.4 counterpart of #21500 (same change against main). Originally bundled with #21451 / #21494 — split out into a standalone PR for clarity.

Test plan

docs-site / build check passes
Verify /fundamentals/architecture and /fundamentals/database render with the Mermaid diagram on the deployed Docusaurus preview

Closes two of the largest content gaps identified in the [Improving-public-docs](https://github.com/erigontech/erigon-documents/blob/master/public-docs/Improving-public-docs.md) spec: the high-level Architecture overview and the deep-dive Database / datadir page. New pages: - `/fundamentals/architecture` (sidebar_position 3) - At-a-glance ASCII component diagram - Staged Sync pipeline + Erigon 3 consolidation notes - Modular processes (Sentry/Downloader/Execution/RPC Daemon/TxPool/Caplin) - Storage model split (chaindata vs snapshots) - Embedded Caplin consensus layer - Flat KV state model + RPC-latency rationale - Prune-modes vs sync-modes clarification - `/fundamentals/database` (sidebar_position 15) - Datadir directory tree with role per folder - MDBX engine properties (no compaction, mmap reads, single-writer) - Immutable .seg snapshots + BitTorrent distribution - Per-transaction history granularity - Real Nov-2024 mainnet + bor-mainnet sizing numbers - Why chaindata/ stays small (and is recoverable from snapshots) - Tuning flags (--batchSize, --db.size.limit, --db.read.concurrency) - Safe-to-delete subdirectories table Cross-links: both pages link to each other plus existing pages (Modules, Caplin, Optimizing Storage, Hardware Requirements, Sync Modes). No content duplication with Optimizing Storage — that page covers multi-disk tiering recipes, these pages cover concepts. Sources: erigontech/erigon README "Datadir structure", "Erigon3 datadir size", "Erigon3 changes from Erigon2", "Modularity", "More Efficient State Storage" sections. llms.txt and llms-full.txt (both static/ and root copies) regenerated. Build: `pnpm run build` passes with onBrokenLinks/onBrokenAnchors: 'throw'. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…nnet sizing - Architecture page: ASCII component diagram → Mermaid flowchart - Database page: remove Polygon (bor-mainnet) disk-size block; we no longer maintain that chain - Add @docusaurus/theme-mermaid@^3.10.0 and enable mermaid in config - Regenerate llms-full.txt Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Port the architecture, database, and prune-modes corrections verified against main (receipt persistence, 6 domains, full-mode rolling window, Commitment folded into Execution, blocks mode, chaindata recovery via Engine API, Mermaid edges) onto release/3.4. Regenerate llms-full.txt.

Copilot

Pull request overview

Adds two new “Fundamentals” documentation pages (Architecture + Database) and wires up Mermaid rendering in the Docusaurus site, with corresponding updates to the llms* artifacts and a prune-modes refresh.

Changes:

Add /fundamentals/architecture (incl. Mermaid diagram) and /fundamentals/database pages.
Enable Mermaid support in the docs site and add the required Docusaurus theme dependency.
Update Prune Modes content (EIP-8252 window framing + Blocks node section) and regenerate llms.txt / llms-full.txt (root + docs/site/static).

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
llms.txt	Add links for the new Fundamentals pages.
llms-full.txt	Add full text for the new pages and update prune-modes excerpt.
docs/site/static/llms.txt	Mirror `llms.txt` updates for the docs site static artifact.
docs/site/static/llms-full.txt	Mirror `llms-full.txt` updates for the docs site static artifact.
docs/site/package.json	Add Mermaid theme dependency for Docusaurus.
docs/site/package-lock.json	Lockfile updates for the Mermaid theme and its dependency tree.
docs/site/docusaurus.config.ts	Enable Mermaid in markdown and register the Mermaid theme.
docs/site/docs/fundamentals/prune-modes.md	Update prune mode retention wording and add “Blocks node” section.
docs/site/docs/fundamentals/database.md	New Database page content.
docs/site/docs/fundamentals/architecture.md	New Architecture page content incl. Mermaid diagram.

Files not reviewed (1)

docs/site/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

    "@docusaurus/core": "3.10.0",
    "@docusaurus/preset-classic": "3.10.0",
+    "@docusaurus/theme-mermaid": "^3.10.0",
    "@easyops-cn/docusaurus-search-local": "^0.55.1",


bloxster · 2026-06-02T07:12:52Z

+
+A simplified pipeline:
+
+```


Leaving this fence untyped intentionally. The main twin (#21500) uses the same untyped fence here, and these two PRs need to stay byte-identical — typing it as text on `release/3.4` only would create a divergence between the branches. It also renders fine as-is. If we ever want to switch these to text it should be a separate pass applied identically to both PRs. Skipping.

bloxster · 2026-06-02T07:12:55Z

+
+## The datadir at a glance
+
+```


Leaving this directory-tree fence untyped intentionally. The main twin (#21500) keeps the same untyped fence, and the two PRs need to stay byte-identical — typing it ```text on release/3.4 only would diverge from `main`. It renders fine as-is. If we want to type these fences it should be a separate, symmetric pass across both PRs. Skipping.

bloxster · 2026-06-02T07:12:57Z

+
+A simplified pipeline:
+
+```


Skipping — this is generated output (produced from the source docs by generate-llms.py, not hand-edited), so the fence here just mirrors the source .md. Same reasoning as the source-doc thread: the main twin #21500 keeps these untyped and the two PRs must stay consistent. Editing it here only would also break --check parity with the source.

bloxster · 2026-06-02T07:12:59Z

+
+## The datadir at a glance
+
+```


Skipping — generated output (regenerated from the source docs by generate-llms.py, not hand-edited), so the fence mirrors the source .md. The main twin #21500 keeps these untyped and the two PRs must stay consistent; editing it here only would break --check parity with the source.

bloxster · 2026-06-02T07:13:01Z

+
+A simplified pipeline:
+
+```


Skipping — generated output (regenerated from the source docs by generate-llms.py, not hand-edited), so the fence mirrors the source .md. The main twin #21500 keeps these untyped and the two PRs must stay consistent; editing it here only would break --check parity with the source.

bloxster · 2026-06-02T07:13:02Z

+
+## The datadir at a glance
+
+```


Skipping — generated output (regenerated from the source docs by generate-llms.py, not hand-edited), so the fence mirrors the source .md. The main twin #21500 keeps these untyped and the two PRs must stay consistent; editing it here only would break --check parity with the source.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Matches the other Docusaurus deps and the main twin (#21500); the lockfile root deps already resolve to 3.10.0, so no lockfile change is needed. Addresses the Copilot review note on #21508. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The committed lockfile was both invalid JSON (a stray trailing `}`) and out of sync with package.json, so CI's `npm ci` failed outright. A from-scratch regen then pulled some @docusaurus/* transitive packages to 3.10.1 while the pinned ones stayed 3.10.0, which breaks Docusaurus's same-version requirement at build time. Reseeded from the main twin (#21500) lockfile — where every @docusaurus/* resolves to 3.10.0 — and reconciled to this branch's package.json with `npm install --package-lock-only`. Verified locally: `npm ci`, `npm run typecheck`, and `npm run build` all pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

yperbasis · 2026-06-02T10:56:15Z

We're going to release 3.5 soon, so I don't think we need to urgently backport PR #21500 to 3.4.

bloxster requested review from AskAlexSharov, Giulio2002 and yperbasis as code owners May 29, 2026 08:08

bloxster marked this pull request as draft May 29, 2026 10:56

Bloxster and others added 2 commits May 29, 2026 15:20

bloxster marked this pull request as ready for review May 29, 2026 13:22

bloxster force-pushed the docs/arch-db-r34-2026-05-29 branch from b4a0472 to de8e596 Compare May 29, 2026 13:22

bloxster added the docs label May 29, 2026

bloxster requested a review from Copilot June 1, 2026 19:15

Copilot started reviewing on behalf of bloxster June 1, 2026 19:15 View session

Copilot AI reviewed Jun 1, 2026

View reviewed changes

bloxster and others added 3 commits June 2, 2026 09:04

Potential fix for pull request finding

92a3fac

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

yperbasis closed this Jun 2, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(fundamentals): add Architecture and Database pages#21508

docs(fundamentals): add Architecture and Database pages#21508
bloxster wants to merge 6 commits into
release/3.4from
docs/arch-db-r34-2026-05-29

bloxster commented May 29, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

bloxster Jun 2, 2026

Uh oh!

bloxster Jun 2, 2026

Uh oh!

bloxster Jun 2, 2026

Uh oh!

bloxster Jun 2, 2026

Uh oh!

bloxster Jun 2, 2026

Uh oh!

bloxster Jun 2, 2026

Uh oh!

yperbasis commented Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

bloxster commented May 29, 2026

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

bloxster Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

bloxster Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

bloxster Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

bloxster Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

bloxster Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

bloxster Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

yperbasis commented Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants