ccs/docs/system-architecture/index.md

CCS System Architecture

Last Updated: 2026-04-14

High-level architecture overview for the CCS (Claude Code Switch) system.

---

System Overview

CCS is a multi-provider profile and runtime manager that enables seamless switching between multiple Claude accounts, alternative AI providers, and multiple CLI targets (Claude Code, Factory Droid, Codex CLI) for credential delivery.

The system consists of two main components:

1. CLI Application (src/) - Node.js TypeScript CLI
2. Dashboard UI (ui/) - React web application served by Express

Dashboard localization (i18n) architecture and contributor workflow are documented in Dashboard i18n Guide.

CCS v7.34 adds Image Analysis Hook for vision model proxying through CLIProxy with automatic injection for all profile types. CCS v7.67 adds a native structured logging lane for CCS-owned runtime events, backed by src/services/logging/, bounded JSONL files under ~/.ccs/logs/, and a dedicated dashboard /logs route. CCS PR review now uses PR-Agent in GitHub Actions, with reviews running on the self-hosted cliproxy runner, existing AI_REVIEW_* workflow variables and secrets preserved as the runtime contract, and repo-level guidance stored in .pr_agent.toml.

+===========================================================================+
|                              CCS System                                    |
+===========================================================================+
|                                                                           |
|   +------------------+      +-----------------+      +----------------+   |
|   |   User Terminal  | ---> |   CCS CLI       | ---> | Target CLI           |   |
|   |   (ccs command)  |      |   (src/ccs.ts)  |      | (claude/droid/codex) |   |
|   +------------------+      +-----------------+      +----------------+   |
|                                    |                        |             |
|                                    v                        v             |
|   +------------------+      +-----------------+      +----------------+   |
|   |   Dashboard UI   | <--> |   Express       | ---> | Provider APIs  |   |
|   |   (React SPA)    |      |   Web Server    |      | (Claude/GLM/   |   |
|   +------------------+      +-----------------+      |  Gemini/etc)   |   |
|                                    |                 +----------------+   |
|                                    v                                      |
|                        +---------------------+                            |
|                        |    CLIProxyAPI      |                            |
|                        |  (Local or Remote)  |                            |
|                        +---------------------+                            |
|                                                                           |
+===========================================================================+

---

Component Architecture

Multi-Target Adapter System

CCS v7.45 introduces the Target Adapter pattern, enabling seamless integration with different CLI implementations.

Key architecture:

Profile Resolution (CLIProxy, Settings/API, Account-based)
        |
        v
Target Resolution (--target flag > runtime entrypoint / argv[0] > config > default)
        |
        v
Get Target Adapter (Claude, Droid, or Codex)
        |
        +---> detectBinary()     (find CLI on system)
        |
        +---> prepareCredentials() (write config or set env)
        |
        +---> buildArgs()        (construct CLI arguments)
        |
        +---> buildEnv()         (prepare environment variables)
        |
        v
Spawn Target Process

Each target adapter implements different credential delivery:

• Claude Adapter: Env var delivery (existing behavior)

  • ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL
  • No config files needed

• Droid Adapter: Config file delivery to ~/.factory/settings.json

  • Writes custom model entry: custom:ccs-<profile>
  • Spawns: droid -m custom:ccs-<profile> <args>
  • Model config includes baseUrl, apiKey, provider

• Codex Adapter: Transient runtime overrides plus user-layer dashboard inspection

  • Uses codex -c key=value only for CCS-routed launches
  • Preserves native ~/.codex/config.toml ownership
  • Dashboard page reads/writes only the user config layer with explicit runtime-vs-provider warnings

Runtime entrypoints (built-in bins) and argv[0]-style aliases:

ccs        → Target: claude (default)
ccs-droid  → Target: droid (explicit alias)
ccsd       → Target: droid (legacy shortcut)
ccs-codex  → Target: codex (explicit alias)
ccsx       → Target: codex (short alias)
ccsxp      → Target: codex (provider shortcut; rewrites argv to `ccs codex --target codex`)

For details on the adapter architecture, see Target Adapters.

CLI Layer

