# usefulsoftwareco/executor architecture

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

- Interactive diagram: https://gitdiagram.com/usefulsoftwareco/executor
- Repository: https://github.com/usefulsoftwareco/executor

## Overview

Executor provides a shared, policy-governed integration catalog that agents access over MCP. The principal workflow is to configure an integration, create an authenticated connection, set tool policies, then discover and invoke tools; executions may pause for approval and resume. The monorepo packages that functionality for local, desktop, cloud, and self-hosted deployments. Relationships below follow explicit README statements and the shown composition excerpts; unsampled subsystems are included where documented, but their internal call paths are not inferred.

Main entry points: [`packages/core/api/src/server/executor-app.ts`](https://github.com/usefulsoftwareco/executor/blob/main/packages/core/api/src/server/executor-app.ts) (Executor API), [`packages/core/execution/src/engine.ts`](https://github.com/usefulsoftwareco/executor/blob/main/packages/core/execution/src/engine.ts) (Execution engine), [`apps/local/src/app.ts`](https://github.com/usefulsoftwareco/executor/blob/main/apps/local/src/app.ts) (Local API runtime), [`packages/core/sdk/src/connection.ts`](https://github.com/usefulsoftwareco/executor/blob/main/packages/core/sdk/src/connection.ts) (Connections and auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Agent and UI"]
  node_console["Web console<br/>[console-routes.ts]"]
  node_cli["Executor CLI<br/>[main.ts]"]
end

subgraph group_domain["Integration and execution"]
  node_integrations["Integration plugins<br/>[handlers.ts]"]
  node_mcpplugin["MCP integration<br/>[handlers.ts]"]
  node_connections["Connections and auth<br/>[connection.ts]"]
  node_policies["Tool policies<br/>[policies.ts]"]
  node_catalog["Tool catalog<br/>[api.ts]"]
  node_engine["Execution engine<br/>[engine.ts]"]
  node_invoker["Tool invoker<br/>[tool-invoker.ts]"]
  node_approval["Approval and resume<br/>[engine.ts]"]
end

subgraph group_shared["Shared platform"]
  node_sdk["TypeScript SDK<br/>[client.ts]"]
  node_api["Executor API<br/>[executor-app.ts]"]
end

subgraph group_local["Local runtime"]
  node_localapp["Local API runtime<br/>[app.ts]"]
  node_localengine["Local MCP runtime<br/>[main.ts]"]
  node_localdb[("Local database<br/>[owned-database.ts]")]
  node_daemon["Local daemon<br/>[daemon.ts]"]
  node_desktop["Desktop app<br/>[index.ts]"]
end

subgraph group_hosting["Hosted runtimes"]
  node_cloud["Executor Cloud<br/>[app.ts]"]
  node_selfhost["Self-host server<br/>[app.ts]"]
  node_cfhost["Cloudflare host<br/>[app.ts]"]
end

node_agent(("MCP agent"))

node_console -->|"manages catalog"| node_api
node_cli -->|"calls tools"| node_api
node_sdk -->|"configures and invokes"| node_api
node_api -.->|"loads plugins"| node_integrations
node_api -.->|"loads plugins"| node_mcpplugin
node_integrations -->|"defines integration instances"| node_connections
node_mcpplugin -->|"defines integration instances"| node_connections
node_console -->|"creates connections"| node_connections
node_connections -->|"provides tools"| node_catalog
node_console -->|"sets policies"| node_policies
node_catalog -->|"exposes tools over MCP"| node_agent
node_agent -->|"invokes tools"| node_engine
node_engine -->|"dispatches execution"| node_invoker
node_engine -->|"pauses and resumes"| node_approval
node_cli -->|"starts daemon"| node_daemon
node_daemon -.->|"serves locally"| node_localapp
node_localapp -->|"boots MCP runtime"| node_localengine
node_localengine -->|"creates engine"| node_engine
node_desktop -->|"packages same runtime"| node_localapp
node_localapp -.->|"uses local data store"| node_localdb
node_cloud -.->|"hosts API"| node_api
node_selfhost -.->|"hosts API"| node_api
node_cfhost -->|"hosts API"| node_api
node_agent -->|"connects over MCP"| node_cloud
node_agent -->|"connects over MCP"| node_selfhost
node_agent -->|"connects over MCP"| node_cfhost

click node_console "https://github.com/usefulsoftwareco/executor/blob/main/packages/react/src/console-routes.ts"
click node_cli "https://github.com/usefulsoftwareco/executor/blob/main/apps/cli/src/main.ts"
click node_sdk "https://github.com/usefulsoftwareco/executor/blob/main/packages/core/sdk/src/client.ts"
click node_api "https://github.com/usefulsoftwareco/executor/blob/main/packages/core/api/src/server/executor-app.ts"
click node_integrations "https://github.com/usefulsoftwareco/executor/blob/main/packages/plugins/openapi/src/api/handlers.ts"
click node_mcpplugin "https://github.com/usefulsoftwareco/executor/blob/main/packages/plugins/mcp/src/api/handlers.ts"
click node_connections "https://github.com/usefulsoftwareco/executor/blob/main/packages/core/sdk/src/connection.ts"
click node_policies "https://github.com/usefulsoftwareco/executor/blob/main/packages/core/sdk/src/policies.ts"
click node_catalog "https://github.com/usefulsoftwareco/executor/blob/main/packages/core/api/src/tools/api.ts"
click node_engine "https://github.com/usefulsoftwareco/executor/blob/main/packages/core/execution/src/engine.ts"
click node_invoker "https://github.com/usefulsoftwareco/executor/blob/main/packages/core/execution/src/tool-invoker.ts"
click node_localapp "https://github.com/usefulsoftwareco/executor/blob/main/apps/local/src/app.ts"
click node_localengine "https://github.com/usefulsoftwareco/executor/blob/main/apps/local/src/main.ts"
click node_localdb "https://github.com/usefulsoftwareco/executor/blob/main/apps/local/src/db/owned-database.ts"
click node_daemon "https://github.com/usefulsoftwareco/executor/blob/main/apps/cli/src/daemon.ts"
click node_desktop "https://github.com/usefulsoftwareco/executor/blob/main/apps/desktop/src/main/index.ts"
click node_cloud "https://github.com/usefulsoftwareco/executor/blob/main/apps/cloud/src/app.ts"
click node_selfhost "https://github.com/usefulsoftwareco/executor/blob/main/apps/host-selfhost/src/app.ts"
click node_cfhost "https://github.com/usefulsoftwareco/executor/blob/main/apps/host-cloudflare/src/app.ts"
click node_approval "https://github.com/usefulsoftwareco/executor/blob/main/packages/core/execution/src/engine.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_console,node_cli toneBlue
class node_integrations,node_mcpplugin,node_connections,node_policies,node_catalog,node_engine,node_invoker,node_approval toneAmber
class node_sdk,node_api toneMint
class node_localapp,node_localengine,node_localdb,node_daemon,node_desktop toneRose
class node_cloud,node_selfhost,node_cfhost,node_agent toneIndigo
```

## Components

### Agent and UI

- [Web console](https://github.com/usefulsoftwareco/executor/blob/main/packages/react/src/console-routes.ts): `packages/react/src/console-routes.ts`
- [Executor CLI](https://github.com/usefulsoftwareco/executor/blob/main/apps/cli/src/main.ts): `apps/cli/src/main.ts`

### Integration and execution

- [Integration plugins](https://github.com/usefulsoftwareco/executor/blob/main/packages/plugins/openapi/src/api/handlers.ts): `packages/plugins/openapi/src/api/handlers.ts`
- [MCP integration](https://github.com/usefulsoftwareco/executor/blob/main/packages/plugins/mcp/src/api/handlers.ts): `packages/plugins/mcp/src/api/handlers.ts`
- [Connections and auth](https://github.com/usefulsoftwareco/executor/blob/main/packages/core/sdk/src/connection.ts): `packages/core/sdk/src/connection.ts`
- [Tool policies](https://github.com/usefulsoftwareco/executor/blob/main/packages/core/sdk/src/policies.ts): `packages/core/sdk/src/policies.ts`
- [Tool catalog](https://github.com/usefulsoftwareco/executor/blob/main/packages/core/api/src/tools/api.ts): `packages/core/api/src/tools/api.ts`
- [Execution engine](https://github.com/usefulsoftwareco/executor/blob/main/packages/core/execution/src/engine.ts): `packages/core/execution/src/engine.ts`
- [Tool invoker](https://github.com/usefulsoftwareco/executor/blob/main/packages/core/execution/src/tool-invoker.ts): `packages/core/execution/src/tool-invoker.ts`
- [Approval and resume](https://github.com/usefulsoftwareco/executor/blob/main/packages/core/execution/src/engine.ts): `packages/core/execution/src/engine.ts`

### Shared platform

- [TypeScript SDK](https://github.com/usefulsoftwareco/executor/blob/main/packages/core/sdk/src/client.ts): `packages/core/sdk/src/client.ts`
- [Executor API](https://github.com/usefulsoftwareco/executor/blob/main/packages/core/api/src/server/executor-app.ts): `packages/core/api/src/server/executor-app.ts`

### Local runtime

- [Local API runtime](https://github.com/usefulsoftwareco/executor/blob/main/apps/local/src/app.ts): `apps/local/src/app.ts`
- [Local MCP runtime](https://github.com/usefulsoftwareco/executor/blob/main/apps/local/src/main.ts): `apps/local/src/main.ts`
- [Local database](https://github.com/usefulsoftwareco/executor/blob/main/apps/local/src/db/owned-database.ts): `apps/local/src/db/owned-database.ts`
- [Local daemon](https://github.com/usefulsoftwareco/executor/blob/main/apps/cli/src/daemon.ts): `apps/cli/src/daemon.ts`
- [Desktop app](https://github.com/usefulsoftwareco/executor/blob/main/apps/desktop/src/main/index.ts): `apps/desktop/src/main/index.ts`

### Hosted runtimes

- [Executor Cloud](https://github.com/usefulsoftwareco/executor/blob/main/apps/cloud/src/app.ts): `apps/cloud/src/app.ts`
- [Self-host server](https://github.com/usefulsoftwareco/executor/blob/main/apps/host-selfhost/src/app.ts): `apps/host-selfhost/src/app.ts`
- [Cloudflare host](https://github.com/usefulsoftwareco/executor/blob/main/apps/host-cloudflare/src/app.ts): `apps/host-cloudflare/src/app.ts`

### Other components

- **MCP agent**

## Connections

- Web console → Executor API: manages catalog (evidence: `README.md`)
- Executor CLI → Executor API: calls tools (evidence: `README.md`)
- TypeScript SDK → Executor API: configures and invokes (evidence: `README.md`)
- Executor API → Integration plugins: loads plugins
- Executor API → MCP integration: loads plugins
- Integration plugins → Connections and auth: defines integration instances (evidence: `README.md`)
- MCP integration → Connections and auth: defines integration instances (evidence: `README.md`)
- Web console → Connections and auth: creates connections (evidence: `README.md`)
- Connections and auth → Tool catalog: provides tools (evidence: `README.md`)
- Web console → Tool policies: sets policies (evidence: `README.md`)
- Tool catalog → MCP agent: exposes tools over MCP (evidence: `README.md`)
- MCP agent → Execution engine: invokes tools (evidence: `README.md`)
- Execution engine → Tool invoker: dispatches execution (evidence: `packages/core/execution/src/engine.ts`)
- Execution engine → Approval and resume: pauses and resumes (evidence: `packages/core/execution/src/engine.ts`)
- Executor CLI → Local daemon: starts daemon (evidence: `README.md`)
- Local daemon → Local API runtime: serves locally
- Local API runtime → Local MCP runtime: boots MCP runtime (evidence: `apps/local/src/main.ts`)
- Local MCP runtime → Execution engine: creates engine (evidence: `apps/local/src/main.ts`)
- Desktop app → Local API runtime: packages same runtime (evidence: `README.md`)
- Local API runtime → Local database: uses local data store
- Executor Cloud → Executor API: hosts API
- Self-host server → Executor API: hosts API
- Cloudflare host → Executor API: hosts API (evidence: `apps/host-cloudflare/src/app.ts`)
- MCP agent → Executor Cloud: connects over MCP (evidence: `README.md`)
- MCP agent → Self-host server: connects over MCP (evidence: `README.md`)
- MCP agent → Cloudflare host: connects over MCP (evidence: `README.md`)
