Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
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.svgindex 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 -> 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 -> 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) -> 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) -> 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 · OpenAI · Gemini · 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 · OpenAI · Gemini · 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 · 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 -> 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 -> skills, tools, teammates -> 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 -> tool_calls? dispatch -> tool message</text>- <text class="sub" x="855" y="510" text-anchor="middle">max-iterations guard · delegate_to_<type> 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 -> 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 -> tool_calls? dispatch -> tool results -> 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) · 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 · thinking · tool_calls · usage · model · 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 · thinking · tool_calls · usage · model · 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.svgindex 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 -> WorkflowService routing -> shared node dispatch</text>+ <text x="40" y="68" class="sub">Two entry points -> WorkflowService routing -> 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 -> WorkflowService.execute_node</text>- <text x="250" y="178" class="sub" text-anchor="middle">runs ONE node · no mode routing</text>+ <text x="250" y="178" class="sub" text-anchor="middle">runs ONE node in-process · 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 -> 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 · 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) · 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 · 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) · 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">-> 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">-> Signal each matching listener · 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 · 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 · 10 min timeout · 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 · 2 min heartbeat</text>+ <text x="520" y="958" class="sub" text-anchor="middle">24 h start-to-close · 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 · 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 · 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 · class-based plugins in server/nodes/<group>/</text>- <text x="610" y="1114" class="sub" text-anchor="middle">-> 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() -> BaseNode.execute()</text>+ <text x="610" y="1124" class="sub" text-anchor="middle">plugin registry dispatch · Params validated · log_context + OTel span per node</text>+ <text x="610" y="1144" class="sub" text-anchor="middle">Output checked at the serialization boundary · NodeUserError -> one WARN line + error envelope</text>+ <text x="610" y="1164" class="sub" text-anchor="middle">-> 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) -> 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">-> frontend WebSocket /ws/status</text></svg>diff --git a/docs/diagrams/node-anatomy.svg b/docs/diagrams/node-anatomy.svgindex 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) -> 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_<type>.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 · _handlers.py · _credentials.py · _events.py · _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 · NODE_METADATA · _DIRECT_MODELS</text>- <text x="880" y="324" class="small" text-anchor="middle">NODE_OUTPUT_SCHEMAS · _HANDLER_REGISTRY</text>+ <text x="880" y="324" class="small" text-anchor="middle">NODE_OUTPUT_SCHEMAS · _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() -> 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) · 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 · router · filter_builder</text>- <text x="880" y="516" class="small" text-anchor="middle">trigger_precheck · service_refresh · 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 · router · option_loader · oauth_callback_path</text>+ <text x="880" y="516" class="small" text-anchor="middle">filter_builder · webhook_source · canary_trigger · 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 · No node_executor.py registry entry · 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 · No node_executor.py registry entry · No frontend edits · 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.svgindex 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 -> 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/<group>/<plugin>/</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 -> 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 -> 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/<group>/<plugin>/ - 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) -> 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/<slug>/ - 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>