# superset-sh/superset architecture

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

- Interactive diagram: https://gitdiagram.com/superset-sh/superset
- Repository: https://github.com/superset-sh/superset

## Overview

Superset is a desktop workspace for running coding agents in parallel and reviewing their work. The documented workflow is to add a repository, create a workspace, launch an agent, inspect and revise its changes, preview the app, then commit or push. The tree supports the desktop’s workspace, Git, browser, and terminal layers; README-described capabilities such as scheduled automations and mobile are represented where matching runtime paths are visible. Several feature paths are unsampled, so uncertain implementation links are omitted.

Main entry points: [`apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/$workspaceId`](https://github.com/superset-sh/superset/tree/main/apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/%24workspaceId) (Agent workspace UI), [`apps/api/src/app/api/route.ts`](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/route.ts) (API service), [`apps/desktop/src/lib/electron-app/factories/app/setup.ts`](https://github.com/superset-sh/superset/blob/main/apps/desktop/src/lib/electron-app/factories/app/setup.ts) (Desktop app), [`apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceForm/PromptGroup/hooks/useBranchPickerController/useBranchPickerController.ts`](https://github.com/superset-sh/superset/blob/main/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceForm/PromptGroup/hooks/useBranchPickerController/useBranchPickerController.ts) (Workspace creation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace management"]
  node_desktop["Desktop app<br/>[setup.ts]"]
  node_workspace_ui["Workspace creation"]
  node_workspace_router["Workspace operations"]
end

subgraph group_agents["Agent sessions"]
  node_terminal["Terminal sessions"]
  node_agent_ui["Agent workspace UI"]
  node_chat["Agent chat"]
end

subgraph group_review["Review and delivery"]
  node_git["Git and worktrees"]
  node_browser["Browser preview<br/>[browser.ts]"]
  node_diff["Change review"]
  node_github["Pull requests"]
end

subgraph group_remote["Remote services"]
  node_automation["Scheduled agents"]
  node_api["API service<br/>[route.ts]"]
  node_mcp["MCP server<br/>[route.ts]"]
  node_mobile["Mobile API<br/>[route.ts]"]
  node_host["Remote host service"]
  node_cloud["Cloud service"]
end

node_user(("User"))

node_user -->|"uses"| node_desktop
node_desktop -->|"opens"| node_workspace_ui
node_workspace_ui -->|"creates workspace"| node_workspace_router
node_workspace_router -->|"manages worktrees"| node_git
node_user -->|"starts task"| node_agent_ui
node_agent_ui -->|"opens sessions"| node_terminal
node_agent_ui -->|"prompts agent"| node_chat
node_chat -->|"sends chat requests"| node_host
node_user -->|"reviews changes"| node_diff
node_diff -->|"reads changes"| node_git
node_user -->|"previews app"| node_browser
node_user -.->|"uses PR workflows"| node_github
node_automation -->|"dispatches runs"| node_api
node_mcp -->|"serves requests"| node_api
node_mobile -->|"exposes endpoint"| node_api
node_cloud -->|"provisions host"| node_host

click node_desktop "https://github.com/superset-sh/superset/blob/main/apps/desktop/src/lib/electron-app/factories/app/setup.ts"
click node_workspace_ui "https://github.com/superset-sh/superset/blob/main/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceForm/PromptGroup/hooks/useBranchPickerController/useBranchPickerController.ts"
click node_workspace_router "https://github.com/superset-sh/superset/tree/main/apps/desktop/src/lib/trpc/routers"
click node_git "https://github.com/superset-sh/superset/tree/main/apps/desktop/src/lib/trpc/routers/changes"
click node_terminal "https://github.com/superset-sh/superset/tree/main/apps/desktop/src/lib/trpc/routers"
click node_agent_ui "https://github.com/superset-sh/superset/tree/main/apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/%24workspaceId"
click node_chat "https://github.com/superset-sh/superset/blob/main/apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/%24workspaceId/hooks/usePaneRegistry/components/ChatV3Pane/hooks/useSessionClient/useSessionClient.ts"
click node_browser "https://github.com/superset-sh/superset/blob/main/apps/desktop/src/lib/trpc/routers/browser/browser.ts"
click node_diff "https://github.com/superset-sh/superset/tree/main/apps/desktop/src/lib/trpc/routers/changes"
click node_github "https://github.com/superset-sh/superset/blob/main/apps/desktop/src/lib/trpc/routers/changes/utils/pull-request-discovery.ts"
click node_automation "https://github.com/superset-sh/superset/tree/main/apps/api/src/lib/automations"
click node_api "https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/route.ts"
click node_mcp "https://github.com/superset-sh/superset/blob/main/apps/api/src/app/mcp/route.ts"
click node_mobile "https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/mobile/version/route.ts"
click node_host "https://github.com/superset-sh/superset/tree/main/apps/desktop/src/lib/trpc/routers/host-service-coordinator"
click node_cloud "https://github.com/superset-sh/superset/tree/main/apps/api/src/app/api/cloud-workspaces"

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_workspace_ui,node_workspace_router,node_user toneBlue
class node_terminal,node_agent_ui,node_chat toneAmber
class node_git,node_browser,node_diff,node_github toneMint
class node_automation,node_api,node_mcp,node_mobile,node_host,node_cloud toneRose
```

## Components

### Workspace management

- [Desktop app](https://github.com/superset-sh/superset/blob/main/apps/desktop/src/lib/electron-app/factories/app/setup.ts): `apps/desktop/src/lib/electron-app/factories/app/setup.ts`
- [Workspace creation](https://github.com/superset-sh/superset/blob/main/apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceForm/PromptGroup/hooks/useBranchPickerController/useBranchPickerController.ts): `apps/desktop/src/renderer/routes/_authenticated/components/DashboardNewWorkspaceModal/components/DashboardNewWorkspaceForm/PromptGroup/hooks/useBranchPickerController/useBranchPickerController.ts`
- [Workspace operations](https://github.com/superset-sh/superset/tree/main/apps/desktop/src/lib/trpc/routers): `apps/desktop/src/lib/trpc/routers`

### Agent sessions

- [Terminal sessions](https://github.com/superset-sh/superset/tree/main/apps/desktop/src/lib/trpc/routers): `apps/desktop/src/lib/trpc/routers`
- [Agent workspace UI](https://github.com/superset-sh/superset/tree/main/apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/%24workspaceId): `apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/$workspaceId`
- [Agent chat](https://github.com/superset-sh/superset/blob/main/apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/%24workspaceId/hooks/usePaneRegistry/components/ChatV3Pane/hooks/useSessionClient/useSessionClient.ts): `apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/$workspaceId/hooks/usePaneRegistry/components/ChatV3Pane/hooks/useSessionClient/useSessionClient.ts`

### Review and delivery

- [Git and worktrees](https://github.com/superset-sh/superset/tree/main/apps/desktop/src/lib/trpc/routers/changes): `apps/desktop/src/lib/trpc/routers/changes`
- [Browser preview](https://github.com/superset-sh/superset/blob/main/apps/desktop/src/lib/trpc/routers/browser/browser.ts): `apps/desktop/src/lib/trpc/routers/browser/browser.ts`
- [Change review](https://github.com/superset-sh/superset/tree/main/apps/desktop/src/lib/trpc/routers/changes): `apps/desktop/src/lib/trpc/routers/changes`
- [Pull requests](https://github.com/superset-sh/superset/blob/main/apps/desktop/src/lib/trpc/routers/changes/utils/pull-request-discovery.ts): `apps/desktop/src/lib/trpc/routers/changes/utils/pull-request-discovery.ts`

### Remote services

- [Scheduled agents](https://github.com/superset-sh/superset/tree/main/apps/api/src/lib/automations): `apps/api/src/lib/automations`
- [API service](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/route.ts): `apps/api/src/app/api/route.ts`
- [MCP server](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/mcp/route.ts): `apps/api/src/app/mcp/route.ts`
- [Mobile API](https://github.com/superset-sh/superset/blob/main/apps/api/src/app/api/mobile/version/route.ts): `apps/api/src/app/api/mobile/version/route.ts`
- [Remote host service](https://github.com/superset-sh/superset/tree/main/apps/desktop/src/lib/trpc/routers/host-service-coordinator): `apps/desktop/src/lib/trpc/routers/host-service-coordinator`
- [Cloud service](https://github.com/superset-sh/superset/tree/main/apps/api/src/app/api/cloud-workspaces): `apps/api/src/app/api/cloud-workspaces`

### Other components

- **User**

## Connections

- User → Desktop app: uses
- Desktop app → Workspace creation: opens
- Workspace creation → Workspace operations: creates workspace
- Workspace operations → Git and worktrees: manages worktrees
- User → Agent workspace UI: starts task
- Agent workspace UI → Terminal sessions: opens sessions
- Agent workspace UI → Agent chat: prompts agent
- Agent chat → Remote host service: sends chat requests
- User → Change review: reviews changes
- Change review → Git and worktrees: reads changes
- User → Browser preview: previews app
- User → Pull requests: uses PR workflows
- Scheduled agents → API service: dispatches runs
- MCP server → API service: serves requests
- Mobile API → API service: exposes endpoint
- Cloud service → Remote host service: provisions host