mirror of
https://github.com/tiennm99/ccs.git
synced 2026-07-17 06:17:09 +00:00
kaitranntt
1ffd169b98
Add five documentation files reflecting Phase 5 UI modularization: - codebase-summary.md: Complete directory structure for CLI and UI - code-standards.md: 200-line file limit, barrel exports, naming conventions - system-architecture.md: ASCII architecture diagrams and data flows - project-roadmap.md: Completed phases 1-5, future work - project-overview-pdr.md: Product development requirements
226 lines
5.8 KiB
Markdown
226 lines
5.8 KiB
Markdown
# CCS Product Development Requirements (PDR)
|
|
|
|
Last Updated: 2025-12-19
|
|
|
|
## Product Overview
|
|
|
|
**Product Name**: CCS (Claude Code Switch)
|
|
|
|
**Tagline**: The universal AI profile manager for Claude Code
|
|
|
|
**Description**: CLI wrapper enabling seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex) with a React-based dashboard for configuration management.
|
|
|
|
---
|
|
|
|
## Problem Statement
|
|
|
|
Developers using Claude Code face these challenges:
|
|
|
|
1. **Single Account Limitation**: Cannot run multiple Claude subscriptions simultaneously
|
|
2. **Provider Lock-in**: Stuck with Anthropic's API, cannot use alternatives
|
|
3. **No Concurrent Sessions**: Cannot work on different projects with different accounts
|
|
4. **Complex Configuration**: Manual env var and config file management
|
|
|
|
---
|
|
|
|
## Solution
|
|
|
|
CCS provides:
|
|
|
|
1. **Multi-Account Claude**: Isolated instances via `CLAUDE_CONFIG_DIR`
|
|
2. **OAuth Providers**: Zero-config Gemini, Codex, Antigravity integration
|
|
3. **API Profiles**: GLM, Kimi, any Anthropic-compatible API
|
|
4. **Visual Dashboard**: React SPA for configuration management
|
|
5. **Automatic WebSearch**: MCP fallback for third-party providers
|
|
|
|
---
|
|
|
|
## Target Users
|
|
|
|
| User Type | Use Case | Primary Features |
|
|
|-----------|----------|------------------|
|
|
| Individual Developer | Work/personal separation | Multi-account Claude |
|
|
| Agency/Contractor | Client account isolation | Profile switching |
|
|
| Cost-conscious Dev | GLM for bulk operations | API profiles |
|
|
| Enterprise | Custom LLM integration | OpenAI-compatible endpoints |
|
|
|
|
---
|
|
|
|
## Functional Requirements
|
|
|
|
### FR-001: Profile Switching
|
|
- Switch between profiles with `ccs <profile>` command
|
|
- Support default profile when no argument provided
|
|
- Pass through all Claude CLI arguments
|
|
|
|
### FR-002: Multi-Account Claude
|
|
- Create isolated Claude instances
|
|
- Maintain separate sessions, todolists, logs per account
|
|
- Share commands, skills, agents across accounts
|
|
|
|
### FR-003: OAuth Provider Integration
|
|
- Support Gemini, Codex, Antigravity OAuth flows
|
|
- Browser-based authentication
|
|
- Token caching and refresh
|
|
|
|
### FR-004: API Profile Management
|
|
- Configure custom API endpoints
|
|
- Support Anthropic-compatible APIs
|
|
- Model mapping and configuration
|
|
|
|
### FR-005: Dashboard UI
|
|
- Visual profile management
|
|
- Real-time health monitoring
|
|
- Usage analytics
|
|
|
|
### FR-006: Health Diagnostics
|
|
- Verify Claude CLI installation
|
|
- Check config file integrity
|
|
- Validate symlinks and permissions
|
|
|
|
### FR-007: WebSearch Fallback
|
|
- Auto-configure MCP web search for third-party profiles
|
|
- Support Gemini CLI, Brave, Tavily providers
|
|
- Graceful fallback chain
|
|
|
|
---
|
|
|
|
## Non-Functional Requirements
|
|
|
|
### NFR-001: Performance
|
|
- CLI startup < 100ms
|
|
- Dashboard load < 2s
|
|
- Minimal memory footprint
|
|
|
|
### NFR-002: Reliability
|
|
- Idempotent operations
|
|
- Graceful error handling
|
|
- Automatic recovery where possible
|
|
|
|
### NFR-003: Security
|
|
- Local-only proxy binding (127.0.0.1)
|
|
- No credential exposure in logs
|
|
- Secure token storage
|
|
|
|
### NFR-004: Cross-Platform
|
|
- Support Linux, macOS, Windows
|
|
- Bash 3.2+, PowerShell 5.1+, Node.js 14+
|
|
- Identical behavior across platforms
|
|
|
|
### NFR-005: Maintainability
|
|
- Files < 200 lines
|
|
- Domain-based organization
|
|
- Barrel exports for clean imports
|
|
|
|
---
|
|
|
|
## Technical Requirements
|
|
|
|
### TR-001: Runtime Dependencies
|
|
- Node.js 14+ or Bun 1.0+
|
|
- Claude Code CLI installed
|
|
- Internet access for OAuth/API calls
|
|
|
|
### TR-002: Optional Dependencies
|
|
- CLIProxyAPI binary (auto-managed)
|
|
- Gemini CLI for WebSearch
|
|
- Additional MCP servers
|
|
|
|
### TR-003: Configuration
|
|
- YAML-based config (`~/.ccs/config.yaml`)
|
|
- JSON settings per profile
|
|
- Environment variable overrides
|
|
|
|
---
|
|
|
|
## Architecture Constraints
|
|
|
|
### AC-001: CLI-First Design
|
|
- All features accessible via CLI
|
|
- Dashboard is convenience layer, not required
|
|
- Scriptable and automatable
|
|
|
|
### AC-002: Non-Invasive
|
|
- Never modify `~/.claude/settings.json`
|
|
- Use environment variables for configuration
|
|
- Reversible changes only
|
|
|
|
### AC-003: Proxy Pattern
|
|
- Use local proxy for provider routing
|
|
- Claude CLI communicates with localhost
|
|
- Proxy handles upstream API calls
|
|
|
|
---
|
|
|
|
## Success Metrics
|
|
|
|
| Metric | Target | Current |
|
|
|--------|--------|---------|
|
|
| Startup time | < 100ms | TBD |
|
|
| Dashboard load | < 2s | TBD |
|
|
| Error rate | < 1% | TBD |
|
|
| Test coverage | > 80% | TBD |
|
|
| File size compliance | 100% < 200 lines | 85% |
|
|
|
|
---
|
|
|
|
## Release Criteria
|
|
|
|
### v1.0 Release (Current)
|
|
- [x] Multi-account Claude support
|
|
- [x] OAuth provider integration (Gemini, Codex, AGY)
|
|
- [x] API profile management
|
|
- [x] Dashboard UI
|
|
- [x] Health diagnostics
|
|
- [x] WebSearch fallback
|
|
- [x] Cross-platform support
|
|
|
|
### v1.1 Release (Planned)
|
|
- [ ] Settings page modularization
|
|
- [ ] Enhanced analytics
|
|
- [ ] Profile templates
|
|
- [ ] Improved error messages
|
|
|
|
### v2.0 Release (Future)
|
|
- [ ] Team collaboration features
|
|
- [ ] Cloud sync for profiles
|
|
- [ ] Plugin system
|
|
- [ ] CLI extension framework
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
### External Services
|
|
- Anthropic Claude API
|
|
- Google Gemini API
|
|
- GitHub Codex API
|
|
- Z.AI GLM API
|
|
|
|
### Third-Party Libraries
|
|
- Express.js (web server)
|
|
- React (dashboard)
|
|
- Vite (build tool)
|
|
- shadcn/ui (UI components)
|
|
- CLIProxyAPI (proxy binary)
|
|
|
|
---
|
|
|
|
## Risks and Mitigations
|
|
|
|
| Risk | Probability | Impact | Mitigation |
|
|
|------|-------------|--------|------------|
|
|
| Claude CLI API changes | Medium | High | Version pinning, compatibility layer |
|
|
| Provider API deprecation | Low | High | Fallback chain, multiple providers |
|
|
| OAuth token expiry | Medium | Medium | Auto-refresh, clear error messages |
|
|
| Binary compatibility | Low | Medium | Multi-platform builds, fallback |
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- [Codebase Summary](./codebase-summary.md) - Technical structure
|
|
- [Code Standards](./code-standards.md) - Development conventions
|
|
- [System Architecture](./system-architecture.md) - Architecture diagrams
|
|
- [Project Roadmap](./project-roadmap.md) - Development phases
|