ccs/docs/codebase-summary.md

# CCS Codebase Summary

## Overview

CCS (Claude Code Switch) is a TypeScript-based CLI tool that provides instant profile switching between multiple AI models (Claude Sonnet 4.5, GLM 4.6, GLMT, and Kimi). The project features a comprehensive architecture with TypeScript source, React UI dashboard, cross-platform shell scripts, and extensive automation. Current version includes a modern React 19 dashboard with real-time WebSocket integration, Vite build system, and shadcn/ui components.

## Repository Structure

```
ccs/
├── src/                      # TypeScript source code (43 files)
│   ├── ccs.ts               # Main entry point (593 lines)
│   ├── commands/            # Modular command handlers (7 files)
│   ├── auth/                # Authentication system (3 files)
│   ├── cliproxy/            # CLIProxy integration (6 files)
│   ├── delegation/          # AI delegation system (6 files)
│   ├── glmt/                # GLMT thinking mode (7 files)
│   ├── management/          # System management (5 files)
│   ├── utils/               # Utilities (6 files)
│   └── types/               # TypeScript definitions (6 files)
├── ui/                      # React 19 Dashboard (Vite + shadcn/ui)
│   ├── src/
│   │   ├── App.tsx          # Main React app
│   │   ├── components/      # UI components
│   │   │   ├── ui/          # shadcn/ui components
│   │   │   └── *.tsx        # Custom components
│   │   ├── hooks/           # React hooks
│   │   ├── lib/             # Utilities
│   │   └── pages/           # Route pages
│   ├── public/              # Static assets
│   ├── package.json         # Dependencies
│   └── vite.config.ts       # Vite configuration
├── lib/                     # Cross-platform scripts
│   ├── ccs                  # Bash bootstrap
│   └── ccs.ps1              # PowerShell bootstrap
├── scripts/                 # Build and automation
│   ├── build.js             # TypeScript compilation
│   ├── postinstall.js       # Auto-configuration
│   └── sync-version.js      # Version sync
├── tests/                   # Test suites
│   ├── unit/                # Unit tests
│   ├── npm/                 # Package tests
│   └── native/              # Native install tests
└── docs/                    # Documentation
    ├── project-overview-pdr.md
    ├── code-standards.md
    ├── system-architecture.md
    └── project-roadmap.md
```

## Key Components

### TypeScript Core (src/)

1. **Main Entry Point** (`src/ccs.ts`)
   - Command parsing and routing
   - Profile detection logic
   - Delegation flag handling (`-p`)
   - GLMT proxy lifecycle management

2. **Modular Commands** (`src/commands/`)
   - `version-command.ts`: Version display
   - `help-command.ts`: Comprehensive help system
   - `install-command.ts`: Installation workflows
   - `doctor-command.ts`: System diagnostics
   - `sync-command.ts`: Configuration synchronization
   - `shell-completion-command.ts`: Shell completion
   - `update-command.ts`: Version updates with beta channel support

3. **Authentication System** (`src/auth/`)
   - Profile detection and validation
   - Multi-account management
   - Profile registry operations

4. **CLIProxy Integration** (`src/cliproxy/`)
   - OAuth-based provider integration
   - Binary manager for cliproxy executables, including the new **version pin feature** (see Recent Changes)
   - Auth handler for OAuth flows
   - **Model Catalog**: Manages available models (Gemini, Codex, AGY, Qwen, Iflow)

5. **AI Delegation** (`src/delegation/`)
   - Headless Claude execution
   - Stream-JSON parsing
   - Real-time tool tracking
   - Session persistence

6. **GLMT System** (`src/glmt/`)
   - HTTP proxy for thinking mode
   - Format transformation (Anthropic ↔ OpenAI)
   - Reasoning content handling
   - Debug logging

7. **Management** (`src/management/`)
   - System diagnostics
   - Instance management
   - Shared data management
   - Recovery operations

8. **Utilities** (`src/utils/`)
   - Cross-platform helpers
   - Shell execution
   - Package manager detection
   - Update checking

### React Dashboard (ui/)

**Technology Stack**:
- React 19 with TypeScript
- Vite for fast development and building
- shadcn/ui component library (Radix UI + Tailwind)
- TanStack Query for server state
- Real-time WebSocket integration
- Dark mode support

**Key Pages**:
- Dashboard: Overview, status, usage analytics, CLIProxy controls, and system health monitoring
- API Profiles: Model configuration
- CLIProxy: OAuth provider setup
- Accounts: Account management
- Health: System diagnostics
- Settings: Configuration
- Shared: Data sharing management

**Components**:
- Modern UI with responsive design
- Real-time updates via WebSocket
- Professional theme with consistent styling
- Accessibility-compliant components

### Cross-Platform Scripts (lib/)

1. **Bash Bootstrap** (`lib/ccs`)
   - Entrypoint for Unix/macOS
   - Delegates to Node.js via npx
   - Argument passthrough support

2. **PowerShell Bootstrap** (`lib/ccs.ps1`)
   - Windows PowerShell support
   - Parameter splatting for arguments
   - Cross-platform parity with bash

### Build & Automation (scripts/)

1. **Build System**
   - TypeScript compilation to dist/
   - Source maps and declarations
   - Linting and formatting

2. **Post-Installation**
   - Auto-configuration creation
   - Directory structure setup
   - Migration for version upgrades

3. **Quality Gates**
   - Type checking (strict mode)
   - ESLint validation
   - Test execution
   - Code formatting

## Technology Stack

