# dassiorleando/openworker architecture

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

- Interactive diagram: https://gitdiagram.com/dassiorleando/openworker
- Repository: https://github.com/dassiorleando/openworker

## Overview

OpenWorker is a local-first desktop AI coworker: a user chooses a specialist, gives it a task, and receives a deliverable through a governed agent loop. The documented workflow spans model selection, tool use across local files and connected services, approval, and transcript-backed results. The graph includes the server and GUI surfaces, runtime orchestration, governance, integrations, and documented scheduling, teams, and sandbox capabilities. Several subsystem links are README-documented rather than verified in sampled implementation; those are marked dashed.

Main entry points: [`coworker/engine.py`](https://github.com/dassiorleando/openworker/blob/main/coworker/engine.py) (Turn engine), [`coworker/server/manager.py`](https://github.com/dassiorleando/openworker/blob/main/coworker/server/manager.py) (Session manager), [`coworker/tools/registry.py`](https://github.com/dassiorleando/openworker/blob/main/coworker/tools/registry.py) (Built-in tools), [`surfaces/gui/src/App.tsx`](https://github.com/dassiorleando/openworker/blob/main/surfaces/gui/src/App.tsx) (Desktop GUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surface["User surfaces"]
  node_desktop["Desktop GUI<br/>[App.tsx]"]
  node_api["Server API<br/>[app.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_manager["Session manager<br/>[manager.py]"]
  node_persona["Personas<br/>[registry.py]"]
  node_agent["Agent setup<br/>[agent.py]"]
  node_engine["Turn engine<br/>[engine.py]"]
  node_providers["Model providers<br/>[router.py]"]
end

subgraph group_governance["Governance and state"]
  node_permissions["Permission engine<br/>[permissions.py]"]
  node_reviewer["Auto-approve reviewer<br/>[reviewer.py]"]
  node_audit[("Audit trail<br/>[audit.py]")]
  node_sessions[("Conversations<br/>[conversations.py]")]
end

subgraph group_integrations["Tools and integrations"]
  node_tools["Built-in tools<br/>[registry.py]"]
  node_connectors["App integrations"]
  node_mcp["MCP connections<br/>[client.py]"]
  node_sandbox["Command sandbox<br/>[client.py]"]
end

subgraph group_capabilities["Extended capabilities"]
  node_inbox[("Unattended inbox<br/>[inbox.py]")]
  node_automations["Scheduled automations<br/>[scheduler.py]"]
  node_teams[("Teams<br/>[store.py]")]
  node_slack["Messaging connectors<br/>[relay_client.py]"]
end

node_user(("User"))
node_localfiles[("Local files")]
node_externalapps["Connected apps"]
node_modelservice["Model service"]
node_deliverable["Finished work"]

node_user -->|"requests work"| node_desktop
node_desktop -.->|"uses API"| node_api
node_api -->|"routes requests"| node_manager
node_manager -->|"resolves persona"| node_persona
node_manager -->|"builds agent"| node_agent
node_agent -->|"creates loop"| node_engine
node_engine -->|"requests completion"| node_providers
node_engine -->|"checks actions"| node_permissions
node_engine -->|"consults reviewer"| node_reviewer
node_engine -->|"dispatches calls"| node_tools
node_engine -.->|"persists conversation"| node_sessions
node_engine -.->|"records actions"| node_audit
node_providers -->|"calls model"| node_modelservice
node_tools -.->|"works on files"| node_localfiles
node_tools -.->|"runs commands"| node_sandbox
node_engine -.->|"uses integrations"| node_connectors
node_engine -.->|"uses MCP tools"| node_mcp
node_connectors -.->|"accesses services"| node_externalapps
node_engine -.->|"produces result"| node_deliverable
node_manager -->|"routes unattended asks"| node_inbox
node_manager -.->|"supports schedules"| node_automations
node_manager -->|"manages teams"| node_teams
node_manager -.->|"supports messaging"| node_slack

click node_desktop "https://github.com/dassiorleando/openworker/blob/main/surfaces/gui/src/App.tsx"
click node_api "https://github.com/dassiorleando/openworker/blob/main/coworker/server/app.py"
click node_manager "https://github.com/dassiorleando/openworker/blob/main/coworker/server/manager.py"
click node_persona "https://github.com/dassiorleando/openworker/blob/main/coworker/personas/registry.py"
click node_agent "https://github.com/dassiorleando/openworker/blob/main/coworker/agent.py"
click node_engine "https://github.com/dassiorleando/openworker/blob/main/coworker/engine.py"
click node_providers "https://github.com/dassiorleando/openworker/blob/main/coworker/providers/router.py"
click node_permissions "https://github.com/dassiorleando/openworker/blob/main/coworker/permissions.py"
click node_reviewer "https://github.com/dassiorleando/openworker/blob/main/coworker/reviewer.py"
click node_audit "https://github.com/dassiorleando/openworker/blob/main/coworker/audit.py"
click node_sessions "https://github.com/dassiorleando/openworker/blob/main/coworker/conversations.py"
click node_tools "https://github.com/dassiorleando/openworker/blob/main/coworker/tools/registry.py"
click node_connectors "https://github.com/dassiorleando/openworker/blob/main/coworker/connectors/integration_tools.py"
click node_mcp "https://github.com/dassiorleando/openworker/blob/main/coworker/mcp/client.py"
click node_sandbox "https://github.com/dassiorleando/openworker/blob/main/coworker/sandbox/client.py"
click node_inbox "https://github.com/dassiorleando/openworker/blob/main/coworker/inbox.py"
click node_automations "https://github.com/dassiorleando/openworker/blob/main/coworker/automation/scheduler.py"
click node_teams "https://github.com/dassiorleando/openworker/blob/main/coworker/teams/store.py"
click node_slack "https://github.com/dassiorleando/openworker/blob/main/coworker/connectors/relay_client.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_desktop,node_api,node_user toneBlue
class node_manager,node_persona,node_agent,node_engine,node_providers,node_localfiles toneAmber
class node_permissions,node_reviewer,node_audit,node_sessions toneMint
class node_tools,node_connectors,node_mcp,node_sandbox toneRose
class node_inbox,node_automations,node_teams,node_slack,node_externalapps,node_modelservice,node_deliverable toneIndigo
```

## Components

### User surfaces

- [Desktop GUI](https://github.com/dassiorleando/openworker/blob/main/surfaces/gui/src/App.tsx): `surfaces/gui/src/App.tsx`
- [Server API](https://github.com/dassiorleando/openworker/blob/main/coworker/server/app.py): `coworker/server/app.py`

### Agent runtime

- [Session manager](https://github.com/dassiorleando/openworker/blob/main/coworker/server/manager.py): `coworker/server/manager.py`
- [Personas](https://github.com/dassiorleando/openworker/blob/main/coworker/personas/registry.py): `coworker/personas/registry.py`
- [Agent setup](https://github.com/dassiorleando/openworker/blob/main/coworker/agent.py): `coworker/agent.py`
- [Turn engine](https://github.com/dassiorleando/openworker/blob/main/coworker/engine.py): `coworker/engine.py`
- [Model providers](https://github.com/dassiorleando/openworker/blob/main/coworker/providers/router.py): `coworker/providers/router.py`

### Governance and state

- [Permission engine](https://github.com/dassiorleando/openworker/blob/main/coworker/permissions.py): `coworker/permissions.py`
- [Auto-approve reviewer](https://github.com/dassiorleando/openworker/blob/main/coworker/reviewer.py): `coworker/reviewer.py`
- [Audit trail](https://github.com/dassiorleando/openworker/blob/main/coworker/audit.py): `coworker/audit.py`
- [Conversations](https://github.com/dassiorleando/openworker/blob/main/coworker/conversations.py): `coworker/conversations.py`

### Tools and integrations

- [Built-in tools](https://github.com/dassiorleando/openworker/blob/main/coworker/tools/registry.py): `coworker/tools/registry.py`
- [App integrations](https://github.com/dassiorleando/openworker/blob/main/coworker/connectors/integration_tools.py): `coworker/connectors/integration_tools.py`
- [MCP connections](https://github.com/dassiorleando/openworker/blob/main/coworker/mcp/client.py): `coworker/mcp/client.py`
- [Command sandbox](https://github.com/dassiorleando/openworker/blob/main/coworker/sandbox/client.py): `coworker/sandbox/client.py`

### Extended capabilities

- [Unattended inbox](https://github.com/dassiorleando/openworker/blob/main/coworker/inbox.py): `coworker/inbox.py`
- [Scheduled automations](https://github.com/dassiorleando/openworker/blob/main/coworker/automation/scheduler.py): `coworker/automation/scheduler.py`
- [Teams](https://github.com/dassiorleando/openworker/blob/main/coworker/teams/store.py): `coworker/teams/store.py`
- [Messaging connectors](https://github.com/dassiorleando/openworker/blob/main/coworker/connectors/relay_client.py): `coworker/connectors/relay_client.py`

### Other components

- **User**
- **Local files**
- **Connected apps**
- **Model service**
- **Finished work**

## Connections

- User → Desktop GUI: requests work
- Desktop GUI → Server API: uses API
- Server API → Session manager: routes requests (evidence: `coworker/server/app.py`)
- Session manager → Personas: resolves persona (evidence: `coworker/server/manager.py`)
- Session manager → Agent setup: builds agent (evidence: `coworker/agent.py`)
- Agent setup → Turn engine: creates loop (evidence: `coworker/agent.py`)
- Turn engine → Model providers: requests completion (evidence: `coworker/engine.py`)
- Turn engine → Permission engine: checks actions (evidence: `coworker/engine.py`)
- Turn engine → Auto-approve reviewer: consults reviewer (evidence: `coworker/engine.py`)
- Turn engine → Built-in tools: dispatches calls (evidence: `coworker/engine.py`)
- Turn engine → Conversations: persists conversation
- Turn engine → Audit trail: records actions
- Model providers → Model service: calls model (evidence: `coworker/providers/router.py`)
- Built-in tools → Local files: works on files
- Built-in tools → Command sandbox: runs commands
- Turn engine → App integrations: uses integrations
- Turn engine → MCP connections: uses MCP tools
- App integrations → Connected apps: accesses services
- Turn engine → Finished work: produces result
- Session manager → Unattended inbox: routes unattended asks (evidence: `coworker/server/manager.py`)
- Session manager → Scheduled automations: supports schedules
- Session manager → Teams: manages teams (evidence: `coworker/server/manager.py`)
- Session manager → Messaging connectors: supports messaging
