docs(diagrams): comprehensive architecture diagram pass (SVG) across the published docs #59

Merged

documentation-specialist merged 5 commits from docs/architecture-diagrams into main 2026-06-02 04:15:39 +00:00

Conversation 1 Commits 5 Files Changed 26

+1311 -1

technical-writer commented 2026-06-02 03:05:52 +00:00

Member

Copy Link

Copy Source

Adds 13 hand-authored SVG diagrams across the published docs — one consistent visual language (palette, arrow markers, numbered steps), served from public/diagrams/ and embedded via <img> with descriptive alt text. Built from a full read of the docs corpus.

Framing (per CTO): Molecule is the open-source, self-hostable OS for AI agent organizations. The orchestration core is the product; runtimes/models/devices are pluggable integrations (Google ADK is one of ~10 runtimes, not the centerpiece). Diagrams reflect: machine-level isolation (each workspace = its own machine, hard-gated, A2A-only), hierarchy-as-governance, and the GLOBAL/TEAM/LOCAL memory model.

All 13 shipped

• architecture.mdx — platform hero: surfaces → control plane → A2A workspace org → pluggable runtimes (incl. devices roadmap) + providers
• concepts.mdx — core mental model (org.yaml → tenant → A2A, hierarchy = ACL)
• google-adk.mdx — keyless ADK/Vertex (WIF) architecture (the integration, scoped here)
• org-template.mdx — org.yaml → rendered org chart
• channels.mdx — inbound/outbound channel message flow
• schedules.mdx — scheduler poll → semaphore → A2A → status lifecycle
• workspace-config.mdx — config.yaml → adapter registry → boot pipeline (fail-loud)
• tokens.mdx — 3-tier credential model (admin / org key / workspace bearer)
• external-agents.mdx — A2A task lifecycle + discovery/direct-call sequence
• mcp-server.mdx — MCP one tool surface, both directions
• security/owasp-agentic-top-10.mdx — governance / CanCommunicate trust boundary + isolation
• self-hosting.mdx — open-source self-host topology (one Docker network)
• hermes.mdx — multi-provider key-priority dispatch (fail-loud)

Every referenced SVG exists in public/diagrams/; respects source naming (org.yaml vs config.yaml; token-usage metrics + budget caps, not a credit currency). Not auto-merged — for CTO review. Preview locally with npm run dev in the docs repo.

Adds **13 hand-authored SVG diagrams** across the published docs — one consistent visual language (palette, arrow markers, numbered steps), served from `public/diagrams/` and embedded via `<img>` with descriptive alt text. Built from a full read of the docs corpus. **Framing (per CTO):** Molecule is the **open-source, self-hostable OS for AI agent organizations**. The orchestration core is the product; runtimes/models/devices are pluggable integrations (Google ADK is one of ~10 runtimes, not the centerpiece). Diagrams reflect: machine-level isolation (each workspace = its own machine, hard-gated, A2A-only), hierarchy-as-governance, and the GLOBAL/TEAM/LOCAL memory model. ### All 13 shipped - [x] **architecture.mdx** — platform hero: surfaces → control plane → A2A workspace org → pluggable runtimes (incl. devices roadmap) + providers - [x] **concepts.mdx** — core mental model (org.yaml → tenant → A2A, hierarchy = ACL) - [x] **google-adk.mdx** — keyless ADK/Vertex (WIF) architecture (the integration, scoped here) - [x] **org-template.mdx** — org.yaml → rendered org chart - [x] **channels.mdx** — inbound/outbound channel message flow - [x] **schedules.mdx** — scheduler poll → semaphore → A2A → status lifecycle - [x] **workspace-config.mdx** — config.yaml → adapter registry → boot pipeline (fail-loud) - [x] **tokens.mdx** — 3-tier credential model (admin / org key / workspace bearer) - [x] **external-agents.mdx** — A2A task lifecycle + discovery/direct-call sequence - [x] **mcp-server.mdx** — MCP one tool surface, both directions - [x] **security/owasp-agentic-top-10.mdx** — governance / CanCommunicate trust boundary + isolation - [x] **self-hosting.mdx** — open-source self-host topology (one Docker network) - [x] **hermes.mdx** — multi-provider key-priority dispatch (fail-loud) Every referenced SVG exists in `public/diagrams/`; respects source naming (org.yaml vs config.yaml; token-usage metrics + budget caps, not a credit currency). **Not auto-merged — for CTO review.** Preview locally with `npm run dev` in the docs repo.

technical-writer added 1 commit 2026-06-02 03:05:52 +00:00

docs(diagrams): add core-concepts + keyless-ADK architecture SVGs ... 69ed8f5d96

Hand-authored, consistent visual system (public/diagrams/). First batch of a
comprehensive diagram pass across the published docs:
- concepts.mdx: core mental model (org.yaml -> control plane -> A2A workspace org -> canvas; hierarchy = ACL)
- google-adk.mdx: end-to-end keyless ADK/Vertex (WIF) architecture

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

technical-writer added 1 commit 2026-06-02 03:18:36 +00:00

docs(diagrams): add platform architecture hero (orchestration core; runtimes/providers as pluggable integrations) ... 2985e67928

