docs: add architecture section describing internals#1044
Merged
Conversation
Adds a new top-level Architecture section to the docs with a macro view of the system: crate/module layout, the data layer (stores, traits, backends, storage modes), the sync pipeline, the Cardano ledger model and epoch transitions, and the serving layer.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (5)
✅ Files skipped from review due to trivial changes (5)
📝 WalkthroughWalkthroughThis PR adds a new Architecture documentation section with an index page and five dedicated pages covering crates/modules, data layer, sync pipeline, ledger model, and serving layer/APIs, plus navigation metadata. ChangesArchitecture Documentation
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 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/content/architecture/data-layer.mdx`:
- Line 7: Update the opening description in the data-layer architecture page so
it reflects Dolos’s mixed storage layout instead of implying everything is in
embedded key-value stores. Reword the intro around the architecture overview to
mention both the key-value stores and the append-only flatfile segments used for
archive block bodies, while keeping the “common traits” and swappable engine
framing intact. Use the existing data-layer introduction text as the place to
adjust the wording so it stays consistent with the later storage sections.
In `@docs/content/architecture/index.mdx`:
- Around line 62-64: The consistency wording is too strong for the current
adapter behavior because `DomainAdapter` and `watch_tip` still allow a race
window. Update the `index.mdx` architecture description to avoid claiming a
perfectly consistent, always up-to-date view; instead describe that the serving
layer reads from committed state and reacts to new blocks via the tip
broadcast/subscription flow, with replay plus subscription keeping it eventually
aligned.
In `@docs/content/architecture/serving-layer.mdx`:
- Around line 13-15: Update the serving-layer architecture description to avoid
promising immediate delivery from the tip broadcast channel. In the section
describing streaming endpoints and the `Domain` adapter, qualify the
`chain-follow`/`tip-watch` behavior as eventually consistent and note the
replay/subscription gap documented by `watch_tip` in `src/adapters/mod.rs`, so
the text reflects that clients may briefly miss blocks around the subscription
window.
🪄 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: defaults
Review profile: CHILL
Plan: Pro
Run ID: da7674f0-29d8-4df6-ba8e-99e0aec65091
📒 Files selected for processing (7)
docs/content/architecture/_meta.ymldocs/content/architecture/crates.mdxdocs/content/architecture/data-layer.mdxdocs/content/architecture/index.mdxdocs/content/architecture/ledger-model.mdxdocs/content/architecture/serving-layer.mdxdocs/content/architecture/sync-pipeline.mdx
Comment on lines
+13
to
+15
| Streaming endpoints (chain-follow, tip-watch) subscribe to the tip broadcast channel that the sync pipeline publishes to, so they push new blocks to clients the moment a block is applied. | ||
|
|
||
| This design means the serving layer adds no new storage and imposes no coupling on the ledger rules — adding an API surface is a matter of writing another adapter over `Domain`. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Qualify the tip-follow guarantee.
src/adapters/mod.rs documents a replay/subscription race window in watch_tip, so this page shouldn't imply clients receive each block "the moment" it is applied. Please describe the delivery as eventually consistent and mention the replay gap.
🛠️ Suggested wording
-Streaming endpoints (chain-follow, tip-watch) subscribe to the tip broadcast channel that the sync pipeline publishes to, so they push new blocks to clients the moment a block is applied.
+Streaming endpoints (chain-follow, tip-watch) subscribe to the tip broadcast channel that the sync pipeline publishes to. Delivery is effectively live, but there is a small replay/subscription race window, so clients should treat it as eventually consistent.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Streaming endpoints (chain-follow, tip-watch) subscribe to the tip broadcast channel that the sync pipeline publishes to, so they push new blocks to clients the moment a block is applied. | |
| This design means the serving layer adds no new storage and imposes no coupling on the ledger rules — adding an API surface is a matter of writing another adapter over `Domain`. | |
| Streaming endpoints (chain-follow, tip-watch) subscribe to the tip broadcast channel that the sync pipeline publishes to. Delivery is effectively live, but there is a small replay/subscription race window, so clients should treat it as eventually consistent. | |
| This design means the serving layer adds no new storage and imposes no coupling on the ledger rules — adding an API surface is a matter of writing another adapter over `Domain`. |
🤖 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/content/architecture/serving-layer.mdx` around lines 13 - 15, Update the
serving-layer architecture description to avoid promising immediate delivery
from the tip broadcast channel. In the section describing streaming endpoints
and the `Domain` adapter, qualify the `chain-follow`/`tip-watch` behavior as
eventually consistent and note the replay/subscription gap documented by
`watch_tip` in `src/adapters/mod.rs`, so the text reflects that clients may
briefly miss blocks around the subscription window.
Addresses review feedback: describe the mixed KV + flatfile layout in the data-layer intro, qualify the cross-store commit consistency claim, and drop the instantaneous-delivery phrasing for tip streaming.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new top-level Architecture section to the docs (
docs/content/architecture/) giving a macro view of how Dolos is built — aimed at contributors, integrators, and advanced operators who want to understand the internals without reading the source.The existing docs cover what Dolos does and how to run it; this section covers how it works. It is conceptual material and cross-links to the existing APIs / Configuration / Operations sections rather than duplicating them.
Pages
dolos-coretraits vs. thedolos-cardanoimplementation; the shared domain; trust modeldolosbinary command surface, key dependenciesEpochValuesnapshot window, RUPD → EWRAP → ESTART phases, the pots system, shardingNotes
order: 8), so no existing_meta.ymlfiles change. Happy to move it right after "What is Dolos" instead if preferred.docs/content/tree.Summary by CodeRabbit