# rouicezar/formabot architecture

> Architecture diagram of the GitHub repository rouicezar/formabot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rouicezar/formabot
- Repository: https://github.com/rouicezar/formabot

## Overview

FormaBot is a local desktop workspace for persistent AI bots and groups. The main workflow is: a user sends a message in a conversation, the desktop forwards it to the runtime, and the runtime routes work to bot or group members for execution with authorized tools; progress and delivered files return to the workspace for review. Settings, workspace authorization, approvals, memory, browser use, web search, skills, and the optional Figma MCP connection are additional capabilities. The sampled excerpts show portions of this flow; some subsystem links follow the README rather than inspected call sites.

Main entry points: [`src/desktop/main.ts`](https://github.com/rouicezar/formabot/blob/main/src/desktop/main.ts) (Desktop main), [`src/runtime/conversation-session.ts`](https://github.com/rouicezar/formabot/blob/main/src/runtime/conversation-session.ts) (Conversation session), [`src/runtime/tools-plugin.ts`](https://github.com/rouicezar/formabot/blob/main/src/runtime/tools-plugin.ts) (Tool dispatch), [`src/desktop/renderer.ts`](https://github.com/rouicezar/formabot/blob/main/src/desktop/renderer.ts) (Workspace UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop workspace"]
  node_renderer["Workspace UI<br/>[renderer.ts]"]
  node_preview["Artifact preview<br/>[preview.ts]"]
  node_settings["Settings UI"]
  node_main["Desktop main<br/>[main.ts]"]
end

subgraph group_coordination["Team coordination"]
  node_session["Conversation session"]
  node_routing["Group routing<br/>[group-routing.ts]"]
  node_attention["Attention selection<br/>[attention.ts]"]
end

subgraph group_execution["Task execution"]
  node_supervisor["Task supervisor<br/>[supervisor.ts]"]
  node_taskhost["Task host<br/>[task-host.ts]"]
  node_toolsplugin["Tool dispatch<br/>[tools-plugin.ts]"]
end

subgraph group_capabilities["Tools and integrations"]
  node_localtools["Local file tools<br/>[local.ts]"]
  node_fileworker["Workspace file worker<br/>[file-worker.ts]"]
  node_browser["Browser tools<br/>[browser.ts]"]
  node_search["Web search<br/>[web-search.ts]"]
  node_discovery["Tool discovery<br/>[discovery.ts]"]
  node_skills["Skills<br/>[skills.ts]"]
  node_mcp["Figma MCP<br/>[mcp.ts]"]
end

subgraph group_state["Workspace state"]
  node_workbench[("Conversation state<br/>[workbench.ts]")]
  node_taskstore[("Task records<br/>[tasks.ts]")]
  node_config["Model settings<br/>[config.ts]"]
end

node_user(("User"))
node_provider{{"Model provider"}}

node_user -->|"sends messages"| node_renderer
node_renderer -->|"invokes IPC"| node_main
node_main -->|"starts tasks"| node_session
node_session -->|"selects recipients"| node_attention
node_session -->|"resolves mentions"| node_routing
node_session -->|"records conversation"| node_workbench
node_session -->|"dispatches jobs"| node_supervisor
node_supervisor -->|"runs tasks"| node_taskhost
node_supervisor -->|"records task status"| node_taskstore
node_taskhost -->|"requests inference"| node_provider
node_taskhost -->|"dispatches tools"| node_toolsplugin
node_toolsplugin -->|"invokes local tools"| node_localtools
node_localtools -->|"runs file operations"| node_fileworker
node_toolsplugin -->|"invokes browser"| node_browser
node_toolsplugin -->|"invokes search"| node_search
node_main -->|"checks authorization"| node_taskstore
node_main -->|"reads previews"| node_fileworker
node_renderer -->|"opens artifacts"| node_preview
node_preview -->|"requests preview"| node_main
node_settings -->|"updates settings"| node_main
node_main -->|"loads model config"| node_config
node_main -->|"scans tools"| node_discovery
node_main -->|"manages skills"| node_skills
node_main -.->|"manages connection"| node_mcp

click node_renderer "https://github.com/rouicezar/formabot/blob/main/src/desktop/renderer.ts"
click node_preview "https://github.com/rouicezar/formabot/blob/main/src/desktop/preview.ts"
click node_settings "https://github.com/rouicezar/formabot/blob/main/src/desktop/settings-renderer.ts"
click node_main "https://github.com/rouicezar/formabot/blob/main/src/desktop/main.ts"
click node_session "https://github.com/rouicezar/formabot/blob/main/src/runtime/conversation-session.ts"
click node_routing "https://github.com/rouicezar/formabot/blob/main/src/runtime/group-routing.ts"
click node_attention "https://github.com/rouicezar/formabot/blob/main/src/runtime/attention.ts"
click node_supervisor "https://github.com/rouicezar/formabot/blob/main/src/runtime/supervisor.ts"
click node_taskhost "https://github.com/rouicezar/formabot/blob/main/src/runtime/task-host.ts"
click node_toolsplugin "https://github.com/rouicezar/formabot/blob/main/src/runtime/tools-plugin.ts"
click node_workbench "https://github.com/rouicezar/formabot/blob/main/src/state/workbench.ts"
click node_taskstore "https://github.com/rouicezar/formabot/blob/main/src/state/tasks.ts"
click node_config "https://github.com/rouicezar/formabot/blob/main/src/models/config.ts"
click node_localtools "https://github.com/rouicezar/formabot/blob/main/src/tools/local.ts"
click node_fileworker "https://github.com/rouicezar/formabot/blob/main/src/tools/file-worker.ts"
click node_browser "https://github.com/rouicezar/formabot/blob/main/src/tools/browser.ts"
click node_search "https://github.com/rouicezar/formabot/blob/main/src/tools/web-search.ts"
click node_discovery "https://github.com/rouicezar/formabot/blob/main/src/capabilities/discovery.ts"
click node_skills "https://github.com/rouicezar/formabot/blob/main/src/capabilities/skills.ts"
click node_mcp "https://github.com/rouicezar/formabot/blob/main/src/capabilities/mcp.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_renderer,node_preview,node_settings,node_main,node_user toneBlue
class node_session,node_routing,node_attention toneAmber
class node_supervisor,node_taskhost,node_toolsplugin toneMint
class node_localtools,node_fileworker,node_browser,node_search,node_discovery,node_skills,node_mcp toneRose
class node_workbench,node_taskstore,node_config,node_provider toneIndigo
```

## Components

### Desktop workspace

- [Workspace UI](https://github.com/rouicezar/formabot/blob/main/src/desktop/renderer.ts): `src/desktop/renderer.ts`
- [Artifact preview](https://github.com/rouicezar/formabot/blob/main/src/desktop/preview.ts): `src/desktop/preview.ts`
- [Settings UI](https://github.com/rouicezar/formabot/blob/main/src/desktop/settings-renderer.ts): `src/desktop/settings-renderer.ts`
- [Desktop main](https://github.com/rouicezar/formabot/blob/main/src/desktop/main.ts): `src/desktop/main.ts`

### Team coordination

- [Conversation session](https://github.com/rouicezar/formabot/blob/main/src/runtime/conversation-session.ts): `src/runtime/conversation-session.ts`
- [Group routing](https://github.com/rouicezar/formabot/blob/main/src/runtime/group-routing.ts): `src/runtime/group-routing.ts`
- [Attention selection](https://github.com/rouicezar/formabot/blob/main/src/runtime/attention.ts): `src/runtime/attention.ts`

### Task execution

- [Task supervisor](https://github.com/rouicezar/formabot/blob/main/src/runtime/supervisor.ts): `src/runtime/supervisor.ts`
- [Task host](https://github.com/rouicezar/formabot/blob/main/src/runtime/task-host.ts): `src/runtime/task-host.ts`
- [Tool dispatch](https://github.com/rouicezar/formabot/blob/main/src/runtime/tools-plugin.ts): `src/runtime/tools-plugin.ts`

### Tools and integrations

- [Local file tools](https://github.com/rouicezar/formabot/blob/main/src/tools/local.ts): `src/tools/local.ts`
- [Workspace file worker](https://github.com/rouicezar/formabot/blob/main/src/tools/file-worker.ts): `src/tools/file-worker.ts`
- [Browser tools](https://github.com/rouicezar/formabot/blob/main/src/tools/browser.ts): `src/tools/browser.ts`
- [Web search](https://github.com/rouicezar/formabot/blob/main/src/tools/web-search.ts): `src/tools/web-search.ts`
- [Tool discovery](https://github.com/rouicezar/formabot/blob/main/src/capabilities/discovery.ts): `src/capabilities/discovery.ts`
- [Skills](https://github.com/rouicezar/formabot/blob/main/src/capabilities/skills.ts): `src/capabilities/skills.ts`
- [Figma MCP](https://github.com/rouicezar/formabot/blob/main/src/capabilities/mcp.ts): `src/capabilities/mcp.ts`

### Workspace state

- [Conversation state](https://github.com/rouicezar/formabot/blob/main/src/state/workbench.ts): `src/state/workbench.ts`
- [Task records](https://github.com/rouicezar/formabot/blob/main/src/state/tasks.ts): `src/state/tasks.ts`
- [Model settings](https://github.com/rouicezar/formabot/blob/main/src/models/config.ts): `src/models/config.ts`

### Other components

- **User**
- **Model provider**

## Connections

- User → Workspace UI: sends messages
- Workspace UI → Desktop main: invokes IPC
- Desktop main → Conversation session: starts tasks
- Conversation session → Attention selection: selects recipients
- Conversation session → Group routing: resolves mentions
- Conversation session → Conversation state: records conversation
- Conversation session → Task supervisor: dispatches jobs
- Task supervisor → Task host: runs tasks
- Task supervisor → Task records: records task status
- Task host → Model provider: requests inference
- Task host → Tool dispatch: dispatches tools
- Tool dispatch → Local file tools: invokes local tools
- Local file tools → Workspace file worker: runs file operations
- Tool dispatch → Browser tools: invokes browser
- Tool dispatch → Web search: invokes search
- Desktop main → Task records: checks authorization
- Desktop main → Workspace file worker: reads previews
- Workspace UI → Artifact preview: opens artifacts
- Artifact preview → Desktop main: requests preview
- Settings UI → Desktop main: updates settings
- Desktop main → Model settings: loads model config
- Desktop main → Tool discovery: scans tools
- Desktop main → Skills: manages skills
- Desktop main → Figma MCP: manages connection