# linyeping/metis architecture

> Architecture diagram of the GitHub repository linyeping/metis, 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/linyeping/metis
- Repository: https://github.com/linyeping/metis

## Overview

Metis is a local AI workbench for Chat, Cowork, Code, and Design. The main task flow is to establish project and session context, run an agent task through model and tool integrations, review changes, verify outcomes, and retain results for recovery. The desktop renderer and Python Flask/SSE backend form the primary interface and execution layers; runtime management and the separate Design surface support additional workflows. Some subsystems are represented from README capabilities and the file tree rather than inspected implementation, so uncertain connections are omitted or marked unverified.

Main entry points: [`backend/runtime/agent_loop.py`](https://github.com/linyeping/metis/blob/main/backend/runtime/agent_loop.py) (Agent Loop), [`desktop/src/App.tsx`](https://github.com/linyeping/metis/blob/main/desktop/src/App.tsx) (Workbench App), [`backend/web/session_routes.py`](https://github.com/linyeping/metis/blob/main/backend/web/session_routes.py) (Session Routes), [`desktop/src/lib/api.ts`](https://github.com/linyeping/metis/blob/main/desktop/src/lib/api.ts) (HTTP API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Workbench"]
  node_app["Workbench App<br/>[App.tsx]"]
  node_api["HTTP API Client<br/>[api.ts]"]
  node_runs["Run State<br/>[runManager.ts]"]
  node_electron["Desktop Host<br/>[main.cjs]"]
end

subgraph group_backend["Agent Backend"]
  node_webapp["Flask API<br/>[app.py]"]
  node_sessions["Session Routes<br/>[session_routes.py]"]
  node_sessiondata[("Session Workspace<br/>[sessions.py]")]
  node_agentservices["Agent Services<br/>[agent_services.py]"]
  node_agentloop["Agent Loop<br/>[agent_loop.py]"]
  node_cowork["Cowork Coordinator"]
  node_model["Model Backends<br/>[_common.py]"]
  node_workspace["Workspace Routes"]
end

subgraph group_execution["Execution and Tools"]
  node_toolregistry["Tool Registry<br/>[tool_registry.py]"]
  node_toolsets["Agent Tools<br/>[registry.py]"]
  node_permissions["Permission Control"]
  node_worktrees["Worktree Manager"]
  node_runtime["Runtime Manager<br/>[runtime_manager.py]"]
  node_connectors["Connectors and MCP<br/>[manager.py]"]
end

subgraph group_design["Design Surface"]
  node_designui["Design Studio<br/>[DesignSurface.tsx]"]
  node_designhost["Design Runtime Host"]
  node_designroutes["Design Project Routes"]
  node_designstorage[("Project Storage<br/>[project-storage.ts]")]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"requests"| node_api
node_app -->|"renders"| node_designui
node_app -.->|"connects through"| node_electron
node_api -.->|"HTTP and SSE"| node_webapp
node_api -.->|"updates"| node_runs
node_webapp -.->|"routes"| node_sessions
node_sessions -->|"uses"| node_sessiondata
node_sessions -->|"invokes"| node_agentservices
node_agentservices -.->|"runs"| node_agentloop
node_agentloop -.->|"queries"| node_model
node_agentloop -.->|"dispatches"| node_toolregistry
node_toolregistry -.->|"registers"| node_toolsets
node_agentloop -.->|"checks"| node_permissions
node_sessions -.->|"coordinates"| node_cowork
node_workspace -->|"coordinates"| node_cowork
node_workspace -->|"manages"| node_worktrees
node_agentloop -.->|"uses"| node_connectors
node_agentloop -.->|"uses"| node_runtime
node_designui -.->|"previews through"| node_designhost
node_designhost -.->|"serves"| node_designroutes
node_designroutes -.->|"persists"| node_designstorage

click node_app "https://github.com/linyeping/metis/blob/main/desktop/src/App.tsx"
click node_api "https://github.com/linyeping/metis/blob/main/desktop/src/lib/api.ts"
click node_runs "https://github.com/linyeping/metis/blob/main/desktop/src/store/runManager.ts"
click node_electron "https://github.com/linyeping/metis/blob/main/desktop/electron/main.cjs"
click node_webapp "https://github.com/linyeping/metis/blob/main/backend/web/app.py"
click node_sessions "https://github.com/linyeping/metis/blob/main/backend/web/session_routes.py"
click node_sessiondata "https://github.com/linyeping/metis/blob/main/backend/web/sessions.py"
click node_agentservices "https://github.com/linyeping/metis/blob/main/backend/runtime/agent_services.py"
click node_agentloop "https://github.com/linyeping/metis/blob/main/backend/runtime/agent_loop.py"
click node_cowork "https://github.com/linyeping/metis/blob/main/backend/runtime/cowork_coordinator.py"
click node_model "https://github.com/linyeping/metis/blob/main/backend/runtime/llm_backends/_common.py"
click node_toolregistry "https://github.com/linyeping/metis/blob/main/backend/runtime/tool_registry.py"
click node_toolsets "https://github.com/linyeping/metis/blob/main/backend/tools/registry.py"
click node_permissions "https://github.com/linyeping/metis/blob/main/backend/runtime/permission_control.py"
click node_worktrees "https://github.com/linyeping/metis/blob/main/backend/runtime/worktree_manager.py"
click node_runtime "https://github.com/linyeping/metis/blob/main/backend/runtime/runtime_manager.py"
click node_connectors "https://github.com/linyeping/metis/blob/main/backend/runtime/connectors/manager.py"
click node_workspace "https://github.com/linyeping/metis/blob/main/backend/web/workspace_routes.py"
click node_designui "https://github.com/linyeping/metis/blob/main/desktop/src/components/design/DesignSurface.tsx"
click node_designhost "https://github.com/linyeping/metis/blob/main/desktop/electron/design-renderer-service.cjs"
click node_designroutes "https://github.com/linyeping/metis/blob/main/open-design/apps/daemon/src/import-export-routes.ts"
click node_designstorage "https://github.com/linyeping/metis/blob/main/open-design/apps/daemon/src/storage/project-storage.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_app,node_api,node_runs,node_electron,node_user toneBlue
class node_webapp,node_sessions,node_sessiondata,node_agentservices,node_agentloop,node_cowork,node_model,node_workspace toneAmber
class node_toolregistry,node_toolsets,node_permissions,node_worktrees,node_runtime,node_connectors toneMint
class node_designui,node_designhost,node_designroutes,node_designstorage toneRose
```

## Components

### Desktop Workbench

- [Workbench App](https://github.com/linyeping/metis/blob/main/desktop/src/App.tsx): `desktop/src/App.tsx`
- [HTTP API Client](https://github.com/linyeping/metis/blob/main/desktop/src/lib/api.ts): `desktop/src/lib/api.ts`
- [Run State](https://github.com/linyeping/metis/blob/main/desktop/src/store/runManager.ts): `desktop/src/store/runManager.ts`
- [Desktop Host](https://github.com/linyeping/metis/blob/main/desktop/electron/main.cjs): `desktop/electron/main.cjs`

### Agent Backend

- [Flask API](https://github.com/linyeping/metis/blob/main/backend/web/app.py): `backend/web/app.py`
- [Session Routes](https://github.com/linyeping/metis/blob/main/backend/web/session_routes.py): `backend/web/session_routes.py`
- [Session Workspace](https://github.com/linyeping/metis/blob/main/backend/web/sessions.py): `backend/web/sessions.py`
- [Agent Services](https://github.com/linyeping/metis/blob/main/backend/runtime/agent_services.py): `backend/runtime/agent_services.py`
- [Agent Loop](https://github.com/linyeping/metis/blob/main/backend/runtime/agent_loop.py): `backend/runtime/agent_loop.py`
- [Cowork Coordinator](https://github.com/linyeping/metis/blob/main/backend/runtime/cowork_coordinator.py): `backend/runtime/cowork_coordinator.py`
- [Model Backends](https://github.com/linyeping/metis/blob/main/backend/runtime/llm_backends/_common.py): `backend/runtime/llm_backends/_common.py`
- [Workspace Routes](https://github.com/linyeping/metis/blob/main/backend/web/workspace_routes.py): `backend/web/workspace_routes.py`

### Execution and Tools

- [Tool Registry](https://github.com/linyeping/metis/blob/main/backend/runtime/tool_registry.py): `backend/runtime/tool_registry.py`
- [Agent Tools](https://github.com/linyeping/metis/blob/main/backend/tools/registry.py): `backend/tools/registry.py`
- [Permission Control](https://github.com/linyeping/metis/blob/main/backend/runtime/permission_control.py): `backend/runtime/permission_control.py`
- [Worktree Manager](https://github.com/linyeping/metis/blob/main/backend/runtime/worktree_manager.py): `backend/runtime/worktree_manager.py`
- [Runtime Manager](https://github.com/linyeping/metis/blob/main/backend/runtime/runtime_manager.py): `backend/runtime/runtime_manager.py`
- [Connectors and MCP](https://github.com/linyeping/metis/blob/main/backend/runtime/connectors/manager.py): `backend/runtime/connectors/manager.py`

### Design Surface

- [Design Studio](https://github.com/linyeping/metis/blob/main/desktop/src/components/design/DesignSurface.tsx): `desktop/src/components/design/DesignSurface.tsx`
- [Design Runtime Host](https://github.com/linyeping/metis/blob/main/desktop/electron/design-renderer-service.cjs): `desktop/electron/design-renderer-service.cjs`
- [Design Project Routes](https://github.com/linyeping/metis/blob/main/open-design/apps/daemon/src/import-export-routes.ts): `open-design/apps/daemon/src/import-export-routes.ts`
- [Project Storage](https://github.com/linyeping/metis/blob/main/open-design/apps/daemon/src/storage/project-storage.ts): `open-design/apps/daemon/src/storage/project-storage.ts`

### Other components

- **User**

## Connections

- User → Workbench App: uses (evidence: `README.md`)
- Workbench App → HTTP API Client: requests (evidence: `desktop/src/App.tsx`)
- Workbench App → Design Studio: renders (evidence: `desktop/src/App.tsx`)
- Workbench App → Desktop Host: connects through
- HTTP API Client → Flask API: HTTP and SSE
- HTTP API Client → Run State: updates
- Flask API → Session Routes: routes
- Session Routes → Session Workspace: uses (evidence: `backend/web/sessions.py`)
- Session Routes → Agent Services: invokes (evidence: `backend/web/session_routes.py`)
- Agent Services → Agent Loop: runs
- Agent Loop → Model Backends: queries
- Agent Loop → Tool Registry: dispatches
- Tool Registry → Agent Tools: registers
- Agent Loop → Permission Control: checks
- Session Routes → Cowork Coordinator: coordinates
- Workspace Routes → Cowork Coordinator: coordinates (evidence: `backend/web/workspace_routes.py`)
- Workspace Routes → Worktree Manager: manages (evidence: `backend/web/workspace_routes.py`)
- Agent Loop → Connectors and MCP: uses
- Agent Loop → Runtime Manager: uses
- Design Studio → Design Runtime Host: previews through
- Design Runtime Host → Design Project Routes: serves
- Design Project Routes → Project Storage: persists