+===========================================================================+
|                           CLI Architecture                                |
+===========================================================================+

  User Input (ccs [--target <cli>] <profile> [args])
        |
        v
  +-------------+
  |   ccs.ts    |  Entry point, command routing
  +-------------+
        |
        +---> [Version/Help/Doctor/etc.] ---> Exit
        |
        v
  +------------------+
  | Target Resolution | Determine which CLI to use
  +------------------+
        |
        v
  +-------------+
  |  Profile    |  Determines execution path
  |  Detection  |
  +-------------+
        |
        +---> [Native Claude Account] ---> execClaude()
        |                                       |
        +---> [CLIProxy Provider] ---> execClaudeWithCLIProxy()
        |                                       |
        +---> [Settings/API Profile] ---> normalize legacy glmt if needed
        |
        v
  +------------------+
  | Target Adapter   |  Get appropriate adapter
  +------------------+
        |
        v
  +------------------+
  | Prepare Creds    |  Deliver credentials
  +------------------+
        |
        v
  +------------------+
  | Target CLI       |  Claude Code or Droid
  +------------------+

---

Data Flow Architecture

CLI Execution Flow

+===========================================================================+
|                        CLI Execution Flow                                  |
+===========================================================================+

  1. Parse Arguments
        |
        v
  2. Resolve Target Type
        |
        v
  3. Detect Profile Type
        |
        +---> Native Claude ---> 3a. Load Account Settings
        |                              |
        |                              v
        |                        4a. Set CLAUDE_CONFIG_DIR
        |                              |
        |                              v
        |                        5a. Get Claude Target Adapter
        |
        +---> CLIProxy -------> 3b. Ensure Binary Installed
        |                              |
        |                              v
        |                        4b. Generate Config
        |                              |
        |                              v
        |                        5b. Resolve Target Adapter
        |                              |
        |                              v
        |                        6b. Prepare Credentials
        |                              |
        |                              v
        |                        7b. Spawn via Adapter
        |
        +---> Settings/API ---> 3c. Load settings env
                                      |
                                      v
                                4c. Normalize legacy glmt if needed
                                      |
                                      v
                                5c. Resolve Target Adapter
                                      |
                                      v
                                6c. Spawn via Adapter

---

Provider Integration Architecture

For detailed provider flows (CLIProxyAPI, legacy GLMT compatibility, quota management), see Provider Flows.

---

Configuration Architecture

CCS Logging Architecture

• Shared logging contract lives in src/services/logging/ and is used for CCS-owned runtime diagnostics, request tracing, and bounded recent-entry reads.
• Config lives at top-level logging.* in ~/.ccs/config.yaml; cliproxy.logging.* still controls upstream CLIProxy runtime files only.
• CCS-owned runtime logs write to ~/.ccs/logs/current.jsonl and rotate into ~/.ccs/logs/archive/ based on policy.
• Dashboard exposure uses native /api/logs/config, /api/logs/sources, and /api/logs/entries endpoints plus the System -> Logs React page.
• Request logging explicitly skips /api/logs reads so the log viewer does not recursively log itself.

Config File Hierarchy

+===========================================================================+
|                     Configuration Hierarchy                                |
+===========================================================================+

  ~/.ccs/
    |
    +---> config.yaml              # Main CCS config (unified)
    |
    +---> profiles.json            # Claude account registry
    |
    +---> <profile>.settings.json  # Per-profile settings
    |
    +---> cliproxy/
    |       |
    |       +---> config.yaml      # CLIProxy configuration
    |       +---> auth/            # OAuth tokens
    |       +---> bin/             # CLIProxy binary
    |
    +---> shared/                  # Symlinked resources
            |
            +---> commands/        # Claude Code commands
            +---> skills/          # Custom skills
            +---> agents/          # Agent configurations
            +---> plugins/
                    |
                    +---> cache/               # Shared plugin payload/cache data
                    +---> marketplaces/        # Shared marketplace payload directories
                    +---> installed_plugins.json

  ~/.ccs/instances/<profile>/
    |
    +---> plugins/
            |
            +---> known_marketplaces.json      # Instance-local registry for active CLAUDE_CONFIG_DIR validation

  ~/.factory/ (Droid CLI)
    |
    +---> settings.json            # Droid config (custom models)

Plugin ownership note:

• commands/, skills/, agents/, and settings.json remain shared through the existing symlink/copy flow.
• Marketplace payload directories stay shared, but known_marketplaces.json is reconciled per instance so Claude Code can validate installLocation against that instance's CLAUDE_CONFIG_DIR/plugins/marketplaces.

