Repository navigation
Improve BeyondDB guides with diagrams and examples - #20
Merged
Merged
Conversation
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
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.
The architecture diagrams used tiny labels and tangled connections, while the server, transaction, GSI, ordered-partitioning, performance and scaling guides mixed current behavior with dense revision-specific evidence. Make the main reading paths visual and preserve the detailed contracts and historical qualification record.
Redraw three architecture SVGs and add fifteen diagrams for server boundaries/durability/lifecycle, transaction writes/read images/recovery/payload lifetimes, GSI ordered ranges/version replay/split cutover, ordered key encoding/cross-Cell Query/logical continuation after splits, and scaling capacity budgets/Cell movement versus range splitting. Reuse existing ownership, projection and split visuals where their contracts match. Add task navigation, configuration/protocol/decision tables, practical JSON and CLI examples, and current source maps. Group detailed material into nine server evidence sections, ten transaction topics, five GSI topics and five ordered-range topics. Simplify the performance reading path with the existing fixture/results SVGs, a compact results table including completion counts, configurable benchmark commands, harness selection and metric interpretation. Keep higher-concurrency transaction failures beside the results and retain the complete historical performance journal in ten expandable topics. Rework the scaling guide around current ordered routing, creation settings, growth decisions and qualification boundaries, retaining its complete journal in sixteen expandable topics.
Distinguish current concurrent prepare, combined COMMIT and acknowledged read cleanup from earlier implementations. Explain independent GSI ranges and eventual delivery while keeping online lifecycle rejected. The ordered guide separates deterministic bootstrap fences and observed-median split selection from workload-weighted templates, merges and broader split-during-page qualification; it includes a filtered-empty-page example and distinguishes logical read continuation from ambiguous mutation retry.
Keep existing architecture SVG paths and prose, correct image descriptions, and preserve original anchors in retained guides. Every substantive line of the original detailed transaction, GSI, ordered-range, performance and scaling analyses remains in its original order; server fault cases, fixture sizes and measurements remain represented. Remove
docs/implementation-status.mdand its two orphaned SVGs, repairing incoming links to retained guides, CI workflows and the protocol runner. Runtime behavior, dependency pins and configuration fields are unchanged.Validation:
python3 scripts/check-docs.pyandgit diff --checkpass. Rendered and visually inspected all eighteen new/redrawn SVGs at 2× resolution; browser text-bound checks found no label overflow. Both transaction Mermaid sequences parse and render. Rendered guide previews load images and expandable content, preserve historical anchor navigation, and show no page overflow at 390px. Ordered-reference table columns and key-row rendering were checked. The performance guide preserves all 48 original anchors and all 919 substantive detailed lines; both reused SVGs load, historical anchor navigation opens its topic, and desktop/390px mobile previews have no page overflow. The scaling guide preserves all 54 original anchors and 2,307 substantive detailed lines; both new SVGs pass text-bound checks and visual inspection, historical anchor navigation opens its topic, and desktop/mobile previews have no page overflow. JSON and shell examples pass syntax checks; the new request examples were not executed. No new performance experiments were run. Runtime tests were not rerun for these documentation-only changes. PNG previews usersvg-convertbecause the skill's raster converter omitted text and stalled on this host.