mirror of
https://github.com/tiennm99/ccs.git
synced 2026-07-17 04:17:11 +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
280 lines
8.0 KiB
Markdown
280 lines
8.0 KiB
Markdown
# CCS Project Roadmap
|
|
|
|
Last Updated: 2025-12-19
|
|
|
|
Development roadmap documenting completed modularization phases and future work.
|
|
|
|
---
|
|
|
|
## Completed Phases
|
|
|
|
### Phase 1: Type System Modularization
|
|
|
|
**Status**: COMPLETE
|
|
|
|
Extracted TypeScript types into dedicated `types/` directory with barrel exports.
|
|
|
|
**Changes**:
|
|
- Created `src/types/` directory structure
|
|
- Extracted types from inline definitions into dedicated files:
|
|
- `config.ts` - Config, Settings, EnvVars
|
|
- `cli.ts` - ParsedArgs, ExitCode, ClaudeCliInfo
|
|
- `delegation.ts` - Session, execution types
|
|
- `glmt.ts` - Message transformation types
|
|
- `utils.ts` - ErrorCode, LogLevel, Result
|
|
- Created `index.ts` barrel export aggregating all types
|
|
|
|
**Impact**:
|
|
- Centralized type definitions
|
|
- Cleaner imports across codebase
|
|
- Easier type maintenance
|
|
|
|
---
|
|
|
|
### Phase 2: CLI Command Extraction
|
|
|
|
**Status**: COMPLETE
|
|
|
|
Extracted CLI command handlers from main `ccs.ts` into dedicated `commands/` directory.
|
|
|
|
**Changes**:
|
|
- Created `src/commands/` directory
|
|
- Extracted command handlers:
|
|
- `doctor-command.ts` - Health diagnostics
|
|
- `help-command.ts` - Help text generation
|
|
- `install-command.ts` - Install/uninstall logic
|
|
- `shell-completion-command.ts` - Shell completions
|
|
- `sync-command.ts` - Symlink synchronization
|
|
- `update-command.ts` - Self-update logic
|
|
- `version-command.ts` - Version display
|
|
- `cliproxy-command.ts` - CLIProxy subcommands (634 lines)
|
|
|
|
**Impact**:
|
|
- Reduced `ccs.ts` from ~1200 lines to 596 lines
|
|
- Isolated command logic for easier testing
|
|
- Clear separation of concerns
|
|
|
|
---
|
|
|
|
### Phase 3: CLIProxy Modularization
|
|
|
|
**Status**: COMPLETE
|
|
|
|
Heavily modularized the CLIProxy integration module with internal subdirectories.
|
|
|
|
**Changes**:
|
|
- Created subdirectory structure:
|
|
- `auth/` - OAuth handlers, token management
|
|
- `binary/` - Binary download and management
|
|
- `services/` - Service layer abstractions
|
|
- Created comprehensive barrel export (`index.ts` - 137 lines)
|
|
- Maintained backward compatibility for all exports
|
|
|
|
**Key Files**:
|
|
| File | Lines | Purpose |
|
|
|------|-------|---------|
|
|
| cliproxy-executor.ts | 666 | Main execution logic |
|
|
| config-generator.ts | 531 | Config file generation |
|
|
| account-manager.ts | 509 | Account management |
|
|
| auth-handler.ts | - | Authentication handling |
|
|
| proxy-detector.ts | - | Running proxy detection |
|
|
|
|
---
|
|
|
|
### Phase 4: Utility and Error Modularization
|
|
|
|
**Status**: COMPLETE
|
|
|
|
Extracted utilities and error handling into focused modules.
|
|
|
|
**Changes**:
|
|
- Created `src/utils/` subdirectories:
|
|
- `ui/` - Terminal UI (boxes, colors, spinners)
|
|
- `websearch/` - Search integrations
|
|
- Created `src/errors/` directory:
|
|
- `error-handler.ts` - Main error handling
|
|
- `exit-codes.ts` - Exit code definitions
|
|
- `cleanup.ts` - Cleanup logic
|
|
- Created `src/management/` directory:
|
|
- `checks/` - Diagnostic checks
|
|
- `repair/` - Auto-repair logic
|
|
|
|
---
|
|
|
|
### Phase 5: UI Components Modularization
|
|
|
|
**Status**: COMPLETE
|
|
|
|
Major UI refactoring splitting monster files into focused modules.
|
|
|
|
**Monster Files Split**:
|
|
|
|
| Original File | Lines | Split Into |
|
|
|---------------|-------|------------|
|
|
| account-flow-viz.tsx | 1,144 | 12 modules in `flow-viz/` |
|
|
| provider-editor.tsx | 921 | 13 modules in `provider-editor/` |
|
|
| copilot-config-form.tsx | 846 | 13 modules in `config-form/` |
|
|
| error-logs.tsx | 617 | 6 modules in `error-logs/` |
|
|
| profile-editor.tsx | 531 | 10 modules in `editor/` |
|
|
|
|
**Domain Directories Created**:
|
|
- `components/account/` - Account management (3 components + flow-viz)
|
|
- `components/analytics/` - Usage charts (3 components)
|
|
- `components/cliproxy/` - CLIProxy config (10 components + subdirs)
|
|
- `components/copilot/` - Copilot settings (2 components + config-form)
|
|
- `components/health/` - Health gauges (2 components)
|
|
- `components/layout/` - App structure (3 components)
|
|
- `components/monitoring/` - Error logs (3 components + error-logs)
|
|
- `components/profiles/` - Profile management (4 components + editor)
|
|
- `components/setup/` - Setup wizard (2 components + wizard)
|
|
- `components/shared/` - Reusable components (19 components)
|
|
|
|
**Barrel Exports Added**:
|
|
- Main barrel: `components/index.ts`
|
|
- Domain barrels: One `index.ts` per domain directory
|
|
- Subdirectory barrels: For split component directories
|
|
|
|
---
|
|
|
|
## Current Status
|
|
|
|
### Metrics
|
|
|
|
| Metric | Before | After | Change |
|
|
|--------|--------|-------|--------|
|
|
| Files > 500 lines | 12 | 7 | -42% |
|
|
| UI files > 200 lines | 28 | 14 | -50% |
|
|
| Barrel exports (CLI) | 5 | 24 | +380% |
|
|
| Barrel exports (UI) | 0 | 11 | New |
|
|
| Domain directories | 4 | 15 | +275% |
|
|
|
|
### Remaining Large Files
|
|
|
|
**CLI (Acceptable)**:
|
|
- `model-pricing.ts` (676 lines) - Data file
|
|
- `glmt-proxy.ts` (675 lines) - Complex proxy logic
|
|
- `cliproxy-executor.ts` (666 lines) - Core execution
|
|
- `ccs.ts` (596 lines) - Entry point
|
|
|
|
**UI (Need Attention)**:
|
|
- `pages/settings.tsx` (1,710 lines) - **HIGH PRIORITY SPLIT**
|
|
- `components/ui/sidebar.tsx` (674 lines) - shadcn component
|
|
- `monitoring/auth-monitor.tsx` (465 lines) - Could split
|
|
- `pages/analytics.tsx` (420 lines) - Could split
|
|
|
|
---
|
|
|
|
## Future Work
|
|
|
|
### Priority 1: Settings Page Split
|
|
|
|
**Target**: Split `pages/settings.tsx` (1,710 lines)
|
|
|
|
**Proposed Structure**:
|
|
```
|
|
pages/settings/
|
|
├── index.tsx # Main layout
|
|
├── general-section.tsx # General settings
|
|
├── appearance-section.tsx # Theme, colors
|
|
├── providers-section.tsx # Provider config
|
|
├── websearch-section.tsx # WebSearch config
|
|
├── advanced-section.tsx # Advanced options
|
|
├── hooks.ts # Shared hooks
|
|
└── types.ts # Settings types
|
|
```
|
|
|
|
### Priority 2: Analytics Page Split
|
|
|
|
**Target**: Split `pages/analytics.tsx` (420 lines)
|
|
|
|
**Proposed Structure**:
|
|
```
|
|
pages/analytics/
|
|
├── index.tsx # Main layout
|
|
├── usage-overview.tsx # Usage summary
|
|
├── model-breakdown.tsx # Per-model stats
|
|
├── cost-analysis.tsx # Cost tracking
|
|
└── hooks.ts # Data hooks
|
|
```
|
|
|
|
### Priority 3: Auth Monitor Split
|
|
|
|
**Target**: Split `monitoring/auth-monitor.tsx` (465 lines)
|
|
|
|
**Proposed Structure**:
|
|
```
|
|
monitoring/auth-monitor/
|
|
├── index.tsx # Main component
|
|
├── provider-status.tsx # Provider cards
|
|
├── token-display.tsx # Token info
|
|
├── refresh-controls.tsx # Refresh actions
|
|
└── hooks.ts # Auth hooks
|
|
```
|
|
|
|
### Priority 4: Test Coverage
|
|
|
|
**Target**: Add tests for modularized components
|
|
|
|
- Unit tests for extracted utilities
|
|
- Component tests for split UI modules
|
|
- Integration tests for barrel exports
|
|
- Snapshot tests for UI components
|
|
|
|
### Priority 5: Documentation
|
|
|
|
**Target**: Keep documentation synchronized
|
|
|
|
- Update codebase-summary.md on structural changes
|
|
- Document new patterns in code-standards.md
|
|
- Keep architecture diagrams current
|
|
- Add inline JSDoc comments
|
|
|
|
---
|
|
|
|
## Development Milestones
|
|
|
|
| Milestone | Status | Target Date |
|
|
|-----------|--------|-------------|
|
|
| Phase 1: Types | COMPLETE | - |
|
|
| Phase 2: Commands | COMPLETE | - |
|
|
| Phase 3: CLIProxy | COMPLETE | - |
|
|
| Phase 4: Utils/Errors | COMPLETE | - |
|
|
| Phase 5: UI Components | COMPLETE | - |
|
|
| Phase 6: Settings Split | PENDING | Q1 2026 |
|
|
| Phase 7: Remaining Splits | PENDING | Q1 2026 |
|
|
| Phase 8: Test Coverage | PENDING | Q2 2026 |
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
### Code Quality
|
|
|
|
- [ ] All files under 200 lines (except documented exceptions)
|
|
- [ ] Every directory has barrel export
|
|
- [ ] No circular dependencies
|
|
- [ ] TypeScript strict mode passing
|
|
|
|
### Maintainability
|
|
|
|
- [ ] Clear domain boundaries
|
|
- [ ] Consistent naming conventions
|
|
- [ ] Comprehensive documentation
|
|
- [ ] Easy navigation for new developers
|
|
|
|
### Developer Experience
|
|
|
|
- [ ] Fast build times
|
|
- [ ] Efficient tree-shaking
|
|
- [ ] Clear import paths
|
|
- [ ] Minimal cognitive load
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- [Codebase Summary](./codebase-summary.md) - Current structure
|
|
- [Code Standards](./code-standards.md) - Patterns and conventions
|
|
- [System Architecture](./system-architecture.md) - Architecture diagrams
|
|
- [CLAUDE.md](../CLAUDE.md) - AI development guidance
|