# anil-matcha/suparagent architecture

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

- Interactive diagram: https://gitdiagram.com/anil-matcha/suparagent
- Repository: https://github.com/anil-matcha/suparagent

## Overview

Suparagent is a workspace for AI coworkers: users configure agents and an engine, chat to delegate work, review gated actions, and use the resulting conversations and workspace files. The desktop shell can start the backend; the browser and phone clients provide additional ways to use the server. Major documented capabilities also include teams, memory, routines, connected apps, computers, tasks, skills, and templates. The graph combines README-described product flows with sampled engine and client evidence; unsampled subsystems are represented by their existing directories, and uncertain wiring is omitted.

Main entry points: [`backend/app/services/thread_runtime.py`](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/thread_runtime.py) (Thread runtime), [`backend/app/services/acp_adapter.py`](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/acp_adapter.py) (Engine adapters), [`backend/app/routers/agents.py`](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/routers/agents.py) (Agents and teams), [`backend/app/services/routine_service.py`](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/routine_service.py) (Routines)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients and access"]
  node_desktop["Desktop shell<br/>[main.js]"]
  node_web["Web workspace<br/>[page.tsx]"]
  node_mobile["Phone app<br/>[&#91;id&#93;.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_engine_settings["Engine settings<br/>[EngineSettings.tsx]"]
end

subgraph group_conversation["Agent conversations"]
  node_thread_runtime["Thread runtime<br/>[thread_runtime.py]"]
  node_engine_adapters["Engine adapters<br/>[acp_adapter.py]"]
end

subgraph group_operations["Work coordination"]
  node_agent_management["Agents and teams<br/>[agents.py]"]
  node_memory["Agent memory<br/>[memory_bridge.py]"]
  node_approvals["Approvals"]
  node_computers["Agent computers<br/>[service.py]"]
  node_routines["Routines<br/>[routine_service.py]"]
  node_work_planning["Tasks and planning<br/>[work_planner.py]"]
  node_connected_apps["Connected apps"]
  node_skills_templates["Skills and templates<br/>[agent_skills.py]"]
  node_workspace_files["Workspace files<br/>[workspace_files.py]"]
end

subgraph group_runtime["Runtime and state"]
  node_auth["Request authentication<br/>[middleware.py]"]
  node_engine_routes["Engine API<br/>[engines.py]"]
  node_registry["Engine registry<br/>[engine_registry.py]"]
  node_thread_store[("Conversation history<br/>[thread_store.py]")]
  node_database[("Application database<br/>[engine.py]")]
end

node_user(("User"))

node_user -->|"opens workspace"| node_desktop
node_user -->|"starts chat"| node_web
node_user -->|"pairs phone"| node_mobile
node_engine_settings -->|"loads and saves"| node_api_client
node_engine_routes -->|"reads adapters"| node_registry
node_engine_adapters -->|"reads history"| node_thread_store
node_engine_adapters -->|"uses memory bridge"| node_memory
node_engine_adapters -->|"uses approval broker"| node_approvals
node_user -->|"creates agents"| node_agent_management
node_user -->|"reviews actions"| node_approvals
node_user -->|"schedules runs"| node_routines
node_user -->|"plans tasks"| node_work_planning
node_user -->|"connects tools"| node_connected_apps
node_user -->|"reuses instructions"| node_skills_templates
node_user -->|"browses files"| node_workspace_files
node_agent_management -.->|"delegates work"| node_thread_runtime
node_thread_runtime -.->|"runs turns"| node_engine_adapters
node_thread_runtime -.->|"persists conversations"| node_thread_store
node_thread_runtime -.->|"uses computer tools"| node_computers
node_routines -.->|"starts runs"| node_thread_runtime
node_agent_management -.->|"stores agent state"| node_database

click node_desktop "https://github.com/Anil-matcha/suparagent/blob/main/desktop/main.js"
click node_web "https://github.com/Anil-matcha/suparagent/blob/main/frontend/app/chat/page.tsx"
click node_mobile "https://github.com/Anil-matcha/suparagent/blob/main/mobile/src/app/thread/%5Bid%5D.tsx"
click node_api_client "https://github.com/Anil-matcha/suparagent/blob/main/frontend/lib/api.ts"
click node_auth "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/auth/middleware.py"
click node_engine_settings "https://github.com/Anil-matcha/suparagent/blob/main/frontend/components/EngineSettings.tsx"
click node_engine_routes "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/routers/engines.py"
click node_registry "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/engine_registry.py"
click node_thread_runtime "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/thread_runtime.py"
click node_engine_adapters "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/acp_adapter.py"
click node_thread_store "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/thread_store.py"
click node_agent_management "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/routers/agents.py"
click node_memory "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/memory_bridge.py"
click node_approvals "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/local_approval_broker.py"
click node_computers "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/computers/service.py"
click node_routines "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/routine_service.py"
click node_work_planning "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/work_planner.py"
click node_connected_apps "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/composio_service.py"
click node_skills_templates "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/agent_skills.py"
click node_workspace_files "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/workspace_files.py"
click node_database "https://github.com/Anil-matcha/suparagent/blob/main/backend/app/db/engine.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_web,node_mobile,node_api_client,node_engine_settings,node_user toneBlue
class node_thread_runtime,node_engine_adapters toneAmber
class node_agent_management,node_memory,node_approvals,node_computers,node_routines,node_work_planning,node_connected_apps,node_skills_templates,node_workspace_files toneMint
class node_auth,node_engine_routes,node_registry,node_thread_store,node_database toneRose
```

## Components

### Clients and access

- [Desktop shell](https://github.com/Anil-matcha/suparagent/blob/main/desktop/main.js): `desktop/main.js`
- [Web workspace](https://github.com/Anil-matcha/suparagent/blob/main/frontend/app/chat/page.tsx): `frontend/app/chat/page.tsx`
- [Phone app](https://github.com/Anil-matcha/suparagent/blob/main/mobile/src/app/thread/%5Bid%5D.tsx): `mobile/src/app/thread/[id].tsx`
- [API client](https://github.com/Anil-matcha/suparagent/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Engine settings](https://github.com/Anil-matcha/suparagent/blob/main/frontend/components/EngineSettings.tsx): `frontend/components/EngineSettings.tsx`

### Agent conversations

- [Thread runtime](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/thread_runtime.py): `backend/app/services/thread_runtime.py`
- [Engine adapters](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/acp_adapter.py): `backend/app/services/acp_adapter.py`

### Work coordination

- [Agents and teams](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/routers/agents.py): `backend/app/routers/agents.py`
- [Agent memory](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/memory_bridge.py): `backend/app/services/memory_bridge.py`
- [Approvals](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/local_approval_broker.py): `backend/app/services/local_approval_broker.py`
- [Agent computers](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/computers/service.py): `backend/app/computers/service.py`
- [Routines](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/routine_service.py): `backend/app/services/routine_service.py`
- [Tasks and planning](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/work_planner.py): `backend/app/services/work_planner.py`
- [Connected apps](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/composio_service.py): `backend/app/services/composio_service.py`
- [Skills and templates](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/agent_skills.py): `backend/app/services/agent_skills.py`
- [Workspace files](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/workspace_files.py): `backend/app/services/workspace_files.py`

### Runtime and state

- [Request authentication](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/auth/middleware.py): `backend/app/auth/middleware.py`
- [Engine API](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/routers/engines.py): `backend/app/routers/engines.py`
- [Engine registry](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/engine_registry.py): `backend/app/services/engine_registry.py`
- [Conversation history](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/services/thread_store.py): `backend/app/services/thread_store.py`
- [Application database](https://github.com/Anil-matcha/suparagent/blob/main/backend/app/db/engine.py): `backend/app/db/engine.py`

### Other components

- **User**

## Connections

- User → Desktop shell: opens workspace (evidence: `README.md`)
- User → Web workspace: starts chat (evidence: `README.md`)
- User → Phone app: pairs phone (evidence: `README.md`)
- Engine settings → API client: loads and saves (evidence: `frontend/components/EngineSettings.tsx`)
- Engine API → Engine registry: reads adapters (evidence: `backend/app/routers/engines.py`)
- Engine adapters → Conversation history: reads history (evidence: `backend/app/services/acp_adapter.py`)
- Engine adapters → Agent memory: uses memory bridge (evidence: `backend/app/services/acp_adapter.py`)
- Engine adapters → Approvals: uses approval broker (evidence: `backend/app/services/acp_adapter.py`)
- User → Agents and teams: creates agents (evidence: `README.md`)
- User → Approvals: reviews actions (evidence: `README.md`)
- User → Routines: schedules runs (evidence: `README.md`)
- User → Tasks and planning: plans tasks (evidence: `README.md`)
- User → Connected apps: connects tools (evidence: `README.md`)
- User → Skills and templates: reuses instructions (evidence: `README.md`)
- User → Workspace files: browses files (evidence: `README.md`)
- Agents and teams → Thread runtime: delegates work
- Thread runtime → Engine adapters: runs turns
- Thread runtime → Conversation history: persists conversations
- Thread runtime → Agent computers: uses computer tools
- Routines → Thread runtime: starts runs
- Agents and teams → Application database: stores agent state