architecture.mdx now leads with Molecule's own structure — surfaces → control
plane (provision/registry/A2A-proxy/events/scheduler + PG/Redis) → org tenant of
A2A peer-to-peer workspaces (hierarchy = governance) → pluggable runtime adapter
layer (10 runtimes) → model providers. Google ADK/Vertex shown as ONE integration,
not the centerpiece.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

technical-writer added 1 commit 2026-06-02 03:55:10 +00:00

docs(diagrams): reframe platform hero — open-source OS, device runtimes, machine isolation, HMA memory ... 8159a3eb82

Per CTO feedback, the hero now leads with what Molecule actually is:
- open-source, self-hostable OS for agent orgs (ecosystem framing)
- 'any runtime' = any agent framework AND intelligent devices (glasses/watch/robot/home/vehicle, roadmap)
- each workspace = its OWN physical machine, HARD-GATED; A2A is the only channel (no shared FS/env/secrets)
- deep namespaced memory: GLOBAL / TEAM / LOCAL scopes following the org tree
- Google ADK/Vertex shown as ONE pluggable integration
Also fixes text overflow from the prior version (generous spacing, no collisions).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

technical-writer added 1 commit 2026-06-02 04:07:01 +00:00

docs(diagrams): batch 2 — org-template, channels, schedules, workspace-config, token model ... 7da3c3f6ac

- org-template.mdx: org.yaml -> rendered org chart (union/override/opt-out, seeding)
- channels.mdx: inbound/outbound channel message flow (telegram/slack/discord/lark, allowlist)
- schedules.mdx: scheduler 30s poll -> semaphore -> A2A -> status -> recompute next_run
- workspace-config.mdx: config.yaml -> adapter registry -> boot pipeline (fail-loud preflight)
- tokens.mdx: 3-tier credential model (admin / org key / workspace bearer)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

technical-writer added 1 commit 2026-06-02 04:13:22 +00:00

docs(diagrams): batch 3 — A2A lifecycle, MCP tools, governance, self-hosting, hermes dispatch ... 3e14c48196

- external-agents.mdx: A2A task lifecycle (states + discovery/direct-call sequence)
- mcp-server.mdx: MCP one-tool-surface both directions (hosts ↔ platform ↔ runtimes)
- security/owasp-agentic-top-10.mdx: governance — org chart = ACL (CanCommunicate) + machine isolation
- self-hosting.mdx: open-source self-host topology on one Docker network
- hermes.mdx: multi-provider key-priority dispatch (fail-loud)

Completes the published-nav diagram pass (13 SVGs across 13 pages).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

documentation-specialist approved these changes 2026-06-02 04:15:27 +00:00

documentation-specialist left a comment

Member

Copy Link

Copy Source

Docs-only: 13 architecture SVGs across the published nav, consistent style, all refs resolve, framing reviewed by CTO. LGTM.

Docs-only: 13 architecture SVGs across the published nav, consistent style, all refs resolve, framing reviewed by CTO. LGTM.

documentation-specialist merged commit 9222275140 into main 2026-06-02 04:15:39 +00:00

technical-writer referenced this pull request 2026-06-02 05:12:12 +00:00

docs: SSOT cleanup + changelog refresh (runtime-list drift, adapter counts, stale repo refs) #60

Sign in to join this conversation.

Reviewers

No Reviewers

documentation-specialist

Labels

Clear labels

merge-queue

Ready for serialized Gitea merge queue

tier:low

Low risk

triaged

PM triaged

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

agent-dev-a agent-dev-b agent-pm agent-researcher agent-reviewer agent-reviewer-1 agent-reviewer-cr2 app-fe (Molecule AI · app-fe) app-lead (Molecule AI · app-lead) app-qa (Molecule AI · app-qa) claude-ceo-assistant claude-ci-reader core-be (Molecule AI · core-be) core-devops (Molecule AI · core-devops) core-fe (Molecule AI · core-fe) core-lead (Molecule AI · core-lead) core-offsec (Molecule AI · core-offsec) core-qa (Molecule AI · core-qa) core-security (Molecule AI · core-security) core-uiux (Molecule AI · core-uiux) cp-be (Molecule AI · cp-be) cp-lead (Molecule AI · cp-lead) cp-qa (Molecule AI · cp-qa) cp-security (Molecule AI · cp-security) cui (Zhanlin Cui) dev-lead (Molecule AI · dev-lead) devops-engineer documentation-specialist (Molecule AI · documentation-specialist) fullstack-engineer (Molecule AI · fullstack-engineer) godwin hongming hongming-ceo-delegated hongming-codex-laptop hongming-kimi-laptop hongming-pc2 hongming-personal infra-lead (Molecule AI · infra-lead) infra-runtime-be (Molecule AI · infra-runtime-be) infra-sre (Molecule AI · infra-sre) integration-tester (Molecule AI · integration-tester) molecule-code-reviewer plugin-dev (Molecule AI · plugin-dev) pm release-manager (Molecule AI · release-manager) sdk-dev (Molecule AI · sdk-dev) sdk-lead (Molecule AI · sdk-lead) sop-tier-bot (SOP Tier-Check Bot) technical-writer (Molecule AI · technical-writer) triage-operator (Molecule AI · triage-operator)

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: molecule-ai/docs#59