### Core Technologies
- **TypeScript 5.3+**: 100% type coverage, zero `any` types
- **Node.js 14+**: Runtime environment
- **Bun**: Package manager (10-25x faster than npm)
- **React 19**: Modern UI with concurrent features
- **Vite**: Fast build tool and dev server

### UI Libraries
- **shadcn/ui**: Modern component library
- **Radix UI**: Accessible component primitives
- **Tailwind CSS**: Utility-first styling
- **Lucide React**: Icon library
- **React Router**: Client-side routing
- **TanStack Query**: Server state management

### Development Tools
- **ESLint**: Code linting with strict rules
- **Prettier**: Code formatting
- **Mocha**: Test framework
- **Chai**: Assertion library
- **Semantic Release**: Automated versioning

## Key Features

### Profile Management
- **Settings-based profiles**: glm, glmt, kimi
- **Account-based profiles**: work, personal
- **CLIProxy providers**: OAuth-based integration
- **Instant switching**: Zero-downtime profile changes

### AI Delegation System
- **Headless execution**: `-p` flag for delegation
- **Real-time tracking**: 13+ Claude Code tools
- **Stream-JSON parsing**: Live tool visibility
- **Session persistence**: `:continue` support
- **Cost tracking**: Usage statistics

### GLMT Thinking Mode
- **Embedded proxy**: HTTP server for format conversion
- **Reasoning support**: GLM 4.6 with thinking blocks
- **Debug logging**: File-based logging with timestamps
- **Configuration**: Temperature, max tokens, timeouts

### Web Dashboard
- **Real-time UI**: WebSocket for live updates
- **Modern interface**: Responsive, accessible design
- **Configuration**: Visual profile and settings management
- **Health monitoring**: System diagnostics dashboard
- **Dark mode**: Theme switching support

### Cross-Platform Support
- **Universal**: macOS, Linux, Windows
- **Shell completion**: Bash, Zsh, Fish, PowerShell
- **Consistent behavior**: Unified across platforms
- **Windows fallbacks**: Copy when symlinks unavailable

### Development Workflow
- **TypeScript strict**: Maximum type safety
- **Automated releases**: Semantic versioning
- **Quality gates**: Pre-commit validation
- **Comprehensive tests**: Unit, integration, native

## Recent Changes

### Version Pin Feature (Issue #88)
- **Description**: Users can now explicitly pin a specific version of CLIProxy using `ccs cliproxy --install <version>`. This creates a `.version-pin` file, preventing automatic updates and ensuring stability for specific project requirements.

### Profile Persistence Fix (Issue #82)
- **Description**: Relaxed configuration validation rules to prevent unintended data loss when handling user profiles, improving robustness and user experience.

### UI Dashboard Capabilities
- **Description**: The web-based UI now provides comprehensive dashboard functionalities, including usage analytics, CLIProxy controls, and system health monitoring, enhancing user visibility and control.

### Multi-Provider Support
- **Description**: The CLIProxy now supports multiple AI model providers, including Gemini, Codex, AGY, Qwen, and Iflow, offering greater flexibility and choice for users.

### Unified Config System
- **Description**: A consolidated configuration system ensures consistent management of settings, feature flags, and secrets across the CLI and its components.

## Architecture Patterns

### Modular Design
- **Single responsibility**: Each module focused
- **Clear interfaces**: TypeScript contracts
- **Dependency injection**: Testable architecture
- **Error boundaries**: Graceful error handling

### Configuration Management
- **Unified Config System**: Consolidated management of settings, feature flags, and secrets across the CLI and its components (see Recent Changes).
- **Shared data**: Symlinks for commands, skills, agents
- **Isolated state**: Profile-specific sessions, logs
- **Auto-recovery**: Self-healing configurations
- **Migration support**: Seamless upgrades

### Performance Optimization
- **Lazy loading**: On-demand initialization
- **Stream processing**: Real-time parsing
- **Minimal overhead**: Direct CLI execution
- **Efficient builds**: Vite and Bun optimization

## Statistics (as of v4.5.0)

- **Total files**: 163 files
- **TypeScript files**: 43 source files
- **Lines of code**: ~8,000 lines TypeScript
- **Test coverage**: 90%+ critical paths
- **Platform support**: 3 OS (macOS, Linux, Windows)
- **Shell completions**: 4 shells supported
- **AI models**: 4+ models integrated
- **Languages**: TypeScript, React, Bash, PowerShell

## Development Standards

### Code Quality
- **Zero any types**: 100% type coverage
- **Strict ESLint**: All errors enforced
- **Pre-commit hooks**: Automated validation
- **Semantic releases**: Automated versioning

### Testing Strategy
- **Unit tests**: Module isolation
- **Integration tests**: Cross-module flows
- **Platform tests**: OS-specific behavior
- **Native tests**: Shell script validation

### Documentation
- **Living docs**: Updated with releases
- **Code examples**: Real usage patterns
- **Architecture docs**: System design
- **API references**: Complete coverage

## Future Roadmap

### v4.6-v4.7 (UI Enhancements)
- Sidebar redesign with modern UX
- Enhanced dashboard visualizations
- Real-time collaboration features
- Mobile-responsive improvements

### v5.0+ (Next Generation)
- AI-powered automation
- Plugin system
- Enterprise features
- Ecosystem expansion

This codebase demonstrates a mature, well-architected TypeScript application with modern React UI, comprehensive testing, and cross-platform support. The modular design enables easy maintenance and extension while maintaining high quality standards.