docs(profile): add architecture-at-a-glance Mermaid diagram#35
Merged
Conversation
GitHub renders Mermaid natively in profile READMEs, so visitors landing on the org page now see the agent → SDK → Cycles → action → commit flow visually before they read the repo list. Two tweaks against the original proposal: - AGENT label trimmed to "AI agent"; supported runtimes moved to a caption line below the diagram so the node doesn't overflow on narrow viewports and so the runtime list is easier to maintain than YAML inside a Mermaid node. - Added a dashed return path from SDK to AGENT on DENY so the "synchronous authority check" claim is visually obvious. Sits right above "Start here" — visitors evaluating the org now get a mental model in the first ~3 seconds before scanning the repo links.
The first iteration put the full architecture (11 nodes, governance plane,
state store, events) on the org profile README. That's the right diagram
for someone evaluating the system, but the wrong diagram for someone who
just landed and is asking "what does this do?"
Profile README now shows the minimal 4-node enforcement loop:
agent → SDK → runtime → action, with reserve/commit return arrows.
6 arrows, 3 colors, reads in ~5 seconds on mobile.
Full diagram moves to a new ARCHITECTURE.md at the repo root. It's
discoverable from the profile diagram caption ("Want the full picture?
See ARCHITECTURE.md"), preserved as a deep-dive reference, and easier to
maintain as a standalone doc than as the README's lead visual.
Component-level deep dive (ports, Lua scripts, auth, deployment topology)
already lives at runcycles.io/quickstart/architecture-overview — linked
from ARCHITECTURE.md so visitors can follow the trail.
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 minimal architecture diagram to the org profile README, with the full deep-dive version moved to a new
ARCHITECTURE.mdat the repo root.Why split
The first iteration of this PR put the full architecture (11 nodes, governance plane, state store, events) on the landing page. That's the right diagram for someone evaluating the system, but the wrong diagram for someone who just landed and is asking "what does this do?" — too dense to parse in 5 seconds, especially on mobile.
Profile README — minimal 4-node loop
Shows just the enforcement core:
ARCHITECTURE.mdfor the deep diveARCHITECTURE.md (new file at repo root)
The full diagram preserved as a deep-dive reference:
DENY → AGENTreturn path showing the synchronous authority check<ArchDiagramFull />Vue component)Commits
73caf6c— initial detailed diagram (replaced by simpler version)6d9faa5— split into minimal profile + ARCHITECTURE.mdTest plan
ARCHITECTURE.mdfrom the GitHub repo file list to confirm the full diagram rendersARCHITECTURE.mdlink in the profile README caption to verify the relative path resolves