# lonr-6/cc-desktop-switch architecture

> Architecture diagram of the GitHub repository lonr-6/cc-desktop-switch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lonr-6/cc-desktop-switch
- Repository: https://github.com/lonr-6/cc-desktop-switch

## Overview

1. **Product shape**
   CC Desktop Switch is a **local desktop companion app** for Claude Desktop, not a cloud service. It runs as a Python backend with a browser-based UI and acts as a local control plane for third-party, Anthropic-compatible providers.

2. **Two main runtimes**
   The repo is split into:
   - a **Python backend** that exposes local APIs and the gateway behavior
   - a **static frontend** in HTML/CSS/vanilla JS for the admin UI
   The README indicates the app can run as a normal desktop window or as a browser fallback at `http://127.0.0.1:18081`.

3. **Core architectural role of the backend**
   The backend is the system of record for provider settings, model mappings, proxy settings, and Claude Desktop integration. The key modules suggest clear boundaries:
   - `config.py` for persisted settings
   - `registry.py` for provider/model registration
   - `provider_tools.py` and `api_adapters.py` for provider-specific API behavior
   - `proxy.py` for upstream proxy handling
   - `model_alias.py` for mapping provider model IDs to Claude-safe names
   - `ccswitch_import.py` for importing CC-Switch-style configs
   - `update.py` for release/update support
   - `i18n.py` for localized UI strings

4. **Local gateway boundary**
   A major design choice is the **local gateway on `127.0.0.1:18080`**. Claude Desktop is configured to talk to this local layer rather than directly to every third-party provider. That gateway is responsible for:
   - translating Claude Desktop requests into provider-specific requests
   - preserving upstream API keys and headers locally
   - enforcing model routing and rejecting unmapped routes instead of silently falling back

5. **Provider management flow**
   The user selects or creates a provider preset in the UI, enters credentials, and the backend stores the configuration locally. The provider abstraction appears to support:
   - preset providers such as DeepSeek, Kimi, Zhipu GLM, Alibaba Cloud Bailian, Xiaomi MiMo
   - custom Anthropic-compatible endpoints
   - optional OpenAI-format imports, but only if the user opts in
   This indicates the architecture is built around **provider adapters + configuration registry**, not hardcoded single-provider logic.

6. **Model mapping and routing**
   The repo emphasizes **model aliasing** as a separate concern from provider connectivity. Third-party model IDs remain internal to the gateway, while Claude Desktop only sees Claude-safe slots. This is important because the model menu in Claude Desktop is intentionally filtered to only explicitly mapped routes, preventing accidental exposure of unsupported models.

7. **Connectivity, health, and streaming**
   The backend includes support for:
   - provider connectivity checks
   - model availability checks
   - SSE streaming
   - custom HTTP/SOCKS upstream proxying
   These features suggest the gateway is not just a config writer; it also validates and proxies live traffic so Claude Desktop can interact with provider APIs reliably.

8. **Claude Desktop integration boundary**
   The app’s “Apply to Claude Desktop” action likely writes or updates Claude Desktop’s third-party configuration on the local machine. The project is explicitly focused on **Windows and macOS**, so the backend must bridge between:
   - local app state in `~/.cc-desktop-switch/config.json`
   - platform-specific Claude Desktop configuration locations
   - restart/relaunch behavior required for Claude Desktop to pick up changes

9. **Frontend structure**
   The frontend is a lightweight single-page admin UI built from:
   - `frontend/index.html`
   - `frontend/css/style.css`
   - `frontend/js/app.js`
   - `frontend/js/api.js`
   - `frontend/js/i18n.js`
   - `frontend/assets/providers`
   This points to a UI that is mostly a thin client over backend APIs, with provider-specific assets and localized text bundled locally.

10. **Startup and process lifecycle**
   The root `main.py` and `backend/main.py` suggest a launcher/orchestrator layer. The README also mentions:
   - duplicate-instance prevention on Windows
   - tray behavior on Windows
   - hidden/background lifecycle on macOS
   So the app is designed as a long-running local utility, not a one-shot configuration tool, because Claude Desktop depends on the gateway staying alive.

