Skip to content

Self-improving AI Employees for everyone

docs(diagrams): bring the four CONTRIBUTING diagrams up to the shipped system

trohitge758b5a45eb3
diff --git a/docs/diagrams/ai-agent-routing.svg b/docs/diagrams/ai-agent-routing.svg
index 036584a9..29af59b2 100644
--- a/docs/diagrams/ai-agent-routing.svg
+++ b/docs/diagrams/ai-agent-routing.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1165 985" width="100%" preserveAspectRatio="xMidYMid meet" font-family="ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Monaco, Consolas, monospace">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1165 1010" width="100%" preserveAspectRatio="xMidYMid meet" font-family="ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Monaco, Consolas, monospace">
<!-- Palette: OpenCompany dark-theme tokens (client/src/themes/dark.css surfaces/fg + light.css Dracula accents) -->
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
@@ -13,6 +13,7 @@
.h2 { fill: #e8eaed; font-size: 14px; font-weight: 700; }
.sub { fill: #e8eaed; font-size: 12px; }
.small { fill: #e8eaed; font-size: 10px; }
+ .dim { fill: #9aa1ac; font-size: 10px; }
.label { fill: #f1fa8c; font-size: 11px; font-style: italic; }
.conn { stroke: #e8eaed; stroke-width: 1.8; fill: none; }
.conn-dot { stroke: #9aa1ac; stroke-width: 1.5; fill: none; stroke-dasharray: 4 4; }
@@ -22,11 +23,11 @@
.title, .h1, .h2 { font-family: 'Geist Variable', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
</style>
</defs>
- <rect class="bg" width="1165" height="985"/>
+ <rect class="bg" width="1165" height="1010"/>
<!-- Title -->
<text class="title" x="582" y="42" text-anchor="middle">AI Service - Chat and Agent, both on native SDKs</text>
- <text class="sub" x="582" y="66" text-anchor="middle">server/services/ai.py + server/services/llm/</text>
+ <text class="sub" x="582" y="66" text-anchor="middle">server/services/ai.py + services/agent_runtime.py + services/llm/</text>
<!-- Entry -->
<rect class="panel p-pink" x="452" y="85" width="260" height="60" rx="8"/>
@@ -41,84 +42,94 @@
<!-- Chat panel (cyan) -->
<text class="h2 accent-cyan" x="44" y="172">Chat path - native SDKs, unified</text>
- <rect class="panel p-cyan" x="40" y="180" width="510" height="470" rx="10"/>
+ <rect class="panel p-cyan" x="40" y="180" width="510" height="490" rx="10"/>
<rect class="box p-cyan" x="60" y="200" width="470" height="58" rx="6"/>
<text class="h2" x="295" y="224" text-anchor="middle">execute_chat(...)</text>
- <text class="sub" x="295" y="244" text-anchor="middle">chat-model nodes: openaiChatModel, anthropicChatModel, ...</text>
+ <text class="sub" x="295" y="244" text-anchor="middle">12 chat-model nodes: openaiChatModel, anthropicChatModel, ...</text>
<path class="conn" d="M 295 258 L 295 306" marker-end="url(#arrow)"/>
<text class="label" x="305" y="286">delegates (every provider)</text>
- <rect class="box p-cyan" x="60" y="306" width="470" height="76" rx="6"/>
+ <rect class="box p-cyan" x="60" y="306" width="470" height="94" rx="6"/>
<text class="h2" x="295" y="330" text-anchor="middle">ChatUnifier.chat(provider=...)</text>
<text class="sub" x="295" y="350" text-anchor="middle">single facade - no per-provider branch</text>
- <text class="sub" x="295" y="368" text-anchor="middle">typed SDK errors -&gt; NodeUserError</text>
+ <text class="sub" x="295" y="368" text-anchor="middle">resolves base_url / local proxy, filters incompatible models</text>
+ <text class="sub" x="295" y="386" text-anchor="middle">typed LLMError -&gt; NodeUserError (one WARN line, no trace)</text>
- <path class="conn" d="M 295 382 L 295 430" marker-end="url(#arrow)"/>
- <text class="label" x="305" y="410">lookup</text>
+ <path class="conn" d="M 295 400 L 295 448" marker-end="url(#arrow)"/>
+ <text class="label" x="305" y="428">lookup</text>
- <rect class="box p-cyan" x="60" y="430" width="470" height="58" rx="6"/>
- <text class="h2" x="295" y="454" text-anchor="middle">ProviderRegistry</text>
- <text class="sub" x="295" y="474" text-anchor="middle">get_provider(name) -&gt; ProviderSpec.factory(...)</text>
+ <rect class="box p-cyan" x="60" y="448" width="470" height="76" rx="6"/>
+ <text class="h2" x="295" y="472" text-anchor="middle">ProviderRegistry</text>
+ <text class="sub" x="295" y="492" text-anchor="middle">get_provider(name) -&gt; ProviderSpec.factory(...)</text>
+ <text class="small" x="295" y="510" text-anchor="middle">SDK exception classes resolved lazily - no SDK import at registration</text>
- <path class="conn" d="M 295 488 L 295 536" marker-end="url(#arrow)"/>
- <text class="label" x="305" y="516">spec.factory()</text>
+ <path class="conn" d="M 295 524 L 295 556" marker-end="url(#arrow)"/>
+ <text class="label" x="305" y="544">spec.factory()</text>
- <rect class="box p-cyan" x="60" y="536" width="470" height="94" rx="6"/>
- <text class="h2" x="295" y="560" text-anchor="middle">Native provider clients (12)</text>
- <text class="sub" x="295" y="580" text-anchor="middle">Anthropic &#183; OpenAI &#183; Gemini &#183; OpenRouter</text>
- <text class="sub" x="295" y="598" text-anchor="middle">OpenAI-compat via base_url: xAI, DeepSeek, Kimi,</text>
- <text class="sub" x="295" y="616" text-anchor="middle">Mistral, Groq, Cerebras, Ollama, LM Studio</text>
+ <rect class="box p-cyan" x="60" y="556" width="470" height="100" rx="6"/>
+ <text class="h2" x="295" y="580" text-anchor="middle">Native providers (13)</text>
+ <text class="sub" x="295" y="600" text-anchor="middle">own SDK: Anthropic &#183; OpenAI &#183; Gemini &#183; OpenRouter</text>
+ <text class="sub" x="295" y="618" text-anchor="middle">OpenAI-compatible via base_url: xAI, DeepSeek, Kimi, Mistral,</text>
+ <text class="sub" x="295" y="636" text-anchor="middle">Groq, Cerebras, Sarvam &#183; local: Ollama, LM Studio</text>
+ <text class="small" x="295" y="652" text-anchor="middle">config-driven (llm_defaults.json): base_url, context, thinking, model listing</text>
<!-- Agent panel (purple) -->
<text class="h2 accent-purple" x="589" y="172">Agent path - native tool loop</text>
- <rect class="panel p-purple" x="585" y="180" width="540" height="382" rx="10"/>
+ <rect class="panel p-purple" x="585" y="180" width="540" height="490" rx="10"/>
<rect class="box p-purple" x="605" y="200" width="500" height="76" rx="6"/>
<text class="h2" x="855" y="224" text-anchor="middle">execute_agent / execute_chat_agent</text>
- <text class="sub" x="855" y="244" text-anchor="middle">aiAgent, chatAgent + specialized agents + team leads</text>
- <text class="sub" x="855" y="262" text-anchor="middle">(CLI agents rlm / claude_code / codex bypass this loop)</text>
+ <text class="sub" x="855" y="244" text-anchor="middle">aiAgent, chatAgent, specialized agents, team leads</text>
+ <text class="small" x="855" y="262" text-anchor="middle">claude_code / codex / rlm / vertex run through the CLI context bridge instead</text>
- <path class="conn" d="M 855 276 L 855 324" marker-end="url(#arrow)"/>
- <text class="label" x="865" y="304">builds model</text>
+ <path class="conn" d="M 855 276 L 855 312" marker-end="url(#arrow)"/>
+ <text class="label" x="865" y="298">prepare</text>
- <rect class="box p-purple" x="605" y="324" width="500" height="76" rx="6"/>
- <text class="h2" x="855" y="348" text-anchor="middle">ChatUnifier -&gt; native provider SDK</text>
- <text class="sub" x="855" y="368" text-anchor="middle">AnthropicProvider / OpenAIProvider / GeminiProvider / ...</text>
- <text class="sub" x="855" y="386" text-anchor="middle">provider-neutral ToolDef schemas</text>
+ <rect class="box p-purple" x="605" y="312" width="500" height="94" rx="6"/>
+ <text class="h2" x="855" y="336" text-anchor="middle">Conversation + tools from the canvas</text>
+ <text class="sub" x="855" y="356" text-anchor="middle">Context node: stored conversation loaded per firing (RFC-0002)</text>
+ <text class="sub" x="855" y="374" text-anchor="middle">edges -&gt; skills, tools, teammates -&gt; provider-neutral ToolDef</text>
+ <text class="small" x="855" y="392" text-anchor="middle">skills load on demand through the Skill tool; Memory is a tool, not history</text>
- <path class="conn" d="M 855 400 L 855 448" marker-end="url(#arrow)"/>
- <text class="label" x="865" y="428">bind_tools</text>
+ <path class="conn" d="M 855 406 L 855 442" marker-end="url(#arrow)"/>
+ <text class="label" x="865" y="428">ChatUnifier per turn</text>
- <rect class="box p-purple" x="605" y="448" width="500" height="112" rx="6"/>
- <text class="h2" x="855" y="472" text-anchor="middle">run_native_agent_loop (plain async)</text>
- <text class="sub" x="855" y="492" text-anchor="middle">loop: chat -&gt; tool_calls? dispatch -&gt; tool message</text>
- <text class="sub" x="855" y="510" text-anchor="middle">max-iterations guard &#183; delegate_to_&lt;type&gt; auto-injected</text>
- <text class="sub" x="855" y="528" text-anchor="middle">hot-rebind of tools after canvas mutations</text>
- <text class="sub" x="855" y="546" text-anchor="middle">llm_media image refs -&gt; hydrated per call (vision-gated)</text>
+ <rect class="box p-purple" x="605" y="442" width="500" height="132" rx="6"/>
+ <text class="h2" x="855" y="466" text-anchor="middle">run_native_agent_loop (plain async)</text>
+ <text class="sub" x="855" y="486" text-anchor="middle">loop: chat -&gt; tool_calls? dispatch -&gt; tool results -&gt; chat</text>
+ <text class="sub" x="855" y="504" text-anchor="middle">max_iterations cap (AGENT_RECURSION_LIMIT, default 200)</text>
+ <text class="sub" x="855" y="522" text-anchor="middle">team leads delegate through Task Manager (durable child runs)</text>
+ <text class="sub" x="855" y="540" text-anchor="middle">tools rebound after Agent Builder edits the canvas mid-task</text>
+ <text class="sub" x="855" y="558" text-anchor="middle">image refs hydrated per call (vision-gated) &#183; saved every turn</text>
+
+ <text class="dim" x="855" y="600" text-anchor="middle">Deployed runs: the same loop as Temporal AgentWorkflow activities</text>
+ <text class="dim" x="855" y="616" text-anchor="middle">(agent.execute_llm_step retried with backoff, tool calls as per-type activities);</text>
+ <text class="dim" x="855" y="632" text-anchor="middle">threshold compaction keeps the system prompt verbatim and summarises into a user turn</text>
<!-- Convergence arrows -->
- <path class="conn" d="M 295 630 V 662 H 462 V 706" marker-end="url(#arrow)"/>
- <text class="label" x="307" y="680">LLMResponse</text>
- <path class="conn" d="M 855 542 V 662 H 702 V 706" marker-end="url(#arrow)"/>
- <text class="label" x="867" y="575">final message</text>
+ <path class="conn" d="M 295 656 V 682 H 462 V 726" marker-end="url(#arrow)"/>
+ <text class="label" x="307" y="700">LLMResponse</text>
+ <path class="conn" d="M 855 640 V 682 H 702 V 726" marker-end="url(#arrow)"/>
+ <text class="label" x="867" y="664">final message</text>
<!-- Shared panel (green) -->
- <text class="h2 accent-green" x="582" y="682" text-anchor="middle">Shared convergence</text>
- <rect class="panel p-green" x="282" y="690" width="600" height="254" rx="10"/>
-
- <rect class="box p-green" x="302" y="706" width="560" height="76" rx="6"/>
- <text class="h2" x="582" y="730" text-anchor="middle">Normalized response</text>
- <text class="sub" x="582" y="750" text-anchor="middle">content &#183; thinking &#183; tool_calls &#183; usage &#183; model &#183; finish_reason</text>
- <text class="sub" x="582" y="768" text-anchor="middle">services/llm/protocol.py (agent path: same fields in a result dict)</text>
-
- <path class="conn" d="M 582 782 L 582 830" marker-end="url(#arrow)"/>
- <text class="label" x="594" y="810">token/cost tracking after each turn</text>
-
- <rect class="box p-green" x="302" y="830" width="560" height="94" rx="6"/>
- <text class="h2" x="582" y="854" text-anchor="middle">Shared infrastructure</text>
- <text class="sub" x="582" y="874" text-anchor="middle">compaction.py: post-turn token tracking + model-aware compaction</text>
- <text class="sub" x="582" y="892" text-anchor="middle">pricing.py: USD cost from config/pricing.json</text>
- <text class="sub" x="582" y="910" text-anchor="middle">model_registry.py: context-length lookup</text>
+ <text class="h2 accent-green" x="582" y="702" text-anchor="middle">Shared convergence</text>
+ <rect class="panel p-green" x="282" y="710" width="600" height="268" rx="10"/>
+
+ <rect class="box p-green" x="302" y="726" width="560" height="76" rx="6"/>
+ <text class="h2" x="582" y="750" text-anchor="middle">Normalized response</text>
+ <text class="sub" x="582" y="770" text-anchor="middle">content &#183; thinking &#183; tool_calls &#183; usage &#183; model &#183; finish_reason</text>
+ <text class="sub" x="582" y="788" text-anchor="middle">services/llm/protocol.py - one MessageWire standard on both paths</text>
+
+ <path class="conn" d="M 582 802 L 582 850" marker-end="url(#arrow)"/>
+ <text class="label" x="594" y="830">token/cost tracking after each turn</text>
+
+ <rect class="box p-green" x="302" y="850" width="560" height="112" rx="6"/>
+ <text class="h2" x="582" y="874" text-anchor="middle">Shared infrastructure</text>
+ <text class="sub" x="582" y="894" text-anchor="middle">compaction.py: usage aggregation + summary compaction at</text>
+ <text class="sub" x="582" y="912" text-anchor="middle">COMPACTION_RATIO (default 0.8) x model context length</text>
+ <text class="sub" x="582" y="930" text-anchor="middle">pricing.py: USD cost from config/pricing.json</text>
+ <text class="sub" x="582" y="948" text-anchor="middle">model_registry.py: context length, max output, reasoning flags</text>
</svg>
diff --git a/docs/diagrams/execution-flow.svg b/docs/diagrams/execution-flow.svg
index 614c7108..a1fe4c78 100644
--- a/docs/diagrams/execution-flow.svg
+++ b/docs/diagrams/execution-flow.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1460 1300" width="100%" preserveAspectRatio="xMidYMid meet" font-family="ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Monaco, Consolas, monospace">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1460 1330" width="100%" preserveAspectRatio="xMidYMid meet" font-family="ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Monaco, Consolas, monospace">
<!-- Palette: OpenCompany dark-theme tokens (client/src/themes/dark.css surfaces/fg + light.css Dracula accents) -->
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
@@ -13,6 +13,7 @@
.h2 { fill: #e8eaed; font-size: 14px; font-weight: 700; }
.sub { fill: #e8eaed; font-size: 12px; }
.small { fill: #e8eaed; font-size: 10px; }
+ .dim { fill: #9aa1ac; font-size: 10px; }
.label { fill: #f1fa8c; font-size: 11px; font-style: italic; }
.conn { stroke: #e8eaed; stroke-width: 1.8; fill: none; }
.conn-dot { stroke: #9aa1ac; stroke-width: 1.5; fill: none; stroke-dasharray: 4 4; }
@@ -22,11 +23,11 @@
.title, .h1, .h2 { font-family: 'Geist Variable', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
</style>
</defs>
- <rect class="bg" width="1460" height="1300"/>
+ <rect class="bg" width="1460" height="1330"/>
<!-- Title -->
<text x="40" y="45" class="title">How Workflows Execute</text>
- <text x="40" y="68" class="sub">Two entry points -&gt; WorkflowService routing -&gt; shared node dispatch</text>
+ <text x="40" y="68" class="sub">Two entry points -&gt; WorkflowService routing -&gt; one node dispatch path</text>
<!-- Lane labels -->
<text x="250" y="92" class="tier-label" text-anchor="middle">CANVAS RUN PATH</text>
@@ -36,112 +37,121 @@
<rect class="panel p-cyan" x="40" y="100" width="420" height="96" rx="8"/>
<text x="250" y="130" class="h1" text-anchor="middle">Per-node "Run"</text>
<text x="250" y="156" class="sub" text-anchor="middle">execute_node WS msg -&gt; WorkflowService.execute_node</text>
- <text x="250" y="178" class="sub" text-anchor="middle">runs ONE node &#183; no mode routing</text>
+ <text x="250" y="178" class="sub" text-anchor="middle">runs ONE node in-process &#183; no mode routing</text>
<!-- Entry box 2: Toolbar Start (purple) -->
<rect class="panel p-purple" x="780" y="100" width="420" height="96" rx="8"/>
<text x="990" y="130" class="h1" text-anchor="middle">Toolbar "Start"</text>
<text x="990" y="156" class="sub" text-anchor="middle">deploy_workflow WS msg -&gt; DeploymentManager.deploy</text>
- <text x="990" y="178" class="sub" text-anchor="middle">(button label is Start, toggles to Stop)</text>
+ <text x="990" y="178" class="sub" text-anchor="middle">graph snapshot persisted &#183; button toggles to Stop</text>
<!-- Canvas lane: straight down to convergence -->
- <path class="conn" d="M 250 196 L 250 1038" marker-end="url(#arrow)"/>
+ <path class="conn" d="M 250 196 L 250 1068" marker-end="url(#arrow)"/>
<text x="262" y="250" class="label">direct dispatch</text>
- <text x="270" y="500" class="small" style="fill:#9aa1ac">canvas trigger waits use in-memory</text>
- <text x="270" y="518" class="small" style="fill:#9aa1ac">event_waiter (asyncio.Future)</text>
+ <text x="270" y="480" class="dim">trigger nodes run on the canvas wait</text>
+ <text x="270" y="498" class="dim">on the in-memory event_waiter</text>
+ <text x="270" y="516" class="dim">(asyncio.Future, cancel from the panel)</text>
+ <text x="270" y="556" class="dim">manual runs persist no conversation</text>
+ <text x="270" y="574" class="dim">(only Start admits a generation)</text>
<!-- Deployed lane -->
<path class="conn" d="M 990 196 L 990 238" marker-end="url(#arrow)"/>
- <rect class="panel p-purple" x="775" y="240" width="430" height="90" rx="8"/>
- <text x="990" y="266" class="h2" text-anchor="middle">Durable trigger listeners</text>
- <text x="990" y="288" class="small" text-anchor="middle">TriggerListenerWorkflow (push) &#183; PollingTriggerWorkflow (poll)</text>
- <text x="990" y="308" class="small" text-anchor="middle">Temporal Schedule (cron, 24h catch-up)</text>
+ <rect class="panel p-purple" x="775" y="240" width="430" height="108" rx="8"/>
+ <text x="990" y="266" class="h2" text-anchor="middle">WorkflowControlWorkflow (per generation)</text>
+ <text x="990" y="288" class="small" text-anchor="middle">owns Start / Pause / Resume / Reset &#183; re-armed from the snapshot on boot</text>
+ <text x="990" y="306" class="small" text-anchor="middle">arms one durable listener per trigger node:</text>
+ <text x="990" y="324" class="small" text-anchor="middle">TriggerListenerWorkflow (push) &#183; PollingTriggerWorkflow (poll)</text>
+ <text x="990" y="340" class="small" text-anchor="middle">Temporal Schedule (cron, 24 h catch-up window)</text>
- <path class="conn" d="M 990 330 L 990 370" marker-end="url(#arrow)"/>
- <text x="1002" y="356" class="label">on event</text>
+ <path class="conn" d="M 990 348 L 990 388" marker-end="url(#arrow)"/>
+ <text x="1002" y="374" class="label">on event</text>
- <rect class="panel p-purple" x="775" y="372" width="430" height="90" rx="8"/>
- <text x="990" y="398" class="h2" text-anchor="middle">dispatch.emit(event)</text>
- <text x="990" y="420" class="small" text-anchor="middle">Temporal Visibility query: EventType=... AND Running</text>
- <text x="990" y="440" class="small" text-anchor="middle">-&gt; Signal each matching listener</text>
+ <rect class="panel p-purple" x="775" y="390" width="430" height="90" rx="8"/>
+ <text x="990" y="416" class="h2" text-anchor="middle">dispatch.emit(CloudEvents envelope)</text>
+ <text x="990" y="438" class="small" text-anchor="middle">Temporal Visibility query: EventType (and EventWorkflowId) AND Running</text>
+ <text x="990" y="458" class="small" text-anchor="middle">-&gt; Signal each matching listener &#183; also broadcast to the UI</text>
- <path class="conn" d="M 990 462 L 990 502" marker-end="url(#arrow)"/>
- <text x="1002" y="488" class="label">Signal</text>
+ <path class="conn" d="M 990 480 L 990 520" marker-end="url(#arrow)"/>
+ <text x="1002" y="506" class="label">Signal</text>
- <rect class="panel p-purple" x="775" y="504" width="430" height="72" rx="8"/>
- <text x="990" y="530" class="h2" text-anchor="middle">Per-firing child run</text>
- <text x="990" y="552" class="small" text-anchor="middle">child MachinaWorkflow per event &#183; trigger node _pre_executed</text>
+ <rect class="panel p-purple" x="775" y="522" width="430" height="72" rx="8"/>
+ <text x="990" y="548" class="h2" text-anchor="middle">Per-firing child run</text>
+ <text x="990" y="570" class="small" text-anchor="middle">one child MachinaWorkflow per event - firing trigger pre-executed</text>
<!-- Deployed lane into router -->
- <path class="conn" d="M 990 576 L 990 608 L 620 608 L 620 636" marker-end="url(#arrow)"/>
+ <path class="conn" d="M 990 594 L 990 626 L 620 626 L 620 654" marker-end="url(#arrow)"/>
<!-- Router diamond 1 -->
- <polygon class="box p-orange" points="620,638 795,700 620,762 445,700"/>
- <text x="620" y="696" class="h2" text-anchor="middle">TEMPORAL_ENABLED</text>
- <text x="620" y="716" class="h2" text-anchor="middle">and worker wired?</text>
+ <polygon class="box p-orange" points="620,656 795,718 620,780 445,718"/>
+ <text x="620" y="714" class="h2" text-anchor="middle">TEMPORAL_ENABLED</text>
+ <text x="620" y="734" class="h2" text-anchor="middle">and worker wired?</text>
<!-- D1 no -> D2 -->
- <path class="conn" d="M 795 700 L 856 700" marker-end="url(#arrow)"/>
- <text x="812" y="692" class="label">no</text>
+ <path class="conn" d="M 795 718 L 856 718" marker-end="url(#arrow)"/>
+ <text x="812" y="710" class="label">no</text>
<!-- D1 yes -> Temporal box -->
- <path class="conn" d="M 620 762 L 620 788 L 520 788 L 520 828" marker-end="url(#arrow)"/>
- <text x="630" y="782" class="label">yes</text>
+ <path class="conn" d="M 620 780 L 620 806 L 520 806 L 520 846" marker-end="url(#arrow)"/>
+ <text x="630" y="800" class="label">yes (default)</text>
<!-- Router diamond 2 -->
- <polygon class="box p-orange" points="990,645 1120,700 990,755 860,700"/>
- <text x="990" y="696" class="h2" text-anchor="middle">Redis</text>
- <text x="990" y="716" class="h2" text-anchor="middle">available?</text>
+ <polygon class="box p-orange" points="990,663 1120,718 990,773 860,718"/>
+ <text x="990" y="714" class="h2" text-anchor="middle">REDIS_ENABLED?</text>
+ <text x="990" y="734" class="small" text-anchor="middle">(default off)</text>
<!-- D2 yes -> Parallel box -->
- <path class="conn" d="M 990 755 L 990 788 L 935 788 L 935 828" marker-end="url(#arrow)"/>
- <text x="1000" y="780" class="label">yes</text>
+ <path class="conn" d="M 990 773 L 990 806 L 935 806 L 935 846" marker-end="url(#arrow)"/>
+ <text x="1000" y="798" class="label">yes</text>
<!-- D2 no -> Sequential box -->
- <path class="conn" d="M 1120 700 L 1290 700 L 1290 828" marker-end="url(#arrow)"/>
- <text x="1140" y="692" class="label">no</text>
+ <path class="conn" d="M 1120 718 L 1290 718 L 1290 846" marker-end="url(#arrow)"/>
+ <text x="1140" y="710" class="label">no</text>
<!-- Mode box: Temporal Distributed -->
- <rect class="panel p-orange" x="330" y="830" width="380" height="152" rx="8"/>
- <text x="520" y="856" class="h2" text-anchor="middle">Temporal Distributed</text>
- <text x="520" y="880" class="sub" text-anchor="middle">MachinaWorkflow orchestrator (FIRST_COMPLETED)</text>
- <text x="520" y="900" class="sub" text-anchor="middle">per-type activities node.{type}.v{ver}</text>
- <text x="520" y="920" class="sub" text-anchor="middle">3 retries &#183; 10 min timeout &#183; heartbeats</text>
- <text x="520" y="940" class="sub" text-anchor="middle">per-queue TemporalWorkerPool (default on)</text>
- <text x="520" y="964" class="small" style="fill:#9aa1ac" text-anchor="middle">services/temporal/</text>
+ <rect class="panel p-orange" x="330" y="848" width="380" height="172" rx="8"/>
+ <text x="520" y="874" class="h2" text-anchor="middle">Temporal Distributed</text>
+ <text x="520" y="898" class="sub" text-anchor="middle">MachinaWorkflow orchestrator (FIRST_COMPLETED)</text>
+ <text x="520" y="918" class="sub" text-anchor="middle">node.{type}.v{ver} activities on 9 task queues</text>
+ <text x="520" y="938" class="sub" text-anchor="middle">RetryPolicy: 3 attempts default &#183; 2 min heartbeat</text>
+ <text x="520" y="958" class="sub" text-anchor="middle">24 h start-to-close &#183; conditional edges honoured</text>
+ <text x="520" y="978" class="sub" text-anchor="middle">agents = AgentWorkflow children (LLM step backoff)</text>
+ <text x="520" y="1002" class="dim" text-anchor="middle">services/temporal/</text>
<!-- Mode box: Parallel Local (Redis) -->
- <rect class="panel p-orange" x="760" y="830" width="350" height="132" rx="8"/>
- <text x="935" y="856" class="h2" text-anchor="middle">Parallel Local (Redis)</text>
- <text x="935" y="880" class="sub" text-anchor="middle">decide loop + Kahn layers</text>
- <text x="935" y="900" class="sub" text-anchor="middle">asyncio.gather() fork/join</text>
- <text x="935" y="920" class="sub" text-anchor="middle">input-hash cache &#183; DLQ + heartbeat recovery</text>
- <text x="935" y="944" class="small" style="fill:#9aa1ac" text-anchor="middle">services/execution/</text>
+ <rect class="panel p-orange" x="760" y="848" width="350" height="152" rx="8"/>
+ <text x="935" y="874" class="h2" text-anchor="middle">Parallel Local (opt-in)</text>
+ <text x="935" y="898" class="sub" text-anchor="middle">decide loop + asyncio.wait(FIRST_COMPLETED)</text>
+ <text x="935" y="918" class="sub" text-anchor="middle">dependents start as soon as their input lands</text>
+ <text x="935" y="938" class="sub" text-anchor="middle">input-hash cache &#183; DLQ + RecoverySweeper</text>
+ <text x="935" y="958" class="sub" text-anchor="middle">Redis SETNX locks</text>
+ <text x="935" y="982" class="dim" text-anchor="middle">services/execution/</text>
<!-- Mode box: Sequential Fallback -->
- <rect class="panel p-orange" x="1160" y="830" width="260" height="112" rx="8"/>
- <text x="1290" y="856" class="h2" text-anchor="middle">Sequential Fallback</text>
- <text x="1290" y="880" class="sub" text-anchor="middle">topological walk</text>
- <text x="1290" y="900" class="sub" text-anchor="middle">no cache, no retry, no DLQ</text>
- <text x="1290" y="924" class="small" style="fill:#9aa1ac" text-anchor="middle">_execute_sequential()</text>
+ <rect class="panel p-orange" x="1160" y="848" width="260" height="112" rx="8"/>
+ <text x="1290" y="874" class="h2" text-anchor="middle">Sequential Fallback</text>
+ <text x="1290" y="898" class="sub" text-anchor="middle">topological walk</text>
+ <text x="1290" y="918" class="sub" text-anchor="middle">no cache, no retry, no DLQ</text>
+ <text x="1290" y="942" class="dim" text-anchor="middle">_execute_sequential()</text>
<!-- Mode boxes -> convergence -->
- <path class="conn" d="M 520 982 L 520 1038" marker-end="url(#arrow)"/>
- <path class="conn" d="M 935 962 L 935 1038" marker-end="url(#arrow)"/>
- <path class="conn" d="M 1290 942 L 1290 1087 L 1004 1087" marker-end="url(#arrow)"/>
+ <path class="conn" d="M 520 1020 L 520 1068" marker-end="url(#arrow)"/>
+ <path class="conn" d="M 935 1000 L 935 1068" marker-end="url(#arrow)"/>
+ <path class="conn" d="M 1290 960 L 1290 1117 L 1004 1117" marker-end="url(#arrow)"/>
<!-- Convergence box -->
- <rect class="panel p-green" x="220" y="1040" width="780" height="94" rx="8"/>
- <text x="610" y="1070" class="h1" text-anchor="middle">NodeExecutor.execute()</text>
- <text x="610" y="1094" class="sub" text-anchor="middle">plugin registry dispatch &#183; class-based plugins in server/nodes/&lt;group&gt;/</text>
- <text x="610" y="1114" class="sub" text-anchor="middle">-&gt; result dict</text>
+ <rect class="panel p-green" x="220" y="1070" width="780" height="112" rx="8"/>
+ <text x="610" y="1100" class="h1" text-anchor="middle">NodeExecutor.execute() -&gt; BaseNode.execute()</text>
+ <text x="610" y="1124" class="sub" text-anchor="middle">plugin registry dispatch &#183; Params validated &#183; log_context + OTel span per node</text>
+ <text x="610" y="1144" class="sub" text-anchor="middle">Output checked at the serialization boundary &#183; NodeUserError -&gt; one WARN line + error envelope</text>
+ <text x="610" y="1164" class="sub" text-anchor="middle">-&gt; result dict</text>
<!-- Convergence -> output -->
- <path class="conn" d="M 610 1134 L 610 1166" marker-end="url(#arrow)"/>
+ <path class="conn" d="M 610 1182 L 610 1214" marker-end="url(#arrow)"/>
<!-- Output box -->
- <rect class="panel p-green" x="320" y="1170" width="580" height="78" rx="8"/>
- <text x="610" y="1198" class="h1" text-anchor="middle">StatusBroadcaster</text>
- <text x="610" y="1222" class="sub" text-anchor="middle">node_status + node_output (CloudEvents envelope) -&gt; frontend WebSocket</text>
+ <rect class="panel p-green" x="290" y="1216" width="640" height="82" rx="8"/>
+ <text x="610" y="1244" class="h1" text-anchor="middle">StatusBroadcaster</text>
+ <text x="610" y="1266" class="sub" text-anchor="middle">node_status + node_output, plus typed CloudEvents (agent_progress, workflow_lifecycle, ...)</text>
+ <text x="610" y="1286" class="sub" text-anchor="middle">-&gt; frontend WebSocket /ws/status</text>
</svg>
diff --git a/docs/diagrams/node-anatomy.svg b/docs/diagrams/node-anatomy.svg
index f9fd319e..4b0a692a 100644
--- a/docs/diagrams/node-anatomy.svg
+++ b/docs/diagrams/node-anatomy.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1760 800" width="100%" preserveAspectRatio="xMidYMid meet" font-family="ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Monaco, Consolas, monospace">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1760 820" width="100%" preserveAspectRatio="xMidYMid meet" font-family="ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Monaco, Consolas, monospace">
<!-- Palette: OpenCompany dark-theme tokens (client/src/themes/dark.css surfaces/fg + light.css Dracula accents) -->
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
@@ -22,11 +22,11 @@
.title, .h1, .h2 { font-family: 'Geist Variable', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
</style>
</defs>
- <rect class="bg" width="1760" height="800"/>
+ <rect class="bg" width="1760" height="820"/>
<!-- Title -->
<text x="880" y="42" class="title" text-anchor="middle">Anatomy of a Plugin Node</text>
- <text x="880" y="68" class="sub" text-anchor="middle">One Python folder = one node. Backend is the single source of truth - the frontend renders itself with zero TypeScript edits.</text>
+ <text x="880" y="68" class="sub" text-anchor="middle">One Python folder = one node. Backend is the single source of truth - the frontend renders itself with zero TypeScript edits. 148 nodes ship this way.</text>
<!-- ================= GROUP 1 (cyan): What you write ================= -->
<rect class="panel p-cyan" x="40" y="100" width="460" height="545" rx="10"/>
@@ -36,27 +36,27 @@
<rect class="box p-cyan" x="60" y="168" width="420" height="78" rx="6"/>
<text x="270" y="190" class="h2" text-anchor="middle">__init__.py - the node class</text>
<text x="270" y="210" class="sub" text-anchor="middle">class MyNode(ActionNode / TriggerNode / ToolNode)</text>
- <text x="270" y="228" class="small" text-anchor="middle">type, display_name, group, handles, credentials, task_queue</text>
+ <text x="270" y="228" class="small" text-anchor="middle">type, display_name, group, credentials, task_queue, ui_hints</text>
<rect class="box p-cyan" x="60" y="264" width="420" height="78" rx="6"/>
<text x="270" y="286" class="h2" text-anchor="middle">Params / Output (Pydantic)</text>
<text x="270" y="306" class="sub" text-anchor="middle">snake_case fields = UI params = LLM tool schema</text>
- <text x="270" y="324" class="small" text-anchor="middle">Output validated at the serialization boundary</text>
+ <text x="270" y="324" class="small" text-anchor="middle">Output enforced at the serialization boundary (OutputValidationError)</text>
<rect class="box p-cyan" x="60" y="360" width="420" height="78" rx="6"/>
<text x="270" y="382" class="h2" text-anchor="middle">@Operation methods</text>
<text x="270" y="402" class="sub" text-anchor="middle">async def op(self, ctx, params) -&gt; Output</text>
- <text x="270" y="420" class="small" text-anchor="middle">the business logic lives here</text>
+ <text x="270" y="420" class="small" text-anchor="middle">or a declarative routing= for plain REST calls (Connection facade)</text>
<rect class="box p-cyan" x="60" y="456" width="420" height="78" rx="6"/>
- <text x="270" y="478" class="h2" text-anchor="middle">icon.svg + meta.json</text>
- <text x="270" y="498" class="sub" text-anchor="middle">co-located icon + {"color": "#..."}</text>
- <text x="270" y="516" class="small" text-anchor="middle">icon/color are NOT class attributes</text>
+ <text x="270" y="478" class="h2" text-anchor="middle">icon.svg / icon_&lt;type&gt;.svg + meta.json</text>
+ <text x="270" y="498" class="sub" text-anchor="middle">co-located brand mark + {"color": "#..."}</text>
+ <text x="270" y="516" class="small" text-anchor="middle">or lucide: / emoji refs in meta.json - never class attributes</text>
<rect class="box p-cyan" x="60" y="552" width="420" height="78" rx="6"/>
<text x="270" y="574" class="h2" text-anchor="middle">Optional siblings (rich plugins)</text>
- <text x="270" y="594" class="sub" text-anchor="middle">_service.py / _handlers.py / _credentials.py</text>
- <text x="270" y="612" class="small" text-anchor="middle">for bots, daemons, signed webhooks</text>
+ <text x="270" y="594" class="small" text-anchor="middle">_service.py &#183; _handlers.py &#183; _credentials.py &#183; _events.py &#183; _router.py</text>
+ <text x="270" y="612" class="small" text-anchor="middle">bots, daemons, OAuth, signed webhooks - telegram/ is the reference</text>
<!-- ================= GROUP 2 (purple): Auto-registration ================= -->
<rect class="panel p-purple" x="650" y="100" width="460" height="449" rx="10"/>
@@ -65,22 +65,22 @@
<rect class="box p-purple" x="670" y="168" width="420" height="78" rx="6"/>
<text x="880" y="190" class="h2" text-anchor="middle">__init_subclass__ fires</text>
<text x="880" y="210" class="sub" text-anchor="middle">nodes/__init__.py pkgutil walker imports every plugin</text>
- <text x="880" y="228" class="small" text-anchor="middle">no manual registry edit, no node_executor.py</text>
+ <text x="880" y="228" class="small" text-anchor="middle">no manual registry edit, no node_executor.py, no main.py edit</text>
<rect class="box p-purple" x="670" y="264" width="420" height="78" rx="6"/>
<text x="880" y="286" class="h2" text-anchor="middle">5 registries populated</text>
<text x="880" y="306" class="sub" text-anchor="middle">_NODE_CLASS_REGISTRY &#183; NODE_METADATA &#183; _DIRECT_MODELS</text>
- <text x="880" y="324" class="small" text-anchor="middle">NODE_OUTPUT_SCHEMAS &#183; _HANDLER_REGISTRY</text>
+ <text x="880" y="324" class="small" text-anchor="middle">NODE_OUTPUT_SCHEMAS &#183; _HANDLER_REGISTRY (class registry first)</text>
<rect class="box p-purple" x="670" y="360" width="420" height="78" rx="6"/>
<text x="880" y="382" class="h2" text-anchor="middle">Temporal activity minted</text>
<text x="880" y="402" class="sub" text-anchor="middle">cls.as_activity() -&gt; node.{type}.v{version}</text>
- <text x="880" y="420" class="small" text-anchor="middle">routed to its task_queue worker pool</text>
+ <text x="880" y="420" class="small" text-anchor="middle">task_queue worker (9 queues) &#183; class RetryPolicy + timeouts</text>
<rect class="box p-purple" x="670" y="456" width="420" height="78" rx="6"/>
- <text x="880" y="478" class="h2" text-anchor="middle">6 self-registration hooks (rich plugins)</text>
- <text x="880" y="498" class="sub" text-anchor="middle">ws_handlers &#183; router &#183; filter_builder</text>
- <text x="880" y="516" class="small" text-anchor="middle">trigger_precheck &#183; service_refresh &#183; output_schema</text>
+ <text x="880" y="478" class="h2" text-anchor="middle">18 self-registration hooks (rich plugins)</text>
+ <text x="880" y="498" class="sub" text-anchor="middle">ws_handlers &#183; router &#183; option_loader &#183; oauth_callback_path</text>
+ <text x="880" y="516" class="small" text-anchor="middle">filter_builder &#183; webhook_source &#183; canary_trigger &#183; output_schema ...</text>
<!-- ================= GROUP 3 (green): What the frontend sees ================= -->
<rect class="panel p-green" x="1260" y="100" width="460" height="353" rx="10"/>
@@ -90,17 +90,17 @@
<rect class="box p-green" x="1280" y="168" width="420" height="78" rx="6"/>
<text x="1490" y="190" class="h2" text-anchor="middle">NodeSpec endpoint</text>
<text x="1490" y="210" class="sub" text-anchor="middle">GET /api/schemas/nodes/{type}/spec.json</text>
- <text x="1490" y="228" class="small" text-anchor="middle">display meta + params + output schema</text>
+ <text x="1490" y="228" class="small" text-anchor="middle">display meta, params, output schema, handles, uiHints, component_kind</text>
<rect class="box p-green" x="1280" y="264" width="420" height="78" rx="6"/>
<text x="1490" y="286" class="h2" text-anchor="middle">useNodeSpec renders it</text>
- <text x="1490" y="306" class="sub" text-anchor="middle">nodeSpecToDescription adapter builds the param panel,</text>
- <text x="1490" y="324" class="small" text-anchor="middle">palette entry, and canvas handles - no client edits</text>
+ <text x="1490" y="306" class="sub" text-anchor="middle">canvas node picked by component_kind, param panel from</text>
+ <text x="1490" y="324" class="small" text-anchor="middle">the JSON Schema, palette entry from the group - no client edits</text>
<rect class="box p-green" x="1280" y="360" width="420" height="78" rx="6"/>
<text x="1490" y="382" class="h2" text-anchor="middle">Credentials modal</text>
- <text x="1490" y="402" class="sub" text-anchor="middle">declare a Credential subclass;</text>
- <text x="1490" y="420" class="small" text-anchor="middle">modal renders from credential_providers.json</text>
+ <text x="1490" y="402" class="sub" text-anchor="middle">declare a Credential subclass in _credentials.py;</text>
+ <text x="1490" y="420" class="small" text-anchor="middle">modal renders from credential_providers.json (key / OAuth / CLI)</text>
<!-- ================= Arrows between groups ================= -->
<text x="575" y="292" class="label" text-anchor="middle">import re-registers</text>
@@ -114,8 +114,9 @@
<!-- ================= Banner ================= -->
<rect class="panel p-pink" x="40" y="675" width="1680" height="58" rx="10"/>
- <text x="880" y="711" class="accent-pink" font-size="18" font-weight="700" text-anchor="middle">No TypeScript node definition &#183; No node_executor.py registry entry &#183; No frontend edits</text>
+ <text x="880" y="711" class="accent-pink" font-size="18" font-weight="700" text-anchor="middle">No TypeScript node definition &#183; No node_executor.py registry entry &#183; No frontend edits &#183; No core-services edits</text>
- <!-- ================= Footnote ================= -->
- <text x="880" y="763" class="label" text-anchor="middle">Edge case: if tool_name != snake_case(type) and the plugin ships a paired skill, add a visuals.json alias (icon + color) - locked by tests/test_skill_icon_resolution.py</text>
+ <!-- ================= Footnotes ================= -->
+ <text x="880" y="763" class="label" text-anchor="middle">Locked by tests/test_plugin_self_containment.py: core never imports a plugin and main.py mounts nothing per plugin - handlers, routers and OAuth callbacks self-register.</text>
+ <text x="880" y="785" class="label" text-anchor="middle">Edge case: if tool_name != snake_case(type) and the plugin ships a paired skill, add a visuals.json alias (icon + color) - locked by tests/test_skill_icon_resolution.py</text>
</svg>
diff --git a/docs/diagrams/system-overview.svg b/docs/diagrams/system-overview.svg
index c2b0eae6..35fe40bd 100644
--- a/docs/diagrams/system-overview.svg
+++ b/docs/diagrams/system-overview.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1800 1080" width="100%" preserveAspectRatio="xMidYMid meet" font-family="ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Monaco, Consolas, monospace">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1800 1120" width="100%" preserveAspectRatio="xMidYMid meet" font-family="ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Monaco, Consolas, monospace">
<!-- Palette: OpenCompany dark-theme tokens (client/src/themes/dark.css surfaces/fg + light.css Dracula accents) -->
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
@@ -13,6 +13,7 @@
.h2 { fill: #e8eaed; font-size: 14px; font-weight: 700; }
.sub { fill: #e8eaed; font-size: 12px; }
.small { fill: #e8eaed; font-size: 10px; }
+ .dim { fill: #9aa1ac; font-size: 10px; }
.label { fill: #f1fa8c; font-size: 11px; font-style: italic; }
.conn { stroke: #e8eaed; stroke-width: 1.8; fill: none; }
.conn-dot { stroke: #9aa1ac; stroke-width: 1.5; fill: none; stroke-dasharray: 4 4; }
@@ -22,92 +23,118 @@
.title, .h1, .h2 { font-family: 'Geist Variable', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
</style>
</defs>
- <rect class="bg" width="1800" height="1080"/>
+ <rect class="bg" width="1800" height="1120"/>
<text class="title" x="900" y="44" text-anchor="middle">OpenCompany - System Overview</text>
- <text class="sub" x="900" y="70" text-anchor="middle">FastAPI plugin backend + React Flow client + sidecar processes (single-machine dev topology)</text>
-
- <!-- ===== Tier: Browser ===== -->
- <text class="tier-label" x="230" y="96">BROWSER</text>
- <rect class="panel p-cyan" x="230" y="104" width="960" height="110" rx="10"/>
- <rect class="box p-cyan" x="500" y="118" width="420" height="82" rx="8"/>
- <text class="h2" x="710" y="144" text-anchor="middle">React Flow client</text>
- <text class="sub" x="710" y="163" text-anchor="middle">client/ - Vite dev :5679</text>
- <text class="sub" x="710" y="181" text-anchor="middle">React 19 + Tailwind v4 + shadcn/ui + Zustand</text>
-
- <!-- Browser <-> Backend -->
- <path class="conn" d="M 558 218 L 558 314" marker-end="url(#arrow)"/>
- <path class="conn" d="M 568 314 L 568 218" marker-end="url(#arrow)"/>
- <text class="label" x="546" y="270" text-anchor="end">WebSocket /ws/status</text>
- <path class="conn" d="M 860 218 L 860 314" marker-end="url(#arrow)"/>
- <text class="label" x="874" y="270">REST /api/*</text>
+ <text class="sub" x="900" y="70" text-anchor="middle">FastAPI plugin backend + React Flow client + sidecar processes, all on one machine (ports are named in .env.template)</text>
+
+ <!-- ===== Tier: Client hosts ===== -->
+ <text class="tier-label" x="230" y="96">CLIENT HOSTS</text>
+ <rect class="panel p-cyan" x="230" y="104" width="960" height="130" rx="10"/>
+
+ <rect class="box p-cyan" x="250" y="120" width="450" height="98" rx="8"/>
+ <text class="h2" x="475" y="145" text-anchor="middle">Browser tab</text>
+ <text class="sub" x="475" y="165" text-anchor="middle">http://localhost:5678 - the built SPA served by the backend</text>
+ <text class="small" x="475" y="184" text-anchor="middle">React 19 + Vite + Tailwind v4 + shadcn/ui + Zustand + TanStack Query</text>
+ <text class="small" x="475" y="202" text-anchor="middle">company dev: Vite HMR on the app port, backend moved behind it</text>
+
+ <rect class="box p-cyan" x="720" y="120" width="450" height="98" rx="8"/>
+ <text class="h2" x="945" y="145" text-anchor="middle">Desktop app (Electron shell, desktop/)</text>
+ <text class="sub" x="945" y="165" text-anchor="middle">bundles uv + CPython 3.12 + bun - no Node, no npm</text>
+ <text class="small" x="945" y="184" text-anchor="middle">first launch: uv sync into the app data dir, then spawns uvicorn</text>
+ <text class="small" x="945" y="202" text-anchor="middle">waits on /health/ready, loads the same SPA, opens OAuth in the OS browser</text>
+
+ <!-- Client <-> Backend -->
+ <path class="conn" d="M 600 238 L 600 314" marker-end="url(#arrow)"/>
+ <path class="conn" d="M 612 314 L 612 238" marker-end="url(#arrow)"/>
+ <text class="label" x="588" y="280" text-anchor="end">WebSocket /ws/status (request/response + broadcasts)</text>
+ <path class="conn" d="M 860 238 L 860 314" marker-end="url(#arrow)"/>
+ <text class="label" x="874" y="280">REST /api/* - /health - /health/ready</text>
<!-- Inbound webhook into backend left edge -->
<path class="conn" d="M 40 430 L 226 430" marker-end="url(#arrow)"/>
<text class="label" x="130" y="414" text-anchor="middle">/webhook/{path} (inbound)</text>
+ <text class="dim" x="130" y="448" text-anchor="middle">Stripe, Discord,</text>
+ <text class="dim" x="130" y="462" text-anchor="middle">WhatsApp Business, custom</text>
<!-- ===== Tier: Python backend ===== -->
<text class="tier-label" x="230" y="310">PYTHON BACKEND</text>
- <rect class="panel p-purple" x="230" y="318" width="960" height="324" rx="10"/>
- <text class="h1" x="710" y="348" text-anchor="middle">Python backend - FastAPI :5678 (server/)</text>
-
- <rect class="box p-purple" x="250" y="368" width="435" height="70" rx="8"/>
- <text class="h2" x="467" y="395" text-anchor="middle">WS + REST dispatch</text>
- <text class="small" x="467" y="417" text-anchor="middle">core MESSAGE_HANDLERS + plugin ws_handler_registry</text>
-
- <rect class="box p-purple" x="735" y="368" width="435" height="70" rx="8"/>
- <text class="h2" x="952" y="395" text-anchor="middle">WorkflowService -&gt; NodeExecutor</text>
- <text class="sub" x="952" y="417" text-anchor="middle">ParameterResolver {{node.field}}</text>
-
- <rect class="box p-purple" x="250" y="456" width="435" height="84" rx="8"/>
- <text class="h2" x="467" y="483" text-anchor="middle">Node plugins (115+)</text>
- <text class="small" x="467" y="503" text-anchor="middle">server/nodes/&lt;group&gt;/&lt;plugin&gt;/</text>
- <text class="small" x="467" y="521" text-anchor="middle">Pydantic Params/Output = SSOT</text>
-
- <rect class="box p-purple" x="735" y="456" width="435" height="84" rx="8"/>
- <text class="h2" x="952" y="483" text-anchor="middle">AuthService</text>
- <text class="sub" x="952" y="507" text-anchor="middle">Fernet + PBKDF2 encrypted credentials</text>
-
- <rect class="box p-purple" x="250" y="558" width="920" height="64" rx="8"/>
- <text class="h2" x="710" y="584" text-anchor="middle">Execution engine</text>
- <text class="sub" x="710" y="607" text-anchor="middle">Temporal -&gt; sequential (auto-fallback)</text>
+ <rect class="panel p-purple" x="230" y="318" width="960" height="330" rx="10"/>
+ <text class="h1" x="710" y="348" text-anchor="middle">Python backend - FastAPI + uvicorn on PYTHON_BACKEND_PORT (server/)</text>
+
+ <rect class="box p-purple" x="250" y="368" width="435" height="72" rx="8"/>
+ <text class="h2" x="467" y="393" text-anchor="middle">WS + REST dispatch</text>
+ <text class="small" x="467" y="412" text-anchor="middle">core MESSAGE_HANDLERS + plugin ws_handler_registry</text>
+ <text class="small" x="467" y="428" text-anchor="middle">broadcasts are CloudEvents v1.0 envelopes</text>
+
+ <rect class="box p-purple" x="735" y="368" width="435" height="72" rx="8"/>
+ <text class="h2" x="952" y="393" text-anchor="middle">WorkflowService -&gt; NodeExecutor</text>
+ <text class="small" x="952" y="412" text-anchor="middle">ParameterResolver {{node.field}} - per-workflow workspace dir</text>
+ <text class="small" x="952" y="428" text-anchor="middle">DeploymentManager + WorkflowControlWorkflow (Start/Pause/Resume/Reset)</text>
+
+ <rect class="box p-purple" x="250" y="458" width="435" height="86" rx="8"/>
+ <text class="h2" x="467" y="483" text-anchor="middle">Node plugins (148, 34 palette groups)</text>
+ <text class="small" x="467" y="503" text-anchor="middle">server/nodes/&lt;group&gt;/&lt;plugin&gt;/ - one folder per node</text>
+ <text class="small" x="467" y="519" text-anchor="middle">Pydantic Params / Output = SSOT, served as NodeSpec</text>
+ <text class="small" x="467" y="535" text-anchor="middle">78 skills in server/skills/ (SKILL.md playbooks)</text>
+
+ <rect class="box p-purple" x="735" y="458" width="435" height="86" rx="8"/>
+ <text class="h2" x="952" y="483" text-anchor="middle">AuthService + credentials</text>
+ <text class="small" x="952" y="503" text-anchor="middle">35 Credential classes (API keys, OAuth, CLI-managed logins)</text>
+ <text class="small" x="952" y="519" text-anchor="middle">Fernet + PBKDF2 encrypted credentials.db</text>
+ <text class="small" x="952" y="535" text-anchor="middle">optional JWT login (VITE_AUTH_ENABLED, AUTH_MODE single / multi)</text>
+
+ <rect class="box p-purple" x="250" y="562" width="920" height="70" rx="8"/>
+ <text class="h2" x="710" y="587" text-anchor="middle">Execution engine</text>
+ <text class="sub" x="710" y="607" text-anchor="middle">Temporal by default (per-type activities on 9 task queues, agents as child workflows) -&gt; sequential fallback</text>
+ <text class="small" x="710" y="624" text-anchor="middle">durable deployments: survive restarts, pause / resume, cron catch-up - see execution-flow.svg</text>
<!-- Backend -> Sidecars -->
- <path class="conn" d="M 710 646 L 710 722" marker-end="url(#arrow)"/>
- <text class="label" x="724" y="688">spawns / calls</text>
+ <path class="conn" d="M 710 652 L 710 722" marker-end="url(#arrow)"/>
+ <text class="label" x="724" y="690">spawns on demand / calls</text>
<!-- ===== Tier: Sidecar processes ===== -->
- <text class="tier-label" x="230" y="718">SIDECAR PROCESSES</text>
- <rect class="panel p-orange" x="230" y="726" width="960" height="120" rx="10"/>
-
- <rect class="box p-orange" x="250" y="746" width="215" height="80" rx="8"/>
- <text class="h2" x="357" y="772" text-anchor="middle">Node.js executor :5682</text>
- <text class="small" x="357" y="792" text-anchor="middle">Express + tsx</text>
- <text class="small" x="357" y="808" text-anchor="middle">JS/TS code nodes</text>
-
- <rect class="box p-orange" x="485" y="746" width="215" height="80" rx="8"/>
- <text class="h2" x="592" y="772" text-anchor="middle">WhatsApp RPC :5683</text>
- <text class="small" x="592" y="792" text-anchor="middle">Go whatsmeow binary</text>
-
- <rect class="box p-orange" x="720" y="746" width="215" height="80" rx="8"/>
- <text class="h2" x="827" y="772" text-anchor="middle">Temporal server</text>
- <text class="small" x="827" y="792" text-anchor="middle">gRPC :5681 - Web UI :5680</text>
-
- <rect class="box p-orange" x="955" y="746" width="215" height="80" rx="8"/>
- <text class="h2" x="1062" y="772" text-anchor="middle">Temporal workers</text>
- <text class="small" x="1062" y="792" text-anchor="middle">manager + per-queue</text>
- <text class="small" x="1062" y="808" text-anchor="middle">worker pool</text>
+ <text class="tier-label" x="230" y="718">SIDECAR PROCESSES (all backend-spawned)</text>
+ <rect class="panel p-orange" x="230" y="726" width="960" height="162" rx="10"/>
+
+ <rect class="box p-orange" x="250" y="742" width="215" height="102" rx="8"/>
+ <text class="h2" x="357" y="766" text-anchor="middle">JS / TS executor</text>
+ <text class="small" x="357" y="786" text-anchor="middle">Express bundle run by bun</text>
+ <text class="small" x="357" y="802" text-anchor="middle">(bun build --target=bun)</text>
+ <text class="dim" x="357" y="820" text-anchor="middle">NODEJS_EXECUTOR_PORT</text>
+
+ <rect class="box p-orange" x="485" y="742" width="215" height="102" rx="8"/>
+ <text class="h2" x="592" y="766" text-anchor="middle">WhatsApp bridge</text>
+ <text class="small" x="592" y="786" text-anchor="middle">edgymeow (Go, whatsmeow)</text>
+ <text class="small" x="592" y="802" text-anchor="middle">bun-managed package</text>
+ <text class="dim" x="592" y="820" text-anchor="middle">WHATSAPP_RPC_PORT</text>
+
+ <rect class="box p-orange" x="720" y="742" width="215" height="102" rx="8"/>
+ <text class="h2" x="827" y="766" text-anchor="middle">Temporal dev server</text>
+ <text class="small" x="827" y="786" text-anchor="middle">pinned CLI, SQLite history</text>
+ <text class="small" x="827" y="802" text-anchor="middle">supervised by the lifespan</text>
+ <text class="dim" x="827" y="820" text-anchor="middle">TEMPORAL_FRONTEND_GRPC_PORT</text>
+ <text class="dim" x="827" y="834" text-anchor="middle">TEMPORAL_UI_PORT</text>
+
+ <rect class="box p-orange" x="955" y="742" width="215" height="102" rx="8"/>
+ <text class="h2" x="1062" y="766" text-anchor="middle">Temporal workers</text>
+ <text class="small" x="1062" y="786" text-anchor="middle">framework worker +</text>
+ <text class="small" x="1062" y="802" text-anchor="middle">TemporalWorkerPool</text>
+ <text class="dim" x="1062" y="820" text-anchor="middle">one worker per task queue</text>
+
+ <text class="dim" x="710" y="870" text-anchor="middle">plugin CLIs run as subprocesses from the shared bun tree in ~/.opencompany/packages/: claude, gh, cf, vercel, gcloud, stripe, agent-browser</text>
<!-- Backend -> Storage (routed around sidecar tier) -->
- <path class="conn" d="M 230 610 L 170 610 L 170 985 L 226 985" marker-end="url(#arrow)"/>
- <text class="label" x="162" y="800" text-anchor="end">read/write</text>
+ <path class="conn" d="M 230 610 L 170 610 L 170 1010 L 226 1010" marker-end="url(#arrow)"/>
+ <text class="label" x="162" y="820" text-anchor="end">read/write</text>
<!-- ===== Tier: Storage ===== -->
- <text class="tier-label" x="230" y="922">STORAGE</text>
- <rect class="panel p-pink" x="230" y="930" width="960" height="110" rx="10"/>
- <rect class="box p-pink" x="250" y="950" width="920" height="70" rx="8"/>
- <text class="h2" x="710" y="977" text-anchor="middle">~/.opencompany/</text>
- <text class="sub" x="710" y="1000" text-anchor="middle">workflow.db - credentials.db - temporal.db - Redis cache/locks (optional)</text>
+ <text class="tier-label" x="230" y="946">STORAGE</text>
+ <rect class="panel p-pink" x="230" y="954" width="960" height="118" rx="10"/>
+ <rect class="box p-pink" x="250" y="970" width="920" height="86" rx="8"/>
+ <text class="h2" x="710" y="995" text-anchor="middle">~/.opencompany/ (DATA_DIR - shared by CLI installs and the desktop app)</text>
+ <text class="sub" x="710" y="1016" text-anchor="middle">workflow.db - credentials.db - temporal.db - workspaces/&lt;slug&gt;/ - packages/ - daemons/ - claude/</text>
+ <text class="small" x="710" y="1036" text-anchor="middle">SQLite everywhere; Redis is opt-in (REDIS_ENABLED, default off) and no shipped configuration enables it</text>
<!-- Backend / Sidecars -> External services -->
<path class="conn" d="M 1194 480 L 1316 480" marker-end="url(#arrow)"/>
@@ -117,45 +144,53 @@
<!-- ===== External services (right column) ===== -->
<text class="tier-label" x="1320" y="96">EXTERNAL SERVICES</text>
- <rect class="panel p-green" x="1320" y="104" width="440" height="936" rx="10"/>
+ <rect class="panel p-green" x="1320" y="104" width="440" height="968" rx="10"/>
<text class="h1" x="1540" y="134" text-anchor="middle">External services</text>
- <rect class="box p-green" x="1340" y="152" width="400" height="116" rx="8"/>
- <text class="h2" x="1540" y="177" text-anchor="middle">LLM providers (12)</text>
- <text class="sub" x="1540" y="197" text-anchor="middle">OpenAI, Anthropic, Gemini, OpenRouter, xAI,</text>
- <text class="sub" x="1540" y="215" text-anchor="middle">DeepSeek, Kimi, Mistral, Groq, Cerebras</text>
- <text class="sub" x="1540" y="233" text-anchor="middle">local: Ollama, LM Studio</text>
- <text class="sub" x="1540" y="251" text-anchor="middle">image input: native blocks + visionAnalyze delegate</text>
+ <rect class="box p-green" x="1340" y="150" width="400" height="116" rx="8"/>
+ <text class="h2" x="1540" y="175" text-anchor="middle">LLM providers (13)</text>
+ <text class="sub" x="1540" y="195" text-anchor="middle">OpenAI, Anthropic, Gemini, OpenRouter, xAI, DeepSeek,</text>
+ <text class="sub" x="1540" y="213" text-anchor="middle">Kimi, Mistral, Groq, Cerebras, Sarvam</text>
+ <text class="sub" x="1540" y="231" text-anchor="middle">local and free: Ollama, LM Studio</text>
+ <text class="small" x="1540" y="251" text-anchor="middle">image input: native image blocks + visionAnalyze delegate</text>
+
+ <rect class="box p-green" x="1340" y="282" width="400" height="62" rx="8"/>
+ <text class="h2" x="1540" y="305" text-anchor="middle">Speech + translation</text>
+ <text class="sub" x="1540" y="325" text-anchor="middle">OpenAI, ElevenLabs, Deepgram, Groq, Sarvam, DeepL</text>
+
+ <rect class="box p-green" x="1340" y="360" width="400" height="62" rx="8"/>
+ <text class="h2" x="1540" y="383" text-anchor="middle">Workspace suites + email</text>
+ <text class="sub" x="1540" y="403" text-anchor="middle">Google Workspace (6 apps), Microsoft 365, IMAP / SMTP</text>
- <rect class="box p-green" x="1340" y="280" width="400" height="60" rx="8"/>
- <text class="h2" x="1540" y="305" text-anchor="middle">Google Workspace</text>
- <text class="sub" x="1540" y="325" text-anchor="middle">Gmail, Calendar, Drive, Sheets, Tasks, Contacts</text>
+ <rect class="box p-green" x="1340" y="438" width="400" height="62" rx="8"/>
+ <text class="h2" x="1540" y="461" text-anchor="middle">Messaging + social</text>
+ <text class="sub" x="1540" y="481" text-anchor="middle">WhatsApp, WhatsApp Business, Telegram, Discord, X</text>
- <rect class="box p-green" x="1340" y="368" width="400" height="60" rx="8"/>
- <text class="h2" x="1540" y="393" text-anchor="middle">Messaging</text>
- <text class="sub" x="1540" y="413" text-anchor="middle">WhatsApp, Telegram, Twitter/X</text>
+ <rect class="box p-green" x="1340" y="516" width="400" height="78" rx="8"/>
+ <text class="h2" x="1540" y="539" text-anchor="middle">Search + scraping</text>
+ <text class="sub" x="1540" y="559" text-anchor="middle">DuckDuckGo (free), Brave, Serper, Perplexity</text>
+ <text class="sub" x="1540" y="577" text-anchor="middle">Apify actors, Crawlee, TikHub (social data)</text>
- <rect class="box p-green" x="1340" y="456" width="400" height="60" rx="8"/>
- <text class="h2" x="1540" y="481" text-anchor="middle">Search APIs</text>
- <text class="sub" x="1540" y="501" text-anchor="middle">DuckDuckGo (free), Brave, Serper, Perplexity</text>
+ <rect class="box p-green" x="1340" y="610" width="400" height="62" rx="8"/>
+ <text class="h2" x="1540" y="633" text-anchor="middle">Dev + cloud CLIs</text>
+ <text class="sub" x="1540" y="653" text-anchor="middle">GitHub gh, Vercel, Cloudflare cf, Google Cloud gcloud</text>
- <rect class="box p-green" x="1340" y="544" width="400" height="60" rx="8"/>
- <text class="h2" x="1540" y="569" text-anchor="middle">Web scraping</text>
- <text class="sub" x="1540" y="589" text-anchor="middle">Apify actors, Crawlee, residential proxies</text>
+ <rect class="box p-green" x="1340" y="688" width="400" height="62" rx="8"/>
+ <text class="h2" x="1540" y="711" text-anchor="middle">Payments</text>
+ <text class="sub" x="1540" y="731" text-anchor="middle">Stripe CLI (actions + signed webhook trigger)</text>
- <rect class="box p-green" x="1340" y="632" width="400" height="60" rx="8"/>
- <text class="h2" x="1540" y="657" text-anchor="middle">Dev CLIs</text>
- <text class="sub" x="1540" y="677" text-anchor="middle">GitHub (gh), Vercel, Stripe</text>
+ <rect class="box p-green" x="1340" y="766" width="400" height="62" rx="8"/>
+ <text class="h2" x="1540" y="789" text-anchor="middle">Device + browser</text>
+ <text class="sub" x="1540" y="809" text-anchor="middle">Android via relay (16 nodes) - your real Chrome over CDP</text>
- <rect class="box p-green" x="1340" y="720" width="400" height="60" rx="8"/>
- <text class="h2" x="1540" y="745" text-anchor="middle">Device</text>
- <text class="sub" x="1540" y="765" text-anchor="middle">Android via relay - 16 service nodes</text>
+ <rect class="box p-green" x="1340" y="844" width="400" height="62" rx="8"/>
+ <text class="h2" x="1540" y="867" text-anchor="middle">Vector + RAG</text>
+ <text class="sub" x="1540" y="887" text-anchor="middle">ChromaDB, Qdrant, Pinecone + embeddings + chunking</text>
- <rect class="box p-green" x="1340" y="808" width="400" height="60" rx="8"/>
- <text class="h2" x="1540" y="833" text-anchor="middle">Vector + RAG</text>
- <text class="sub" x="1540" y="853" text-anchor="middle">ChromaDB, Qdrant, Pinecone</text>
+ <rect class="box p-green" x="1340" y="922" width="400" height="62" rx="8"/>
+ <text class="h2" x="1540" y="945" text-anchor="middle">Maps + proxies</text>
+ <text class="sub" x="1540" y="965" text-anchor="middle">Google Maps Geocoding + Places - residential proxies</text>
- <rect class="box p-green" x="1340" y="896" width="400" height="60" rx="8"/>
- <text class="h2" x="1540" y="921" text-anchor="middle">Maps</text>
- <text class="sub" x="1540" y="941" text-anchor="middle">Google Maps Geocoding + Places</text>
+ <text class="dim" x="1540" y="1020" text-anchor="middle">Counts come from the live registries: len(NODE_METADATA),</text>
+ <text class="dim" x="1540" y="1036" text-anchor="middle">len(CREDENTIAL_REGISTRY), config/llm_defaults.json - September 2026</text>
</svg>