# siteboon/claudecodeui architecture

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

- Interactive diagram: https://gitdiagram.com/siteboon/claudecodeui
- Repository: https://github.com/siteboon/claudecodeui

## Overview

CloudCLI is a responsive desktop/mobile interface for coding-agent CLIs, usable locally or remotely. Users authenticate, select a project and provider, then manage or resume sessions and interact with an agent through chat; the server exposes APIs and coordinates provider runtimes. The product also includes project files, Git, browser-use, plugins, TaskMaster, voice, and notifications, with an optional Electron companion. The graph preserves these documented capabilities; unsampled subsystem links are omitted rather than inferred.

Main entry points: [`server/index.ts`](https://github.com/siteboon/claudecodeui/blob/main/server/index.ts) (HTTP Server), [`src/App.tsx`](https://github.com/siteboon/claudecodeui/blob/main/src/App.tsx) (Application Shell), [`electron/main.js`](https://github.com/siteboon/claudecodeui/blob/main/electron/main.js) (Desktop App), [`src/modules/chat/ChatInterface.tsx`](https://github.com/siteboon/claudecodeui/blob/main/src/modules/chat/ChatInterface.tsx) (Agent Chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Companion"]
  node_desktop_main["Desktop App<br/>[main.js]"]
  node_desktop_windows["Desktop Windows<br/>[desktopWindow.js]"]
  node_desktop_local["Local Server<br/>[localServer.js]"]
  node_desktop_installer["Server Installer<br/>[serverInstaller.js]"]
  node_desktop_views["View Host<br/>[viewHost.js]"]
  node_desktop_notifications["Desktop Notifications"]
end

subgraph group_client["Web Client"]
  node_app["Application Shell<br/>[App.tsx]"]
  node_auth["Authentication"]
  node_workspace["Workspace UI"]
  node_chat["Agent Chat<br/>[ChatInterface.tsx]"]
  node_chat_messages["Message State<br/>[useChatMessages.ts]"]
  node_session_store["Session Store<br/>[useSessionStore.ts]"]
  node_api_client["API Client<br/>[api.ts]"]
  node_preferences[("User Preferences<br/>[userSettings.ts]")]
  node_theme["Theme Context<br/>[ThemeContext.tsx]"]
  node_i18n["Localization<br/>[config.ts]"]
end

subgraph group_server["Agent Server"]
  node_server_app["HTTP Server<br/>[index.ts]"]
  node_database[("Application Database")]
  node_provider_routes["Provider API<br/>[provider.routes.ts]"]
  node_provider_models["Model Catalog"]
  node_provider_sessions["Session Service"]
  node_session_watcher["Session Watcher"]
  node_provider_cli["Agent CLIs"]
end

subgraph group_projects["Project Workspace"]
  node_file_tree["File Explorer"]
  node_git["Git Explorer<br/>[git.routes.ts]"]
  node_browser_use["Browser Use"]
end

subgraph group_extensions["Product Extensions"]
  node_plugins["Plugin System"]
  node_taskmaster["TaskMaster"]
  node_voice["Voice"]
  node_notifications["Notifications"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_user -->|"opens"| node_desktop_main
node_desktop_main -->|"creates"| node_desktop_windows
node_desktop_main -->|"manages"| node_desktop_local
node_desktop_local -->|"uses"| node_desktop_installer
node_desktop_windows -->|"uses"| node_desktop_views
node_desktop_main -->|"configures"| node_desktop_notifications
node_app -->|"provides"| node_auth
node_app -->|"routes to"| node_workspace
node_app -->|"provides"| node_theme
node_app -->|"provides"| node_i18n
node_user -->|"chats with"| node_chat
node_chat -.->|"manages"| node_chat_messages
node_chat -.->|"uses"| node_session_store
node_chat -.->|"requests"| node_api_client
node_workspace -.->|"reads"| node_preferences
node_api_client -->|"calls API"| node_server_app
node_server_app -->|"initializes"| node_database
node_server_app -->|"mounts routes"| node_provider_routes
node_provider_routes -.->|"serves models"| node_provider_models
node_provider_routes -.->|"serves sessions"| node_provider_sessions
node_server_app -->|"initializes"| node_session_watcher
node_session_watcher -.->|"observes"| node_provider_cli
node_user -->|"explores files"| node_file_tree
node_user -->|"manages changes"| node_git
node_user -->|"uses browser"| node_browser_use
node_user -->|"extends"| node_plugins
node_user -->|"plans tasks"| node_taskmaster
node_user -.->|"uses voice"| node_voice
node_server_app -->|"starts servers"| node_plugins
node_server_app -->|"configures push"| node_notifications

click node_desktop_main "https://github.com/siteboon/claudecodeui/blob/main/electron/main.js"
click node_desktop_windows "https://github.com/siteboon/claudecodeui/blob/main/electron/desktopWindow.js"
click node_desktop_local "https://github.com/siteboon/claudecodeui/blob/main/electron/localServer.js"
click node_desktop_installer "https://github.com/siteboon/claudecodeui/blob/main/electron/serverInstaller.js"
click node_desktop_views "https://github.com/siteboon/claudecodeui/blob/main/electron/viewHost.js"
click node_desktop_notifications "https://github.com/siteboon/claudecodeui/blob/main/electron/desktopNotifications.js"
click node_app "https://github.com/siteboon/claudecodeui/blob/main/src/App.tsx"
click node_auth "https://github.com/siteboon/claudecodeui/tree/main/src/modules/auth"
click node_workspace "https://github.com/siteboon/claudecodeui/tree/main/src/modules/project-workspace"
click node_chat "https://github.com/siteboon/claudecodeui/blob/main/src/modules/chat/ChatInterface.tsx"
click node_chat_messages "https://github.com/siteboon/claudecodeui/blob/main/src/modules/chat/hooks/useChatMessages.ts"
click node_session_store "https://github.com/siteboon/claudecodeui/blob/main/src/modules/chat/hooks/useSessionStore.ts"
click node_api_client "https://github.com/siteboon/claudecodeui/blob/main/src/shared/api.ts"
click node_preferences "https://github.com/siteboon/claudecodeui/blob/main/src/shared/userSettings.ts"
click node_theme "https://github.com/siteboon/claudecodeui/blob/main/src/shared/context/ThemeContext.tsx"
click node_i18n "https://github.com/siteboon/claudecodeui/blob/main/src/modules/i18n/config.ts"
click node_server_app "https://github.com/siteboon/claudecodeui/blob/main/server/index.ts"
click node_database "https://github.com/siteboon/claudecodeui/tree/main/server/modules/database"
click node_provider_routes "https://github.com/siteboon/claudecodeui/blob/main/server/modules/providers/provider.routes.ts"
click node_provider_models "https://github.com/siteboon/claudecodeui/blob/main/server/modules/providers/services/provider-models.service.ts"
click node_provider_sessions "https://github.com/siteboon/claudecodeui/blob/main/server/modules/providers/services/sessions.service.ts"
click node_session_watcher "https://github.com/siteboon/claudecodeui/blob/main/server/modules/providers/services/sessions-watcher.service.ts"
click node_provider_cli "https://github.com/siteboon/claudecodeui/tree/main/server/modules/providers/list"
click node_file_tree "https://github.com/siteboon/claudecodeui/blob/main/server/modules/file-tree/file-tree.routes.ts"
click node_git "https://github.com/siteboon/claudecodeui/blob/main/server/modules/git/git.routes.ts"
click node_browser_use "https://github.com/siteboon/claudecodeui/blob/main/server/modules/browser-use/browser-use.service.ts"
click node_plugins "https://github.com/siteboon/claudecodeui/tree/main/server/modules/plugins"
click node_taskmaster "https://github.com/siteboon/claudecodeui/tree/main/server/modules/taskmaster"
click node_voice "https://github.com/siteboon/claudecodeui/tree/main/server/modules/voice"
click node_notifications "https://github.com/siteboon/claudecodeui/tree/main/server/modules/notifications"

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_main,node_desktop_windows,node_desktop_local,node_desktop_installer,node_desktop_views,node_desktop_notifications,node_user toneBlue
class node_app,node_auth,node_workspace,node_chat,node_chat_messages,node_session_store,node_api_client,node_preferences,node_theme,node_i18n toneAmber
class node_server_app,node_database,node_provider_routes,node_provider_models,node_provider_sessions,node_session_watcher,node_provider_cli toneMint
class node_file_tree,node_git,node_browser_use toneRose
class node_plugins,node_taskmaster,node_voice,node_notifications toneIndigo
```

## Components

### Desktop Companion

- [Desktop App](https://github.com/siteboon/claudecodeui/blob/main/electron/main.js): `electron/main.js`
- [Desktop Windows](https://github.com/siteboon/claudecodeui/blob/main/electron/desktopWindow.js): `electron/desktopWindow.js`
- [Local Server](https://github.com/siteboon/claudecodeui/blob/main/electron/localServer.js): `electron/localServer.js`
- [Server Installer](https://github.com/siteboon/claudecodeui/blob/main/electron/serverInstaller.js): `electron/serverInstaller.js`
- [View Host](https://github.com/siteboon/claudecodeui/blob/main/electron/viewHost.js): `electron/viewHost.js`
- [Desktop Notifications](https://github.com/siteboon/claudecodeui/blob/main/electron/desktopNotifications.js): `electron/desktopNotifications.js`

### Web Client

- [Application Shell](https://github.com/siteboon/claudecodeui/blob/main/src/App.tsx): `src/App.tsx`
- [Authentication](https://github.com/siteboon/claudecodeui/tree/main/src/modules/auth): `src/modules/auth`
- [Workspace UI](https://github.com/siteboon/claudecodeui/tree/main/src/modules/project-workspace): `src/modules/project-workspace`
- [Agent Chat](https://github.com/siteboon/claudecodeui/blob/main/src/modules/chat/ChatInterface.tsx): `src/modules/chat/ChatInterface.tsx`
- [Message State](https://github.com/siteboon/claudecodeui/blob/main/src/modules/chat/hooks/useChatMessages.ts): `src/modules/chat/hooks/useChatMessages.ts`
- [Session Store](https://github.com/siteboon/claudecodeui/blob/main/src/modules/chat/hooks/useSessionStore.ts): `src/modules/chat/hooks/useSessionStore.ts`
- [API Client](https://github.com/siteboon/claudecodeui/blob/main/src/shared/api.ts): `src/shared/api.ts`
- [User Preferences](https://github.com/siteboon/claudecodeui/blob/main/src/shared/userSettings.ts): `src/shared/userSettings.ts`
- [Theme Context](https://github.com/siteboon/claudecodeui/blob/main/src/shared/context/ThemeContext.tsx): `src/shared/context/ThemeContext.tsx`
- [Localization](https://github.com/siteboon/claudecodeui/blob/main/src/modules/i18n/config.ts): `src/modules/i18n/config.ts`

### Agent Server

- [HTTP Server](https://github.com/siteboon/claudecodeui/blob/main/server/index.ts): `server/index.ts`
- [Application Database](https://github.com/siteboon/claudecodeui/tree/main/server/modules/database): `server/modules/database`
- [Provider API](https://github.com/siteboon/claudecodeui/blob/main/server/modules/providers/provider.routes.ts): `server/modules/providers/provider.routes.ts`
- [Model Catalog](https://github.com/siteboon/claudecodeui/blob/main/server/modules/providers/services/provider-models.service.ts): `server/modules/providers/services/provider-models.service.ts`
- [Session Service](https://github.com/siteboon/claudecodeui/blob/main/server/modules/providers/services/sessions.service.ts): `server/modules/providers/services/sessions.service.ts`
- [Session Watcher](https://github.com/siteboon/claudecodeui/blob/main/server/modules/providers/services/sessions-watcher.service.ts): `server/modules/providers/services/sessions-watcher.service.ts`
- [Agent CLIs](https://github.com/siteboon/claudecodeui/tree/main/server/modules/providers/list): `server/modules/providers/list`

### Project Workspace

- [File Explorer](https://github.com/siteboon/claudecodeui/blob/main/server/modules/file-tree/file-tree.routes.ts): `server/modules/file-tree/file-tree.routes.ts`
- [Git Explorer](https://github.com/siteboon/claudecodeui/blob/main/server/modules/git/git.routes.ts): `server/modules/git/git.routes.ts`
- [Browser Use](https://github.com/siteboon/claudecodeui/blob/main/server/modules/browser-use/browser-use.service.ts): `server/modules/browser-use/browser-use.service.ts`

### Product Extensions

- [Plugin System](https://github.com/siteboon/claudecodeui/tree/main/server/modules/plugins): `server/modules/plugins`
- [TaskMaster](https://github.com/siteboon/claudecodeui/tree/main/server/modules/taskmaster): `server/modules/taskmaster`
- [Voice](https://github.com/siteboon/claudecodeui/tree/main/server/modules/voice): `server/modules/voice`
- [Notifications](https://github.com/siteboon/claudecodeui/tree/main/server/modules/notifications): `server/modules/notifications`

### Other components

- **User**

## Connections

- User → Application Shell: uses
- User → Desktop App: opens
- Desktop App → Desktop Windows: creates (evidence: `electron/main.js`)
- Desktop App → Local Server: manages (evidence: `electron/main.js`)
- Local Server → Server Installer: uses (evidence: `electron/localServer.js`)
- Desktop Windows → View Host: uses (evidence: `electron/desktopWindow.js`)
- Desktop App → Desktop Notifications: configures (evidence: `electron/main.js`)
- Application Shell → Authentication: provides (evidence: `src/App.tsx`)
- Application Shell → Workspace UI: routes to (evidence: `src/App.tsx`)
- Application Shell → Theme Context: provides (evidence: `src/App.tsx`)
- Application Shell → Localization: provides (evidence: `src/App.tsx`)
- User → Agent Chat: chats with
- Agent Chat → Message State: manages
- Agent Chat → Session Store: uses
- Agent Chat → API Client: requests
- Workspace UI → User Preferences: reads
- API Client → HTTP Server: calls API
- HTTP Server → Application Database: initializes (evidence: `server/index.ts`)
- HTTP Server → Provider API: mounts routes (evidence: `server/index.ts`)
- Provider API → Model Catalog: serves models
- Provider API → Session Service: serves sessions
- HTTP Server → Session Watcher: initializes (evidence: `server/index.ts`)
- Session Watcher → Agent CLIs: observes
- User → File Explorer: explores files
- User → Git Explorer: manages changes
- User → Browser Use: uses browser
- User → Plugin System: extends
- User → TaskMaster: plans tasks
- User → Voice: uses voice
- HTTP Server → Plugin System: starts servers (evidence: `server/index.ts`)
- HTTP Server → Notifications: configures push (evidence: `server/index.ts`)