Config Loading Order

  1. Environment Variables (highest priority)
        |
        v
  2. CLI Arguments (including --target)
        |
        v
  3. Profile-specific settings (~/.ccs/<profile>.settings.json)
        |
        v
  4. Main config (~/.ccs/config.yaml)
        |
        v
  5. Default values (lowest priority)

---

WebSocket Architecture

Real-time Communication

+===========================================================================+
|                     WebSocket Communication                                |
+===========================================================================+

  Dashboard (React)                     Server (Express)
        |                                      |
        |<------ Connection Established ------>|
        |                                      |
        |<------ health:update ----------------|  Health status
        |                                      |
        |<------ auth:status ------------------|  Auth changes
        |                                      |
        |<------ usage:update -----------------|  Usage stats
        |                                      |
        |------- action:refresh -------------->|  User requests
        |                                      |

---

Security Architecture

Authentication Flow

See Provider Flows → Authentication Flow section.

Security Boundaries

  +------------------+
  | User Terminal    |
  +------------------+
        |
        | Local only (no network exposure)
        v
  +------------------+
  | CCS CLI          |
  +------------------+
        |
        | Localhost only (127.0.0.1)
        v
  +------------------+
  | CLIProxy/Legacy  |  Binds to localhost only
  +------------------+
        |
        | TLS encrypted
        v
  +------------------+
  | Target CLI       |  Spawned locally (claude/droid)
  +------------------+
        |
        | TLS encrypted
        v
  +------------------+
  | Provider APIs    |  External endpoints
  +------------------+

---

Build and Distribution

Build Pipeline

+===========================================================================+
|                        Build Pipeline                                      |
+===========================================================================+

  src/ (TypeScript)                    ui/src/ (React TSX)
        |                                      |
        v                                      v
  TypeScript Compiler                  Vite Build
        |                                      |
        v                                      v
  dist/ (JavaScript)                   dist/ui/ (Static assets)
        |                                      |
        +---------------+---------------------+
                        |
                        v
               npm package (@kaitranntt/ccs)
                        |
                        v
               npm registry / GitHub releases

Package Contents

  @kaitranntt/ccs
        |
        +---> dist/           # Compiled CLI
        +---> dist/ui/        # Built dashboard
        +---> lib/            # Native scripts
        |       +---> ccs     # Bash bootstrap
        |       +---> ccs.ps1 # PowerShell bootstrap
        +---> package.json

---

Deployment Architecture

Local Installation

  npm install -g @kaitranntt/ccs
        |
        v
  Global node_modules
        |
        +---> Creates symlink: ccs --> dist/ccs.js
        |
        +---> Runtime aliases: ccs-droid / ccsd → ccs (auto-select droid target)
        |
        +---> First run creates: ~/.ccs/

PR Review Lane

Automated pull request review stays in .github/workflows/ai-review.yml, but the workflow now runs PR-Agent instead of the old Claude action. Reviews run on the existing self-hosted cliproxy runner, while the workflow preserves the existing AI_REVIEW_BASE_URL, AI_REVIEW_MODEL, and AI_REVIEW_API_KEY contract by mapping those values into PR-Agent env keys such as OPENAI.*, config.*, and github_action_config.*. Repo-specific reviewer guidance lives in .pr_agent.toml.

GitHub Actions `ai-review.yml`
      |
      v
Self-hosted `cliproxy` runner
      |
      v
PR-Agent action
      |
      v
CLIProxy
      |
      v
Configured model from `.pr_agent.toml`

• ai-review.yml owns automation wiring such as runner selection, PR-Agent action usage, and runtime values mapped from AI_REVIEW_* into OPENAI.*, config.*, and github_action_config.*.
• .pr_agent.toml in the repo root owns review instructions for this repository.
• Contributors should treat PR-Agent comments and trusted /review reruns as the primary AI review path for PRs targeting CCS.

Runtime Dependencies

  +------------------+     +------------------+
  |   Node.js 14+    |     |   Claude CLI     |
  |   (required)     |     |   (required)     |
  +------------------+     +------------------+

  +------------------+     +------------------+
  |   CLIProxyAPI    |     |   Droid CLI      |
  |   (auto-managed) |     |   (optional)     |
  +------------------+     +------------------+

---

Related Documentation

• Codebase Summary - Detailed directory structure
• Code Standards - Coding conventions & patterns
• Target Adapters - Multi-CLI adapter architecture
• Provider Flows - CLIProxy, legacy GLMT compatibility, authentication flows
• Project Roadmap - Development phases