# scs-labrat/figaro architecture

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

- Interactive diagram: https://gitdiagram.com/scs-labrat/figaro
- Repository: https://github.com/scs-labrat/figaro

## Overview

Figaro orchestrates long-running desktop-agent tasks: users submit work through the dashboard or conversational gateway; the orchestrator assigns tasks over NATS to workers or supervisors, tracks results and durable state, and exposes live desktop views. Other documented capabilities include recurring schedules, help requests, self-healing/self-learning, external desktop connections, and Telegram. The graph combines README-described behavior with indexed references and excerpts; unsampled subsystems and some UI-to-service wiring are shown only where documented, or omitted where evidence is insufficient.

Main entry points: [`figaro-nats/src/figaro_nats/client.py`](https://github.com/scs-labrat/figaro/blob/main/figaro-nats/src/figaro_nats/client.py) (NATS messaging), [`figaro/src/figaro/app.py`](https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/app.py) (Orchestrator app), [`figaro-ui/src/components/Dashboard.tsx`](https://github.com/scs-labrat/figaro/blob/main/figaro-ui/src/components/Dashboard.tsx) (Dashboard), [`figaro/src/figaro/services/nats/service.py`](https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/nats/service.py) (NATS service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_ui_state["Live UI state"]
  node_gateway["Telegram gateway<br/>[bot.py]"]
  node_router["Gateway router<br/>[router.py]"]
  node_ui_schedule["Schedule controls"]
  node_ui_desktop["Desktop controls"]
end

subgraph group_orchestration["Orchestration"]
  node_orchestrator["Orchestrator app<br/>[app.py]"]
  node_task_api["Task routing<br/>[api_tasks.py]"]
  node_task_manager["Task lifecycle<br/>[task_manager.py]"]
  node_event_handlers["Event handling<br/>[event_handlers.py]"]
  node_scheduler["Scheduled work<br/>[scheduler.py]"]
  node_help["Help requests<br/>[help_request.py]"]
end

subgraph group_agents["Agent runtime"]
  node_worker["Worker agent<br/>[executor.ts]"]
  node_supervisor["Supervisor agent<br/>[executor.ts]"]
  node_worker_entry["Agent entrypoint<br/>[index.ts]"]
  node_patchright["Browser automation<br/>[server.py]"]
end

subgraph group_desktop["Desktop access"]
  node_desktop_access["Remote desktop access"]
  node_guac["Guacamole streaming<br/>[guacamole.py]"]
end

subgraph group_platform["Messaging and state"]
  node_nats_service["NATS service<br/>[service.py]"]
  node_publishing["Task publishing<br/>[publishing.py]"]
  node_nats["NATS messaging<br/>[client.py]"]
  node_database[("PostgreSQL state<br/>[models.py]")]
end

node_user(("User"))

node_user -->|"manages tasks"| node_dashboard
node_dashboard -->|"renders updates"| node_ui_state
node_dashboard -.->|"communicates via"| node_nats
node_user -->|"sends instructions"| node_gateway
node_gateway -.->|"routes messages"| node_router
node_router -.->|"communicates via"| node_nats
node_orchestrator -->|"starts service"| node_nats_service
node_nats_service -->|"connects and subscribes"| node_nats
node_nats_service -->|"registers handlers"| node_task_api
node_nats_service -->|"registers handlers"| node_event_handlers
node_task_api -->|"creates and routes"| node_task_manager
node_task_api -->|"requests assignment"| node_publishing
node_publishing -->|"publishes assignments"| node_nats
node_event_handlers -->|"records completion"| node_task_manager
node_task_manager -->|"persists task state"| node_database
node_orchestrator -->|"starts scheduler"| node_scheduler
node_ui_schedule -.->|"manages schedules"| node_nats
node_orchestrator -->|"initializes manager"| node_help
node_worker_entry -->|"dispatches tasks"| node_worker
node_worker_entry -->|"dispatches tasks"| node_supervisor
node_worker_entry -->|"connects through client"| node_nats
node_supervisor -.->|"observes and controls"| node_desktop_access
node_ui_desktop -.->|"adds desktop"| node_orchestrator
node_orchestrator -->|"mounts streaming server"| node_guac
node_dashboard -.->|"views desktops"| node_guac
node_worker -.->|"uses browser automation"| node_patchright

click node_dashboard "https://github.com/scs-labrat/figaro/blob/main/figaro-ui/src/components/Dashboard.tsx"
click node_ui_state "https://github.com/scs-labrat/figaro/blob/main/figaro-ui/src/api/nats-broadcast-handler.ts"
click node_gateway "https://github.com/scs-labrat/figaro/blob/main/figaro-gateway/src/figaro_gateway/channels/telegram/bot.py"
click node_router "https://github.com/scs-labrat/figaro/blob/main/figaro-gateway/src/figaro_gateway/core/router.py"
click node_orchestrator "https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/app.py"
click node_task_api "https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/nats/api_tasks.py"
click node_task_manager "https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/task_manager.py"
click node_event_handlers "https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/nats/event_handlers.py"
click node_scheduler "https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/scheduler.py"
click node_help "https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/help_request.py"
click node_nats_service "https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/nats/service.py"
click node_publishing "https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/nats/publishing.py"
click node_nats "https://github.com/scs-labrat/figaro/blob/main/figaro-nats/src/figaro_nats/client.py"
click node_database "https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/db/models.py"
click node_ui_schedule "https://github.com/scs-labrat/figaro/blob/main/figaro-ui/src/components/ScheduleFormModal.tsx"
click node_ui_desktop "https://github.com/scs-labrat/figaro/blob/main/figaro-ui/src/components/AddDesktopWorkerForm.tsx"
click node_worker "https://github.com/scs-labrat/figaro/blob/main/figaro-worker/src/worker/executor.ts"
click node_supervisor "https://github.com/scs-labrat/figaro/blob/main/figaro-worker/src/supervisor/executor.ts"
click node_worker_entry "https://github.com/scs-labrat/figaro/blob/main/figaro-worker/src/index.ts"
click node_guac "https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/routes/guacamole.py"
click node_patchright "https://github.com/scs-labrat/figaro/blob/main/patchright-cli/src/patchright_cli/server.py"

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_dashboard,node_ui_state,node_gateway,node_router,node_ui_schedule,node_ui_desktop,node_user toneBlue
class node_orchestrator,node_task_api,node_task_manager,node_event_handlers,node_scheduler,node_help toneAmber
class node_worker,node_supervisor,node_worker_entry,node_patchright toneMint
class node_desktop_access,node_guac toneRose
class node_nats_service,node_publishing,node_nats,node_database toneIndigo
```

## Components

### User interfaces

- [Dashboard](https://github.com/scs-labrat/figaro/blob/main/figaro-ui/src/components/Dashboard.tsx): `figaro-ui/src/components/Dashboard.tsx`
- [Live UI state](https://github.com/scs-labrat/figaro/blob/main/figaro-ui/src/api/nats-broadcast-handler.ts): `figaro-ui/src/api/nats-broadcast-handler.ts`
- [Telegram gateway](https://github.com/scs-labrat/figaro/blob/main/figaro-gateway/src/figaro_gateway/channels/telegram/bot.py): `figaro-gateway/src/figaro_gateway/channels/telegram/bot.py`
- [Gateway router](https://github.com/scs-labrat/figaro/blob/main/figaro-gateway/src/figaro_gateway/core/router.py): `figaro-gateway/src/figaro_gateway/core/router.py`
- [Schedule controls](https://github.com/scs-labrat/figaro/blob/main/figaro-ui/src/components/ScheduleFormModal.tsx): `figaro-ui/src/components/ScheduleFormModal.tsx`
- [Desktop controls](https://github.com/scs-labrat/figaro/blob/main/figaro-ui/src/components/AddDesktopWorkerForm.tsx): `figaro-ui/src/components/AddDesktopWorkerForm.tsx`

### Orchestration

- [Orchestrator app](https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/app.py): `figaro/src/figaro/app.py`
- [Task routing](https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/nats/api_tasks.py): `figaro/src/figaro/services/nats/api_tasks.py`
- [Task lifecycle](https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/task_manager.py): `figaro/src/figaro/services/task_manager.py`
- [Event handling](https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/nats/event_handlers.py): `figaro/src/figaro/services/nats/event_handlers.py`
- [Scheduled work](https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/scheduler.py): `figaro/src/figaro/services/scheduler.py`
- [Help requests](https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/help_request.py): `figaro/src/figaro/services/help_request.py`

### Agent runtime

- [Worker agent](https://github.com/scs-labrat/figaro/blob/main/figaro-worker/src/worker/executor.ts): `figaro-worker/src/worker/executor.ts`
- [Supervisor agent](https://github.com/scs-labrat/figaro/blob/main/figaro-worker/src/supervisor/executor.ts): `figaro-worker/src/supervisor/executor.ts`
- [Agent entrypoint](https://github.com/scs-labrat/figaro/blob/main/figaro-worker/src/index.ts): `figaro-worker/src/index.ts`
- [Browser automation](https://github.com/scs-labrat/figaro/blob/main/patchright-cli/src/patchright_cli/server.py): `patchright-cli/src/patchright_cli/server.py`

### Desktop access

- **Remote desktop access**
- [Guacamole streaming](https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/routes/guacamole.py): `figaro/src/figaro/routes/guacamole.py`

### Messaging and state

- [NATS service](https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/nats/service.py): `figaro/src/figaro/services/nats/service.py`
- [Task publishing](https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/services/nats/publishing.py): `figaro/src/figaro/services/nats/publishing.py`
- [NATS messaging](https://github.com/scs-labrat/figaro/blob/main/figaro-nats/src/figaro_nats/client.py): `figaro-nats/src/figaro_nats/client.py`
- [PostgreSQL state](https://github.com/scs-labrat/figaro/blob/main/figaro/src/figaro/db/models.py): `figaro/src/figaro/db/models.py`

### Other components

- **User**

## Connections

- User → Dashboard: manages tasks
- Dashboard → Live UI state: renders updates (evidence: `figaro-ui/src/api/nats-broadcast-handler.ts`)
- Dashboard → NATS messaging: communicates via
- User → Telegram gateway: sends instructions
- Telegram gateway → Gateway router: routes messages
- Gateway router → NATS messaging: communicates via
- Orchestrator app → NATS service: starts service (evidence: `figaro/src/figaro/app.py`)
- NATS service → NATS messaging: connects and subscribes (evidence: `figaro/src/figaro/services/nats/service.py`)
- NATS service → Task routing: registers handlers (evidence: `figaro/src/figaro/services/nats/service.py`)
- NATS service → Event handling: registers handlers (evidence: `figaro/src/figaro/services/nats/service.py`)
- Task routing → Task lifecycle: creates and routes (evidence: `figaro/src/figaro/services/nats/api_tasks.py`)
- Task routing → Task publishing: requests assignment (evidence: `figaro/src/figaro/services/nats/api_tasks.py`)
- Task publishing → NATS messaging: publishes assignments (evidence: `figaro/src/figaro/services/nats/publishing.py`)
- Event handling → Task lifecycle: records completion (evidence: `figaro/src/figaro/services/nats/event_handlers.py`)
- Task lifecycle → PostgreSQL state: persists task state (evidence: `figaro/src/figaro/services/task_manager.py`)
- Orchestrator app → Scheduled work: starts scheduler (evidence: `figaro/src/figaro/app.py`)
- Schedule controls → NATS messaging: manages schedules
- Orchestrator app → Help requests: initializes manager (evidence: `figaro/src/figaro/app.py`)
- Agent entrypoint → Worker agent: dispatches tasks (evidence: `figaro-worker/src/index.ts`)
- Agent entrypoint → Supervisor agent: dispatches tasks (evidence: `figaro-worker/src/index.ts`)
- Agent entrypoint → NATS messaging: connects through client (evidence: `figaro-worker/src/index.ts`)
- Supervisor agent → Remote desktop access: observes and controls
- Desktop controls → Orchestrator app: adds desktop
- Orchestrator app → Guacamole streaming: mounts streaming server (evidence: `figaro/src/figaro/app.py`)
- Dashboard → Guacamole streaming: views desktops
- Worker agent → Browser automation: uses browser automation
