🎨 Palette: [UX improvement] Enhance architecture diagram and documentation UX#73
🎨 Palette: [UX improvement] Enhance architecture diagram and documentation UX#73Igor Holt (igor-holt) wants to merge 1 commit into
Conversation
- Add title and semantic node shapes to Mermaid architecture diagram - Delineate architectural layers with dashed subgraph borders - Include 'AI Workloads' and 'aSHARD VRAM Pinning' in architecture flow - Add accessible link to Genesis Conductor Engine website - Update Palette journal with learnings on Mermaid visual hierarchy Co-authored-by: igor-holt <125706350+igor-holt@users.noreply.github.com>
|
👋 Jules, reporting for duty! I'm here to lend a hand with this pull request. When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down. I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job! For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with New to Jules? Learn more at jules.google/docs. For security, I will only act on instructions from the user who triggered this task. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code review is billed via overage credits. To resume reviews, an organization admin can raise the monthly limit at claude.ai/admin-settings/claude-code.
Once credits are available, push a new commit or reopen this pull request to trigger a review.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the Mermaid architecture diagram in the README to incorporate semantic shapes, dashed subgraph borders, and a title, while documenting these visual standards in the palette journal. Additionally, a text reference was updated to a markdown link. The review feedback points out that the bidirectional arrow syntax (<-->) is invalid in Mermaid flowcharts and will cause rendering failures. It also recommends using comma-separated values for stroke-dasharray (e.g., 5,5 instead of 5 5) to prevent parsing issues across different Mermaid renderers, suggesting a corresponding update to the documentation.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| Arbiter <--> VP | ||
| VP <--> BM |
There was a problem hiding this comment.
Mermaid flowchart syntax does not support <--> for bidirectional arrows, which will cause a syntax error and prevent the diagram from rendering. To represent bidirectional relationships, use undirected links (---) or separate directed edges. Note that you should also update the existing <--> connections on lines 39 and 40 to maintain a valid and consistent diagram.
| Arbiter <--> VP | |
| VP <--> BM | |
| Arbiter --- VP | |
| VP --- BM |
| style CloudNative stroke-dasharray: 5 5 | ||
| style Orchestration stroke-dasharray: 5 5 | ||
| style Infrastructure stroke-dasharray: 5 5 |
There was a problem hiding this comment.
Using spaces in Mermaid style values (e.g., stroke-dasharray: 5 5) can cause parsing errors in some Mermaid renderers. It is safer and more compatible to use a comma instead of a space (e.g., stroke-dasharray: 5,5).
| style CloudNative stroke-dasharray: 5 5 | |
| style Orchestration stroke-dasharray: 5 5 | |
| style Infrastructure stroke-dasharray: 5 5 | |
| style CloudNative stroke-dasharray: 5,5 | |
| style Orchestration stroke-dasharray: 5,5 | |
| style Infrastructure stroke-dasharray: 5,5 |
| ## 2026-05-22 - Semantic Shapes and Visual Delineation in Mermaid | ||
| **Learning:** In technical documentation, using semantic node shapes (e.g., stadiums for workloads/clusters, hexagons for specialized logic) and dashed subgraph borders improves the readability and "glanceability" of complex architecture diagrams. Providing an explicit title within the Mermaid block also ensures context is preserved. | ||
|
|
||
| **Action:** Apply stadium shapes `([ ... ])` for high-level groupings and hexagons `{{ ... }}` for specialized components. Use `stroke-dasharray: 5 5` on subgraphs to visually separate architectural layers. |
There was a problem hiding this comment.
Update the recommended action to use stroke-dasharray: 5,5 instead of stroke-dasharray: 5 5 to avoid potential parsing issues in some Mermaid renderers and to align with the changes in the README.
1 participant
This PR enhances the documentation UX by improving the clarity and accessibility of the project's architecture diagram and contextual information.
💡 What:
🎯 Why:
For an infrastructure project like Arbiter, the README is the primary user interface. These changes improve "glanceability" and help users more quickly map the system's components across different layers of the stack.
♿ Accessibility:
📸 Architecture Diagram Update:
The diagram now explicitly shows the flow from AI Workloads through the Arbiter Core down to the VRAM pinning and physical GPU resources.
PR created automatically by Jules for task 13158886461924102789 started by Igor Holt (@igor-holt)