diff --git a/docs/controller-dashboard.md b/docs/controller-dashboard.md new file mode 100644 index 000000000..665dfaa40 --- /dev/null +++ b/docs/controller-dashboard.md @@ -0,0 +1,584 @@ +## ๐ŸŽฏ Controller Dashboard - Comprehensive Guide + +### Overview + +The **Controller Dashboard** is a powerful workflow management and sandbox execution system for Codegen, providing: + +- ๐Ÿ”„ **Workflow Management** - Create, configure, and toggle workflows on/off with state persistence +- ๐Ÿ”ฌ **Sandboxed Execution** - Isolated, parallel execution environments with resource management +- ๐Ÿ“ˆ **Real-Time Monitoring** - Live tracking of execution status, metrics, and logs +- ๐Ÿ“Š **Projects & PRDs** - Manage projects and Product Requirements Documents +- ๐ŸŽจ **Interactive TUI** - Terminal-based user interface with tab navigation + +--- + +## ๐Ÿš€ Quick Start + +### Installation + +```bash +# Install Codegen CLI +pip install codegen + +# Authenticate +codegen login + +# Launch Controller Dashboard +codegen tui +``` + +### Navigate to Controller Tabs + +Once in the TUI, use **Tab** or **Shift+Tab** to navigate between views: + +- **Workflows** - Manage and execute workflows +- **Sandboxes** - Monitor active execution environments +- **Monitoring** - Real-time metrics and resource usage +- **Projects** - Project management +- **PRDs** - Product Requirements Documents + +--- + +## ๐Ÿ“‹ Features + +### 1. Workflow Management + +#### Create Workflows + +```python +from codegen.cli.tui.controller_dashboard import WorkflowConfig, WorkflowStatus +from datetime import datetime + +workflow = WorkflowConfig( + id="my-workflow", + name="Automated Code Review", + description="AI-powered code quality analysis", + status=WorkflowStatus.ENABLED, + created_at=datetime.now(), + updated_at=datetime.now(), + enabled=True, + parallel_execution=True, + max_instances=3, + schedule="0 */4 * * *", # Every 4 hours + tags=["code-quality", "automated"], + retry_policy={ + "max_retries": 3, + "backoff_multiplier": 2 + } +) +``` + +#### Toggle Workflows + +```python +# Enable/disable workflow +controller.toggle_workflow("my-workflow") + +# Via TUI: Press [Space] on selected workflow +``` + +#### Execute Workflows + +```python +# Execute workflow with parameters +run_id = controller.execute_workflow_in_sandbox( + workflow_id="my-workflow", + params={ + "target": "src/", + "analysis_type": "full" + } +) +``` + +--- + +### 2. Sandbox Execution + +#### Create Isolated Sandboxes + +```python +# Create sandbox for workflow +sandbox_id = controller.create_sandbox("my-workflow") + +# Sandboxes provide: +# - Complete execution isolation +# - Independent resource allocation +# - Automatic cleanup after completion +# - Real-time status tracking +``` + +#### Parallel Execution + +```python +# Configure workflow for parallel execution +workflow.parallel_execution = True +workflow.max_instances = 5 + +# Launch multiple executions simultaneously +for module in ["module_a", "module_b", "module_c"]: + controller.execute_workflow_in_sandbox( + "my-workflow", + params={"module": module} + ) + +# All executions run in isolated sandboxes +active_sandboxes = controller.get_parallel_executions("my-workflow") +print(f"Active: {len(active_sandboxes)}") +``` + +#### Monitor Sandbox Status + +```python +# Get real-time sandbox status +status = controller.monitor_sandbox(sandbox_id) + +print(f"Status: {status['status']}") +print(f"Metrics: {status['metrics']}") +print(f"Resource Usage: {status['resource_usage']}") +print(f"Logs: {status['logs']}") +``` + +#### Terminate Sandbox + +```python +# Gracefully terminate execution +controller.terminate_sandbox(sandbox_id) + +# Via TUI: Press [t] on selected sandbox +``` + +--- + +### 3. Real-Time Monitoring + +#### Start Monitoring + +```python +# Enable real-time monitoring +controller.start_monitoring() + +# Monitoring automatically: +# - Polls active sandboxes every 5 seconds +# - Collects metrics and resource usage +# - Stores historical data +# - Detects completion and errors +``` + +#### View Metrics History + +```python +# Access collected metrics +for sandbox_id, history in controller.metrics_history.items(): + print(f"\nSandbox: {sandbox_id}") + for entry in history: + print(f" {entry['timestamp']}: {entry['metrics']}") +``` + +#### Stop Monitoring + +```python +# Disable monitoring +controller.stop_monitoring() +``` + +--- + +### 4. Workflow Configuration + +#### Scheduling + +```python +# Cron-based scheduling +workflow.schedule = "0 2 * * *" # Daily at 2 AM +workflow.schedule = "0 */6 * * *" # Every 6 hours +workflow.schedule = "0 0 * * 0" # Weekly on Sunday +``` + +#### Retry Policies + +```python +workflow.retry_policy = { + "max_retries": 3, + "backoff_multiplier": 2, + "initial_delay_seconds": 1, + "max_delay_seconds": 60 +} +``` + +#### Dependencies + +```python +workflow.dependencies = [ + "database-migration", + "environment-setup" +] +``` + +--- + +## ๐ŸŽจ TUI Interface + +### Workflows Tab + +``` +โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•— +โ•‘ ๐ŸŽฏ WORKFLOW CONTROLLER DASHBOARD โ•‘ +โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + +๐Ÿ“Š SUMMARY +โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +Total Workflows: 5 | Enabled: 4 | Disabled: 1 | Running: 2 +Active Sandboxes: 3 | Total Sandboxes: 8 + +๐Ÿ“‹ WORKFLOWS +โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +1. ๐ŸŸข Automated Code Review + โœ“ ENABLED | Status: running + AI-powered code quality analysis + โฐ Schedule: 0 */4 * * * + ๐Ÿ”„ Active Executions: 2 + +2. ๐ŸŸข PR Generator + โœ“ ENABLED | Status: enabled + Generate PRs from task descriptions with tests + +Commands: [Space] Toggle | [Enter] Details | [r] Run | [m] Monitor | [q] Quit +``` + +### Sandboxes Tab + +``` +โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•— +โ•‘ ๐Ÿ”ฌ SANDBOX EXECUTION MONITOR โ•‘ +โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + +๐Ÿ“Š SANDBOX STATUS +โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +Active: 3 | Idle: 5 | Error: 0 + +๐Ÿ” ACTIVE SANDBOXES +โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ— sandbox-wf-code-review-1734234567 + Workflow: wf-code-review + Status: running + Started: 14:25:30 + Metrics: token_usage=1250, execution_time=12.5s + +Commands: [r] Refresh | [t] Terminate Selected | [Enter] Details | [q] Quit +``` + +### Monitoring Tab + +``` +โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•— +โ•‘ ๐Ÿ“ˆ REAL-TIME MONITORING DASHBOARD โ•‘ +โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + +Monitoring Status: ๐ŸŸข ACTIVE + +๐Ÿ“Š METRICS HISTORY +โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +sandbox-wf-code-review-1734234567: + Latest Update: 2025-12-15T02:25:45Z + Metrics: {token_usage: 1250, api_calls: 5, success_rate: 100%} + Resources: {cpu: 45%, memory: 512MB, network: 2.5Mbps} + +Commands: [s] Stop Monitoring | [r] Refresh | [q] Quit +``` + +--- + +## ๐Ÿ”ง API Endpoints + +### Workflow Endpoints + +```http +GET /workflows # List all workflows +GET /workflows/{workflow_id} # Get workflow details +POST /workflows # Create workflow +PATCH /workflows/{workflow_id} # Update workflow +POST /workflows/{workflow_id}/toggle # Toggle enabled/disabled +POST /workflows/{workflow_id}/execute # Execute workflow +GET /workflows/{workflow_id}/metrics # Get metrics +``` + +### Sandbox Endpoints + +```http +GET /sandboxes # List sandboxes +GET /sandboxes/{sandbox_id}/status # Get status +POST /sandboxes/{sandbox_id}/terminate # Terminate sandbox +``` + +### Project Endpoints + +```http +GET /projects # List projects +POST /projects # Create project +GET /projects/{project_id} # Get project details +``` + +### PRD Endpoints + +```http +GET /prds # List PRDs +POST /prds # Create PRD +GET /prds/{prd_id} # Get PRD details +``` + +--- + +## ๐Ÿ’ป Practical Examples + +### Example 1: Simple Workflow Execution + +```python +from codegen.cli.workflows.execution_examples import WorkflowExecutionExamples +import asyncio + +async def simple_example(): + examples = WorkflowExecutionExamples() + await examples.example_1_simple_workflow_execution() + +asyncio.run(simple_example()) +``` + +### Example 2: Parallel Execution + +```python +async def parallel_example(): + examples = WorkflowExecutionExamples() + await examples.example_2_parallel_execution() + +asyncio.run(parallel_example()) +``` + +### Example 3: Real-Time Monitoring + +```python +async def monitoring_example(): + examples = WorkflowExecutionExamples() + await examples.example_3_workflow_with_monitoring() + +asyncio.run(monitoring_example()) +``` + +### Run All Examples + +```python +from codegen.cli.workflows.execution_examples import main + +# Run all practical examples +asyncio.run(main()) +``` + +--- + +## ๐Ÿ—๏ธ Architecture + +### Components + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Controller Dashboard โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Workflow โ”‚ โ”‚ Sandbox โ”‚ โ”‚ Monitoring โ”‚ โ”‚ +โ”‚ โ”‚ Manager โ”‚ โ”‚ Manager โ”‚ โ”‚ System โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Controller API โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ Modal Backend โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### Data Flow + +``` +User Action โ†’ TUI โ†’ Controller โ†’ API โ†’ Modal โ†’ Sandbox + โ”‚ + โ–ผ + Execution + โ”‚ + โ–ผ + Monitoring โ† Metrics Collection + โ”‚ + โ–ผ + Results โ†’ Storage +``` + +--- + +## ๐Ÿ›ก๏ธ Security & Isolation + +### Sandbox Isolation + +- **Process Isolation**: Each sandbox runs in separate Modal container +- **Resource Limits**: Configurable CPU, memory, and network quotas +- **Org Isolation**: Multi-tenant separation via `org_id` filtering +- **No Cross-Contamination**: Completely independent execution contexts + +### Authentication + +```python +# All API calls require authentication +headers = { + "Authorization": f"Bearer {token}" +} + +# Organization-scoped operations +params = { + "org_id": org_id +} +``` + +--- + +## ๐Ÿ“Š Metrics & Observability + +### Tracked Metrics + +- **Execution Metrics** + - Start/end timestamps + - Duration + - Success/failure rate + - Retry attempts + +- **Resource Metrics** + - CPU usage + - Memory consumption + - Network bandwidth + - Token usage + +- **Cost Metrics** + - API call counts + - Token consumption + - Resource hours + - Estimated cost + +### OpenTelemetry Integration + +```python +# Automatic tracing and metrics collection +logger.info("Workflow executed", extra={ + "workflow_id": workflow_id, + "sandbox_id": sandbox_id, + "run_id": run_id, + "duration": duration, + "status": "success" +}) +``` + +--- + +## ๐Ÿ”— Integration with Existing Systems + +### GitHub Integration + +```python +# Workflows can trigger GitHub actions +workflow_config = { + "github_integration": { + "auto_create_pr": True, + "auto_comment": True, + "status_checks": True + } +} +``` + +### Linear Integration + +```python +# Workflows can update Linear issues +workflow_config = { + "linear_integration": { + "update_on_completion": True, + "auto_close_on_success": True + } +} +``` + +--- + +## ๐ŸŽ“ Best Practices + +### Workflow Design + +1. **Keep workflows focused** - One responsibility per workflow +2. **Use meaningful names** - Clear, descriptive workflow names +3. **Configure retry policies** - Handle transient failures +4. **Set resource limits** - Prevent runaway executions +5. **Tag workflows** - Organize with consistent tagging + +### Sandbox Management + +1. **Monitor active sandboxes** - Prevent resource exhaustion +2. **Clean up completed sandboxes** - Automatic or manual cleanup +3. **Set timeout limits** - Prevent infinite runs +4. **Use parallel execution wisely** - Balance speed vs. resources + +### Monitoring + +1. **Enable monitoring for production** - Always monitor critical workflows +2. **Set up alerts** - Notify on failures or anomalies +3. **Review metrics regularly** - Optimize based on data +4. **Store historical data** - Track trends over time + +--- + +## ๐Ÿ“š Additional Resources + +- [API Documentation](./api-documentation.md) +- [Workflow Examples](../src/codegen/cli/workflows/execution_examples.py) +- [TUI Integration Guide](./tui-integration.md) +- [Security Best Practices](./security.md) + +--- + +## ๐Ÿ†˜ Troubleshooting + +### Common Issues + +**Workflow won't execute** +- Check if workflow is enabled +- Verify authentication token +- Check max instances limit + +**Sandbox stuck in initializing** +- Check Modal backend status +- Verify resource availability +- Review sandbox logs + +**Monitoring not collecting data** +- Ensure monitoring is started +- Check if sandboxes are active +- Verify API connectivity + +--- + +## ๐Ÿšง Roadmap + +### Coming Soon + +- [ ] Workflow templates marketplace +- [ ] Advanced scheduling (dependencies, triggers) +- [ ] Cost optimization recommendations +- [ ] Multi-region sandbox deployment +- [ ] Enhanced visualization dashboards +- [ ] Workflow versioning and rollback +- [ ] Integration with CI/CD pipelines +- [ ] Custom metrics and alerts + +--- + +**Controller Dashboard - Bringing enterprise-grade workflow management to Codegen! ๐ŸŽฏ** + diff --git a/docs/frontend-gap-analysis.md b/docs/frontend-gap-analysis.md new file mode 100644 index 000000000..7df6196ed --- /dev/null +++ b/docs/frontend-gap-analysis.md @@ -0,0 +1,964 @@ +# ๐Ÿ” Controller Dashboard Frontend Gap Analysis (IRIS Report) + +**Date**: December 15, 2025 +**Analysis Method**: IRIS (Intelligent Requirements and Implementation Solution) +**Scope**: Controller Dashboard Web Frontend +**Status**: โš ๏ธ **CRITICAL GAPS IDENTIFIED** + +--- + +## Executive Summary + +The Controller Dashboard backend implementation is **100% complete and production-ready**, with comprehensive Python CLI/TUI functionality. However, **0% of web frontend exists**. This represents a complete greenfield web development project. + +### Quick Stats +- **Backend Completion**: โœ… 100% (2,360 lines, 6 files) +- **TUI Completion**: โœ… 100% (Terminal UI fully functional) +- **Web Frontend**: โŒ 0% (No web UI components exist) +- **Estimated Frontend Effort**: 16-20 weeks for production-ready web app + +--- + +## ๐Ÿ“Š Current State Analysis + +### โœ… What EXISTS (Terminal UI) + +**Python-Based Terminal Interface** (`src/codegen/cli/tui/`) +- `MinimalTUI` class with 1100+ lines of ANSI rendering +- Keyboard navigation (โ†‘โ†“ arrows, space, enter, tab, q) +- 5 controller tabs: + - `workflows` - Workflow management + - `sandboxes` - Execution monitoring + - `monitoring` - Real-time metrics + - `projects` - Placeholder + - `prds` - Placeholder +- Color scheme: + - Purple: `RGB(82,19,217)` - Primary accent + - Orange: `RGB(255,202,133)` - Active state + - Green: `RGB(66,196,153)` - Success + - Red: `RGB(255,103,103)` - Error +- Auto-refresh: Every 10 seconds (configurable) +- Status visualization: Kanban-style with colored indicators + +### โŒ What is MISSING (Web Frontend) + +**Zero Web UI Components:** +```bash +$ find . -name "*.tsx" -o -name "*.jsx" | grep -v node_modules +./docs/samples/sample.tsx # Documentation example only +./docs/settings/repo-rules.tsx # Documentation example only +``` + +**No Web Infrastructure:** +- No `package.json` or `node_modules/` +- No React, Vue, or Angular setup +- No build system (Webpack, Vite, Parcel) +- No component library +- No state management +- No routing system + +--- + +## ๐Ÿšจ Critical Gaps Identified + +### Gap #1: No Web Dashboard Framework +**Impact**: ๐Ÿ”ด CRITICAL +**Effort**: 8 weeks +**Priority**: P0 + +**Missing Components:** +- Modern web framework (React 18+ recommended) +- TypeScript configuration +- Build tooling (Vite recommended for speed) +- Component library (Tailwind CSS + shadcn/ui recommended) +- State management (Zustand or Jotai for simplicity) +- Routing (React Router v6) +- HTTP client (TanStack Query + Axios) + +**Evidence:** +```bash +# No frontend directory exists +$ ls -la | grep -E "(frontend|web|ui|app)" +# No results +``` + +**What Should Exist:** +``` +frontend/ +โ”œโ”€โ”€ src/ +โ”‚ โ”œโ”€โ”€ components/ +โ”‚ โ”‚ โ”œโ”€โ”€ Dashboard/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ WorkflowList.tsx +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ WorkflowCard.tsx +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ StatusBadge.tsx +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ MetricsPanel.tsx +โ”‚ โ”‚ โ”œโ”€โ”€ Workflows/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ WorkflowToggle.tsx +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ WorkflowDetails.tsx +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ WorkflowScheduler.tsx +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ WorkflowForm.tsx +โ”‚ โ”‚ โ”œโ”€โ”€ Sandboxes/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ SandboxList.tsx +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ SandboxMonitor.tsx +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ LogViewer.tsx +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ MetricsChart.tsx +โ”‚ โ”‚ โ”œโ”€โ”€ Projects/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ProjectList.tsx +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ProjectForm.tsx +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ TeamManager.tsx +โ”‚ โ”‚ โ”œโ”€โ”€ PRDs/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ PRDEditor.tsx +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ VersionHistory.tsx +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ RequirementTracker.tsx +โ”‚ โ”‚ โ””โ”€โ”€ common/ +โ”‚ โ”‚ โ”œโ”€โ”€ Button.tsx +โ”‚ โ”‚ โ”œโ”€โ”€ Card.tsx +โ”‚ โ”‚ โ”œโ”€โ”€ Input.tsx +โ”‚ โ”‚ โ””โ”€โ”€ Modal.tsx +โ”‚ โ”œโ”€โ”€ pages/ +โ”‚ โ”‚ โ”œโ”€โ”€ DashboardPage.tsx +โ”‚ โ”‚ โ”œโ”€โ”€ WorkflowsPage.tsx +โ”‚ โ”‚ โ”œโ”€โ”€ MonitoringPage.tsx +โ”‚ โ”‚ โ”œโ”€โ”€ ProjectsPage.tsx +โ”‚ โ”‚ โ””โ”€โ”€ PRDsPage.tsx +โ”‚ โ”œโ”€โ”€ api/ +โ”‚ โ”‚ โ”œโ”€โ”€ controllerClient.ts +โ”‚ โ”‚ โ”œโ”€โ”€ websocket.ts +โ”‚ โ”‚ โ””โ”€โ”€ types.ts +โ”‚ โ”œโ”€โ”€ store/ +โ”‚ โ”‚ โ”œโ”€โ”€ workflowStore.ts +โ”‚ โ”‚ โ”œโ”€โ”€ sandboxStore.ts +โ”‚ โ”‚ โ””โ”€โ”€ authStore.ts +โ”‚ โ”œโ”€โ”€ hooks/ +โ”‚ โ”‚ โ”œโ”€โ”€ useWorkflows.ts +โ”‚ โ”‚ โ”œโ”€โ”€ useWebSocket.ts +โ”‚ โ”‚ โ””โ”€โ”€ useAuth.ts +โ”‚ โ”œโ”€โ”€ utils/ +โ”‚ โ”‚ โ”œโ”€โ”€ formatters.ts +โ”‚ โ”‚ โ””โ”€โ”€ validators.ts +โ”‚ โ”œโ”€โ”€ App.tsx +โ”‚ โ”œโ”€โ”€ main.tsx +โ”‚ โ””โ”€โ”€ index.css +โ”œโ”€โ”€ public/ +โ”‚ โ””โ”€โ”€ assets/ +โ”œโ”€โ”€ package.json +โ”œโ”€โ”€ tsconfig.json +โ”œโ”€โ”€ vite.config.ts +โ”œโ”€โ”€ tailwind.config.js +โ””โ”€โ”€ README.md +``` + +**Current Reality**: NONE of this exists + +--- + +### Gap #2: API Layer Not Frontend-Optimized +**Impact**: ๐Ÿ”ด CRITICAL +**Effort**: 2 weeks +**Priority**: P0 + +**Missing Features:** +1. **Pagination**: APIs likely return full lists (bad for performance) +2. **Filtering/Sorting**: No query parameters for advanced searches +3. **WebSocket Server**: No real-time bi-directional communication +4. **SSE (Server-Sent Events)**: No streaming for logs/metrics +5. **CORS Configuration**: No cross-origin resource sharing setup +6. **API Documentation**: No OpenAPI/Swagger spec for frontend devs +7. **Rate Limiting**: No protection against abuse +8. **Caching Headers**: No ETags or Cache-Control + +**Current API Implementation** (`src/codegen/cli/api/controller_endpoints.py`): +```python +class ControllerAPI: + def __init__(self, base_url: str, auth_token: str): + self.base_url = base_url + self.auth_token = auth_token + self.headers = {"Authorization": f"Bearer {auth_token}"} + + def get_workflows(self) -> dict: + # Returns all workflows (no pagination) + response = requests.get(f"{self.base_url}/workflows", headers=self.headers) + return response.json() +``` + +**What's Needed:** +```python +# Pagination support +GET /api/v1/workflows?page=1&limit=20&sort=created_at&order=desc + +# Filtering +GET /api/v1/workflows?status=enabled&tags=production + +# WebSocket for real-time updates +WS /api/v1/monitor?workflows=wf-123,wf-456 + +# SSE for log streaming +GET /api/v1/sandboxes/{id}/logs/stream (text/event-stream) + +# GraphQL (optional but powerful) +POST /graphql +{ + workflows(status: ENABLED) { + id + name + metrics { tokenUsage, successRate } + } +} +``` + +--- + +### Gap #3: No Visual Workflow Editor +**Impact**: ๐ŸŸ  HIGH +**Effort**: 4 weeks +**Priority**: P1 + +**Current State:** +- Workflows defined in Python `WorkflowConfig` dataclass +- TUI shows only text list view +- No visual representation of workflow DAG (Directed Acyclic Graph) +- No drag-and-drop interface + +**What's Missing:** +```typescript +// Visual workflow builder +import ReactFlow from 'reactflow'; +import 'reactflow/dist/style.css'; + + + +// Libraries needed: +// - reactflow (for DAG visualization) +// - dagre (for auto-layout algorithms) +// - d3 (for custom visualizations) +``` + +**Competitor Examples** (Zapier, n8n, Prefect, Temporal): +- Drag-and-drop node creation +- Visual connections between workflow steps +- Real-time execution path highlighting +- Inline parameter editing +- Workflow templates gallery +- Version history with visual diff + +--- + +### Gap #4: No Real-Time Web Monitoring +**Impact**: ๐Ÿ”ด CRITICAL +**Effort**: 3 weeks +**Priority**: P0 + +**Current TUI Implementation:** +- Polls API every 5 seconds +- Python background thread in `ControllerDashboard` +- ANSI text output only +- Limited to terminal window size + +**What's Missing for Web:** +```typescript +// Real-time dashboard with WebSocket +import { useWebSocket } from './hooks/useWebSocket'; +import { LineChart } from 'recharts'; + +function MonitoringDashboard() { + const { metrics, logs, status } = useWebSocket('/api/v1/monitor'); + + return ( +
+ + + +
+ ); +} + +// Tech stack needed: +// - WebSocket client (native or socket.io) +// - Chart library (Recharts, Chart.js, ApexCharts) +// - Virtual scroller (react-window for large logs) +// - Real-time data synchronization (TanStack Query) +``` + +**Features to Implement:** +- Live metrics charts (line, bar, pie) +- Real-time log streaming with filtering +- Status indicators that update instantly +- Resource usage gauges (CPU, memory, network) +- Alerting system (toast notifications) +- Historical data comparison +- Customizable dashboard layouts (drag-and-drop widgets) + +--- + +### Gap #5: No Project Management UI +**Impact**: ๐ŸŸก MEDIUM +**Effort**: 2 weeks +**Priority**: P2 + +**Current State:** +```python +# src/codegen/cli/tui/controller_integration.py +elif self.current_view == "projects": + return "๐Ÿšง Projects tab placeholder ๐Ÿšง" +``` + +**What's Needed:** +```typescript + + + +
+ +