docs: add module-by-module design documentation and CLAUDE.md

[liunyl]

Summary

Adds docs/ — module-by-module design documentation for the open-source components, plus a CLAUDE.md for AI-assisted development. The goal is that an engineer (or an AI coding assistant) can understand a module's design, flows, and invariants before reading the headers.

• docs/README.md — index, reading order, scope/exclusions, and the maintenance rule: code changes that alter documented behavior must update the corresponding doc in the same PR.
• 01 architecture overview & core/ init · 02 threading model (TxProcessor/brpc module, shard latch, bthread-mutex deadlock class) · 03 concurrency control (CcShard/CcMap/CcEntry, NonBlockingLock, CC request catalog) · 04 transaction execution (txm state machine, commit pipeline) · 05 data model & catalog (TxKey type erasure, object/command model, CatalogFactory) · 06 distribution & clustering (Sharder, terms, remote CC, cluster scale) · 07 durability & recovery (WAL, ckpt-ts derivation, data sync pipeline, replay/orphan-lock recovery) · 08 range & bucket management (slices, 14-stage range split, bucket migration) · 09 store handler (DataStoreHandler contract, EloqDSS) · 10 open log service.
• CLAUDE.md — build/test commands, architecture primer, pointers into docs/, and the doc-maintenance rule.

All content was derived from reading the current source (file/line citations throughout); no external knowledge bases were used. Proprietary components (eloq_log_service/, tx_service/raft_host_manager/, eloqstore submodule internals) are referenced only at their RPC/interface boundaries and intentionally not documented.

Notes

• Based on main; docs-only (docs/ + CLAUDE.md), no code changes, CI-neutral.
• A few passages (threading-model invariant bug: fix fetch range entry from deleted table #2, durability §8) describe the CC-request wait pattern finalized in fix: avoid bthread mutex deadlock between tx processors and bthread waiters #491 (fix-cc-request-bthread-mutex-deadlock, the bthread_usleep-polling WaitableCc/CkptTsCc). Until fix: avoid bthread mutex deadlock between tx processors and bthread waiters #491 merges those are slightly ahead of main's code.

Verification

• Cross-doc links validated (no broken links).
• Grepped all docs to confirm no proprietary-component internals are described.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added comprehensive system documentation including architecture overview, threading model, concurrency control, transaction execution, data model and catalog, distribution and clustering, durability and recovery, range and bucket management, storage handler, and log service guides.
  • Added repository guidance document and documentation index for navigating design materials.

[coderabbitai]

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title accurately summarizes the main change: adding module-by-module design documentation and CLAUDE.md to the repository.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description clearly explains the changes (adds comprehensive docs/ tree and CLAUDE.md), lists all included documentation files with their scope, and defines the maintenance rule for future code changes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch add-module-design-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/05-data-model-and-catalog.md`:
- Around line 119-121: The wording is misleading about schema-version scope;
change the sentence that claims “at most two schema versions per node” to
clarify it applies per table/catalog entry (i.e., per CatalogEntry in
LocalCcShards::table_catalogs_), not across the whole node; mention that each
CatalogEntry can have at most two versions (current and dirty) and that a node
may host many CatalogEntry instances each with its own pair of versions, and
keep references to CatalogEntry and catalog_key_record.h so reviewers can locate
the text to update.

In `@docs/06-distribution-and-clustering.md`:
- Around line 71-80: The paragraph currently contradicts itself about bootstrap
values; update it to explicitly distinguish term caches vs leader-id cache by
stating that all term-related caches (leader_term_cache_,
candidate_leader_term_cache_, ng_leader_term_cache_, standby_node_term_cache_,
candidate_standby_node_term_cache_, standby_becoming_leader_term_cache_) are
initialized to -1, while ng_leader_cache_ is initialized to the local node id
(ng_leader_cache_[nid] == nid) so node i is assumed leader of NG i until told
otherwise, and adjust the surrounding sentence and examples to reflect those two
distinct defaults.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c8a25203-bb1a-4544-90a9-867ee30dac7e

📥 Commits

Reviewing files that changed from the base of the PR and between 1448c93 and d3ecb97.

📒 Files selected for processing (12)

• CLAUDE.md
• docs/01-architecture-overview.md
• docs/02-threading-model.md
• docs/03-concurrency-control.md
• docs/04-transaction-execution.md
• docs/05-data-model-and-catalog.md
• docs/06-distribution-and-clustering.md
• docs/07-durability-and-recovery.md
• docs/08-range-and-bucket-management.md
• docs/09-store-handler.md
• docs/10-log-service.md
• docs/README.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Clarify the schema-version scope.

Line 120 says there are “at most two schema versions per node,” but a node can host many CatalogEntrys. That limit only makes sense per table/entry, so the current wording is misleading.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/05-data-model-and-catalog.md` around lines 119 - 121, The wording is
misleading about schema-version scope; change the sentence that claims “at most
two schema versions per node” to clarify it applies per table/catalog entry
(i.e., per CatalogEntry in LocalCcShards::table_catalogs_), not across the whole
node; mention that each CatalogEntry can have at most two versions (current and
dirty) and that a node may host many CatalogEntry instances each with its own
pair of versions, and keep references to CatalogEntry and catalog_key_record.h
so reviewers can locate the text to update.