[PR #167] [MERGED] docs: add Mermaid diagrams for better readability

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/167 **Author:** [@LSX-s-Software](https://github.com/LSX-s-Software) **Created:** 8/13/2026 **Status:** ✅ Merged **Merged:** 8/13/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `docs/update-networking-doc` --- ### 📝 Commits (1) - [`a82b68e`](https://github.com/kvcache-ai/AgentENV/commit/a82b68e7055021ae4cfa9103f6a6541dec8da54c) docs: add mermaid charts for better readability ### 📊 Changes **6 files changed** (+139 additions, -92 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/docs.yml` (+4 -0) 📝 `docs/book.toml` (+4 -1) ➕ `docs/mermaid-init.js` (+58 -0) 📝 `docs/src/concepts/overview.md` (+15 -29) 📝 `docs/src/concepts/sandboxes.md` (+30 -7) 📝 `docs/src/internals/architecture.md` (+28 -55) </details> ### 📄 Description ## What Replace selected ASCII architecture and lifecycle diagrams in the mdBook documentation with Mermaid diagrams, and enable Mermaid rendering in the documentation build. ## Why The architecture, sandbox lifecycle, egress-rule, and multi-node control-plane diagrams are easier to read, maintain, and render consistently as Mermaid diagrams than as fixed-width ASCII art. ## Related issue N/A ## Scope and non-goals - Convert relationship diagrams in the concepts and internals documentation. - Add the mdBook Mermaid preprocessor and browser-side Mermaid initialization. - Keep source directory trees, command examples, and other non-diagram text unchanged. - No runtime, API, storage, scheduler, or generated-code behavior changes. ## Design and behavior changes - `docs/book.toml` enables the `mdbook-mermaid` preprocessor and loads `mermaid-init.js`. - Mermaid diagrams preserve the original component relationships, labels, lifecycle transitions, storage paths, and control-plane routing semantics. - The browser initializer loads Mermaid 11.12.0 from jsDelivr with an integrity hash and selects a light or dark Mermaid theme based on the mdBook theme. - The distributed control-plane diagram shows Gateway as the data-plane proxy and Scheduler as the node selection/lookup service. ## Compatibility and operations - Public API or generated protocol: N/A; documentation-only change. - Configuration or defaults: N/A. - Snapshot manifest, artifact layout, or storage format: N/A. - Upgrade and rollback: Reverting this commit restores the previous ASCII diagrams and removes Mermaid preprocessing. - Host requirements, permissions, ports, or dependencies: Documentation builds now require `mdbook-mermaid`; CI installs `mdbook-mermaid@0.17.0`. ## Validation - [ ] `make fmt` - [ ] `make clippy` - [ ] `make test-unit` - [ ] Relevant Rust integration tests - [ ] `make -C services test` (required when `services/` changes) - [ ] Generated clients/server regenerated with the documented `make` target - [x] Documentation updated - [ ] Benchmarks or performance comparison completed Commands and results: ```text mdbook build docs INFO Book building has started INFO Running the html backend INFO HTML book written to /home/ubuntu/AgentENV/docs/book git diff --check Passed ``` Skipped checks and reasons: Rust, services, generated-code, and benchmark checks were skipped because this PR only changes documentation and documentation build assets. ## Risks and reviewer notes - Mermaid rendering depends on the pinned jsDelivr asset and the `mdbook-mermaid` preprocessor. ## Checklist - [x] The PR contains one coherent change and no unrelated formatting or refactoring. - [x] New behavior is covered by tests, or I explained why testing is impractical. - [x] Logs and examples contain no credentials, tokens, or private registry information. - [x] I did not manually edit generated code without updating its source and regenerating it. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi commented

2026-10-29 14:21:12 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/167
Author: @LSX-s-Software
Created: 8/13/2026
Status: ✅ Merged
Merged: 8/13/2026
Merged by: @yingdi-shan

Base: main ← Head: docs/update-networking-doc

📝 Commits (1)

a82b68e docs: add mermaid charts for better readability

📊 Changes

6 files changed (+139 additions, -92 deletions)

View changed files

📝 .github/workflows/docs.yml (+4 -0)
📝 docs/book.toml (+4 -1)
➕ docs/mermaid-init.js (+58 -0)
📝 docs/src/concepts/overview.md (+15 -29)
📝 docs/src/concepts/sandboxes.md (+30 -7)
📝 docs/src/internals/architecture.md (+28 -55)

📄 Description

What

Replace selected ASCII architecture and lifecycle diagrams in the mdBook documentation with Mermaid diagrams, and enable Mermaid rendering in the documentation build.

Why

The architecture, sandbox lifecycle, egress-rule, and multi-node control-plane diagrams are easier to read, maintain, and render consistently as Mermaid diagrams than as fixed-width ASCII art.

N/A

Scope and non-goals

Convert relationship diagrams in the concepts and internals documentation.
Add the mdBook Mermaid preprocessor and browser-side Mermaid initialization.
Keep source directory trees, command examples, and other non-diagram text unchanged.
No runtime, API, storage, scheduler, or generated-code behavior changes.

Design and behavior changes

docs/book.toml enables the mdbook-mermaid preprocessor and loads mermaid-init.js.
Mermaid diagrams preserve the original component relationships, labels, lifecycle transitions, storage paths, and control-plane routing semantics.
The browser initializer loads Mermaid 11.12.0 from jsDelivr with an integrity hash and selects a light or dark Mermaid theme based on the mdBook theme.
The distributed control-plane diagram shows Gateway as the data-plane proxy and Scheduler as the node selection/lookup service.

Compatibility and operations

Public API or generated protocol: N/A; documentation-only change.
Configuration or defaults: N/A.
Snapshot manifest, artifact layout, or storage format: N/A.
Upgrade and rollback: Reverting this commit restores the previous ASCII diagrams and removes Mermaid preprocessing.
Host requirements, permissions, ports, or dependencies: Documentation builds now require mdbook-mermaid; CI installs mdbook-mermaid@0.17.0.

Validation

make fmt
make clippy
make test-unit
Relevant Rust integration tests
make -C services test (required when services/ changes)
Generated clients/server regenerated with the documented make target
Documentation updated
Benchmarks or performance comparison completed

Commands and results:

mdbook build docs
INFO Book building has started
INFO Running the html backend
INFO HTML book written to /home/ubuntu/AgentENV/docs/book

git diff --check
Passed

Skipped checks and reasons:

Rust, services, generated-code, and benchmark checks were skipped because this PR only changes documentation and documentation build assets.

Risks and reviewer notes

Mermaid rendering depends on the pinned jsDelivr asset and the mdbook-mermaid preprocessor.

Checklist

The PR contains one coherent change and no unrelated formatting or refactoring.
New behavior is covered by tests, or I explained why testing is impractical.
Logs and examples contain no credentials, tokens, or private registry information.
I did not manually edit generated code without updating its source and regenerating it.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

bsakaguchi

closed this issue
added the
pull-request
label

bsakaguchi referenced this issue

2026-10-29 14:21:37 +00:00

[PR #223] [MERGED] feat(overlaybd): port the crate to macOS behind a platform sys module #265

Rows
Columns

[PR #167] [MERGED] docs: add Mermaid diagrams for better readability #223