mirror of
https://github.com/tiennm99/ccs.git
synced 2026-07-16 06:16:37 +00:00
Tam Nhu Tran
7d7054e2c0
Implement target adapter pattern enabling CCS CLI to support multiple backend targets (Claude, Droid) via pluggable adapters. Core additions: - TargetAdapter interface for pluggable target implementations - ClaudeAdapter and DroidAdapter concrete implementations - Target registry (singleton Map-based storage) - Target resolver with precedence: --target flag > per-profile config > busybox detection - Droid config manager with atomic writes and file locking to ~/.factory/settings.json - Droid binary detector to validate runtime environment - Adapter dispatch integrated into ccs.ts main execution flow - ccsd busybox alias for seamless Droid invocation - --target flag documentation in help - Session tracking enriched with target metadata - Dashboard target badge for visual identification Testing: - 43 unit tests covering resolver, registry, config manager, and adapters - Full coverage of target detection logic and edge cases Documentation: - Refactored system-architecture.md into modular docs/system-architecture/ subdirectory - Updated code-standards.md with target adapter guidelines - Updated codebase-summary.md with architecture overview - Updated maintainability baseline (33.8% → 35.2%) This establishes extensible foundation for multi-target support without breaking existing Claude workflows. Droid adapter is production-ready but defaults to Claude for backward compatibility.
12 KiB
12 KiB
CCS System Architecture
Last Updated: 2026-02-16
High-level architecture overview for the CCS (Claude Code Switch) system.
System Overview
CCS is a CLI wrapper that enables seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex, Kiro, GitHub Copilot, OpenRouter, Qwen, Kimi, DeepSeek). It now supports multiple CLI targets (Claude Code, Factory Droid) for credential delivery.
The system consists of two main components:
- CLI Application (
src/) - Node.js TypeScript CLI - Dashboard UI (
ui/) - React web application served by Express
CCS v7.34 adds Image Analysis Hook for vision model proxying through CLIProxy with automatic injection for all profile types.
+===========================================================================+
| CCS System |
+===========================================================================+
| |
| +------------------+ +-----------------+ +----------------+ |
| | User Terminal | ---> | CCS CLI | ---> | Target CLI | |
| | (ccs command) | | (src/ccs.ts) | | (claude/droid) | |
| +------------------+ +-----------------+ +----------------+ |
| | | |
| 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, GLMT, Account-based)
|
v
Target Resolution (--target flag > config > argv[0] > default)
|
v
Get Target Adapter (Claude or Droid)
|
+---> 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
- Writes custom model entry:
Binary alias pattern (busybox-style):
ccs → Target: claude (default)
ccsd → Target: droid (auto-selected via argv[0])
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()
| |
+---> [GLMT Profile] ---> execClaudeWithProxy()
|
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
|
+---> GLMT -----------> 3c. Start Embedded Proxy
|
v
4c. Resolve Target Adapter
|
v
5c. Spawn via Adapter
Provider Integration Architecture
For detailed provider flows (CLIProxyAPI, GLMT, quota management), see Provider Flows.
Configuration Architecture
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
~/.factory/ (Droid CLI)
|
+---> settings.json # Droid config (custom models)
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/GLMT | 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
|
+---> Binary alias: ccsd → ccs (auto-selects droid target)
|
+---> First run creates: ~/.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, GLMT, authentication flows
- Project Roadmap - Development phases