11. **Packaging and platform-specific delivery**
   The repo contains substantial packaging infrastructure:
   - Windows: `build.spec`, `installer.nsi`, `start.bat`, `build.bat`
   - macOS: `macos/` build scripts, entitlements, pkg/dmg creation
   - release automation: `.github/workflows/release.yml`, `scripts/`
   This means the repository is architected for **desktop distribution artifacts**, not just source execution.

12. **Validation and quality gates**
   The `tests/` directory covers macOS config/library behavior and provider config/proxy behavior, which matches the app’s two riskiest areas: platform integration and network routing. The README’s verification steps also show a split between Python compilation/tests and JS syntax checks, reflecting the backend/frontend boundary.

13. **External dependencies that matter**
   Material dependencies include FastAPI, httpx, and uvicorn on the backend, and Bootstrap 5.3 via CDN on the frontend. These are not incidental: FastAPI and uvicorn define the local API/server surface, while httpx underpins outbound provider calls and streaming through the gateway.

14. **Overall architecture in one sentence**
   The repo is a **local desktop orchestration app** that stores provider configuration, maps models, proxies requests through a localhost gateway, and applies the resulting setup to Claude Desktop across Windows and macOS.

Main entry points: [`backend/main.py`](https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/main.py) (Server), [`.github/workflows/release.yml`](https://github.com/lonr-6/cc-desktop-switch/blob/main/.github/workflows/release.yml) (Release flow), [`frontend/js/app.js`](https://github.com/lonr-6/cc-desktop-switch/blob/main/frontend/js/app.js) (UI logic), [`frontend/index.html`](https://github.com/lonr-6/cc-desktop-switch/blob/main/frontend/index.html) (Admin UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_backend["Backend"]
  node_node_backend_main["Server<br/>[main.py]"]
  node_node_config[("Settings<br/>state store<br/>[config.py]")]
  node_node_registry["Registry<br/>provider catalog<br/>[registry.py]"]
  node_node_adapters["Adapters<br/>provider integration<br/>[api_adapters.py]"]
  node_node_tools["Provider tools<br/>validation<br/>[provider_tools.py]"]
  node_node_proxy["Proxy<br/>[proxy.py]"]
  node_node_alias["Model alias<br/>routing map<br/>[model_alias.py]"]
  node_node_import["Config import<br/>importer<br/>[ccswitch_import.py]"]
  node_node_update["Updater<br/>release support<br/>[update.py]"]
  node_node_i18n_backend["Backend i18n<br/>localization<br/>[i18n.py]"]
end

subgraph group_group_frontend["Frontend"]
  node_node_front_index["Admin UI<br/>single-page ui<br/>[index.html]"]
  node_node_front_app["UI logic<br/>client app<br/>[app.js]"]
  node_node_front_api["UI API<br/>client api<br/>[api.js]"]
  node_node_front_i18n["UI i18n<br/>localization<br/>[i18n.js]"]
  node_node_front_css["Styles<br/>ui styling<br/>[style.css]"]
end

subgraph group_group_platform["Platform"]
  node_node_main["Launcher<br/>entrypoint<br/>[main.py]"]
  node_node_claude["Claude Desktop<br/>external app"]
  node_node_platform_cfg[("Claude config<br/>platform config")]
end

subgraph group_group_delivery["Delivery"]
  node_node_release["Release flow<br/>packaging<br/>[release.yml]"]
  node_node_win_pkg["Windows package<br/>installer<br/>[installer.nsi]"]
  node_node_mac_pkg["macOS package<br/>installer<br/>[build-macos.sh]"]
  node_node_tests["Tests<br/>quality gates"]
end

node_node_main -->|"starts"| node_node_backend_main
node_node_backend_main -->|"loads"| node_node_config
node_node_backend_main -->|"uses"| node_node_registry
node_node_backend_main -->|"routes via"| node_node_adapters
node_node_backend_main -->|"proxies through"| node_node_proxy
node_node_backend_main -->|"maps"| node_node_alias
node_node_backend_main -->|"checks"| node_node_tools
node_node_backend_main -->|"imports"| node_node_import
node_node_backend_main -->|"updates"| node_node_update
node_node_backend_main -->|"localizes"| node_node_i18n_backend
node_node_front_index -->|"loads"| node_node_front_app
node_node_front_app -->|"calls"| node_node_front_api
node_node_front_app -->|"uses"| node_node_front_i18n
node_node_front_index -->|"styles"| node_node_front_css
node_node_front_app -->|"administers"| node_node_backend_main
node_node_backend_main -->|"writes"| node_node_platform_cfg
node_node_platform_cfg -->|"enables"| node_node_claude
node_node_backend_main -->|"serves"| node_node_claude
node_node_release -->|"builds"| node_node_win_pkg
node_node_release -->|"builds"| node_node_mac_pkg
node_node_release -->|"packages"| node_node_backend_main
node_node_release -->|"packages"| node_node_front_index
node_node_tests -->|"validates"| node_node_backend_main
node_node_tests -->|"validates"| node_node_platform_cfg

click node_node_main "https://github.com/lonr-6/cc-desktop-switch/blob/main/main.py"
click node_node_backend_main "https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/main.py"
click node_node_config "https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/config.py"
click node_node_registry "https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/registry.py"
click node_node_adapters "https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/api_adapters.py"
click node_node_tools "https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/provider_tools.py"
click node_node_proxy "https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/proxy.py"
click node_node_alias "https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/model_alias.py"
click node_node_import "https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/ccswitch_import.py"
click node_node_update "https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/update.py"
click node_node_i18n_backend "https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/i18n.py"
click node_node_front_index "https://github.com/lonr-6/cc-desktop-switch/blob/main/frontend/index.html"
click node_node_front_app "https://github.com/lonr-6/cc-desktop-switch/blob/main/frontend/js/app.js"
click node_node_front_api "https://github.com/lonr-6/cc-desktop-switch/blob/main/frontend/js/api.js"
click node_node_front_i18n "https://github.com/lonr-6/cc-desktop-switch/blob/main/frontend/js/i18n.js"
click node_node_front_css "https://github.com/lonr-6/cc-desktop-switch/blob/main/frontend/css/style.css"
click node_node_release "https://github.com/lonr-6/cc-desktop-switch/blob/main/.github/workflows/release.yml"
click node_node_win_pkg "https://github.com/lonr-6/cc-desktop-switch/blob/main/installer.nsi"
click node_node_mac_pkg "https://github.com/lonr-6/cc-desktop-switch/blob/main/macos/build-macos.sh"
click node_node_tests "https://github.com/lonr-6/cc-desktop-switch/blob/main/tests/test_provider_config_and_proxy.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_node_backend_main,node_node_config,node_node_registry,node_node_adapters,node_node_tools,node_node_proxy,node_node_alias,node_node_import,node_node_update,node_node_i18n_backend toneBlue
class node_node_front_index,node_node_front_app,node_node_front_api,node_node_front_i18n,node_node_front_css toneAmber
class node_node_main,node_node_claude,node_node_platform_cfg toneMint
class node_node_release,node_node_win_pkg,node_node_mac_pkg,node_node_tests toneRose
```

## Components

### Backend

Local Python control plane, gateway, and integration logic.

- [Server](https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/main.py): api server · Backend application entrypoint and local API host. · `backend/main.py`
- [Settings](https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/config.py): state store · Persists local app configuration and provider settings. · `backend/config.py`
- [Registry](https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/registry.py): provider catalog · Tracks provider presets, models, and available routes. · `backend/registry.py`
- [Adapters](https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/api_adapters.py): provider integration · Provider-specific request translation and API shaping. · `backend/api_adapters.py`
- [Provider tools](https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/provider_tools.py): validation · Connectivity checks, model checks, and provider helper logic. · `backend/provider_tools.py`
- [Proxy](https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/proxy.py): upstream proxy · Handles HTTP/SOCKS proxying for outbound provider traffic. · `backend/proxy.py`
- [Model alias](https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/model_alias.py): routing map · Maps provider model IDs to Claude-safe model names. · `backend/model_alias.py`
- [Config import](https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/ccswitch_import.py): importer · Imports CC-Switch style provider and model configuration. · `backend/ccswitch_import.py`
- [Updater](https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/update.py): release support · Update and release metadata handling. · `backend/update.py`
- [Backend i18n](https://github.com/lonr-6/cc-desktop-switch/blob/main/backend/i18n.py): localization · Localized strings used by the backend and UI integration. · `backend/i18n.py`

### Frontend

Static browser UI for local administration.

- [Admin UI](https://github.com/lonr-6/cc-desktop-switch/blob/main/frontend/index.html): single-page ui · Main browser-based administration shell. · `frontend/index.html`
- [UI logic](https://github.com/lonr-6/cc-desktop-switch/blob/main/frontend/js/app.js): client app · Frontend state management and screen behavior. · `frontend/js/app.js`
- [UI API](https://github.com/lonr-6/cc-desktop-switch/blob/main/frontend/js/api.js): client api · Browser-side wrapper for local backend calls. · `frontend/js/api.js`
- [UI i18n](https://github.com/lonr-6/cc-desktop-switch/blob/main/frontend/js/i18n.js): localization · Frontend string localization and language selection. · `frontend/js/i18n.js`
- [Styles](https://github.com/lonr-6/cc-desktop-switch/blob/main/frontend/css/style.css): ui styling · Visual styling for the local admin interface. · `frontend/css/style.css`

### Platform

Claude Desktop integration and OS-specific lifecycle.

- [Launcher](https://github.com/lonr-6/cc-desktop-switch/blob/main/main.py): entrypoint · Starts the desktop app and coordinates the runtime. · `main.py`
- **Claude Desktop**: external app · Local desktop app that consumes the gateway and config.
- **Claude config**: platform config · Platform-specific Claude Desktop configuration files and app state.

### Delivery

Packaging, release, and distribution artifacts.

- [Release flow](https://github.com/lonr-6/cc-desktop-switch/blob/main/.github/workflows/release.yml): packaging · Build and release automation for desktop distribution. · `.github/workflows/release.yml`
- [Windows package](https://github.com/lonr-6/cc-desktop-switch/blob/main/installer.nsi): installer · Windows build and installer artifacts. · `installer.nsi`
- [macOS package](https://github.com/lonr-6/cc-desktop-switch/blob/main/macos/build-macos.sh): installer · macOS build scripts, entitlements, and package creation. · `macos/build-macos.sh`
- [Tests](https://github.com/lonr-6/cc-desktop-switch/blob/main/tests/test_provider_config_and_proxy.py): quality gates · Coverage for platform integration, provider config, and proxy behavior. · `tests/test_provider_config_and_proxy.py`

## Connections

- Launcher → Server: starts · Launcher hands off to the local server/runtime.
- Server → Settings: loads · Reads and persists local settings.
- Server → Registry: uses · Initializes provider and model registry state.
- Server → Adapters: routes via · Dispatches provider-specific request handling.
- Server → Proxy: proxies through · Applies upstream proxy settings for outbound traffic.
- Server → Model alias: maps · Translates provider models into Claude-safe aliases.
- Server → Provider tools: checks · Runs connectivity and availability validation.
- Server → Config import: imports · Supports external config import workflows.
- Server → Updater: updates · Surfaces update and release support.
- Server → Backend i18n: localizes · Provides localized backend-facing strings.
- Admin UI → UI logic: loads · Browser shell hosts the UI logic.
- UI logic → UI API: calls · Frontend invokes local backend endpoints.
- UI logic → UI i18n: uses · UI text and language switching.
- Admin UI → Styles: styles · Applies local styling to the admin UI.
- UI logic → Server: administers · UI controls the local backend control plane.
- Server → Claude config: writes · Applies Claude Desktop configuration changes.
- Claude config → Claude Desktop: enables · Claude Desktop consumes the local gateway setup.
- Server → Claude Desktop: serves · Provides the localhost gateway Claude Desktop talks to.
- Release flow → Windows package: builds · Release automation produces Windows artifacts.
- Release flow → macOS package: builds · Release automation produces macOS artifacts.
- Release flow → Server: packages · Bundles the backend runtime into releases.
- Release flow → Admin UI: packages · Bundles the static frontend into releases.
- Tests → Server: validates · Tests backend integration and proxy behavior.
- Tests → Claude config: validates · Tests macOS configuration/library behavior.
