[Phase 2] Server audit and refactor - routes delegating to core modules

[frankbria]

Overview

Audit the existing FastAPI server and refactor all routes to delegate logic to core.* modules. The server should be a thin adapter, not contain business logic.

Background

Per the v2 architecture principle:

CLI (typer) ─┬── core.* ─── adapters.*
             │
Server (fastapi) ─┘

Server and CLI are siblings, both calling core. This ensures:

• No duplicate logic between CLI and server
• Server can be optional (CLI-first philosophy)
• Easier testing (test core once, not twice)

Deliverables

1. Route Audit

• Inventory all routes in codeframe/server/ and codeframe/ui/routers/
• For each route, document: current logic location, target core module
• Identify routes with inline business logic that needs extraction

2. Core Module Mapping

Ensure each CLI command has a corresponding core function that the server can also call:

CLI Command	Core Module	Server Route
cf init	core.workspace	POST /api/workspaces
cf prd add	core.prd	POST /api/projects/{id}/prd
cf prd generate	core.prd_discovery	POST /api/projects/{id}/prd/generate
cf tasks generate	core.tasks	POST /api/projects/{id}/tasks/generate
cf work start	core.runtime	POST /api/tasks/{id}/start
cf work follow	core.streaming	GET /api/tasks/{id}/stream
cf blocker answer	core.blockers	POST /api/blockers/{id}/answer
...	...	...

3. Refactor Pattern

For each route:

# Before (inline logic)
@router.post("/tasks/{task_id}/start")
async def start_task(task_id: str):
    task = db.get_task(task_id)
    task.status = "IN_PROGRESS"
    db.save(task)
    return {"status": "started"}

# After (delegate to core)
@router.post("/tasks/{task_id}/start")
async def start_task(task_id: str):
    from codeframe.core import runtime
    result = await runtime.start_task_run(task_id)
    return result

4. Route Consistency

• One route per CLI command (1:1 mapping)
• Consistent URL patterns: /api/{resource}/{id}/{action}
• Consistent response formats

Acceptance Criteria

• All routes delegate to core.* modules
• No business logic in route handlers (only request parsing, response formatting)
• Route audit document created
• Integration tests pass with refactored routes

Related Issues

• [Phase 2] Complete OpenAPI documentation for all endpoints #119 - OpenAPI documentation (depends on route consistency)
• [Phase 2] Add API pagination support for large datasets #118 - API pagination
• [Phase 2] Implement API Rate Limiting for Security #167 - Rate limiting

References

• docs/V2_STRATEGIC_ROADMAP.md - Phase 2 requirements
• docs/CLI_WIREFRAME.md - CLI command → module mapping

[traycerai]

Plan

Observations

The codebase has a well-established v2 architecture with clear separation between CLI (file:codeframe/cli/app.py) and core modules (file:codeframe/core/). The server layer (file:codeframe/ui/server.py and file:codeframe/ui/routers/) currently contains mixed patterns: some routes delegate to core modules (e.g., file:codeframe/ui/routers/blockers.py uses file:codeframe/core/blockers.py), while others contain inline business logic (e.g., file:codeframe/ui/routers/tasks.py has multi-agent execution logic, file:codeframe/ui/routers/discovery.py has PRD generation logic). The CLI already demonstrates proper delegation to core modules like file:codeframe/core/prd.py, file:codeframe/core/tasks.py, file:codeframe/core/runtime.py, and file:codeframe/core/workspace.py.

Approach

The refactor will follow a systematic audit-then-refactor pattern, ensuring all server routes become thin adapters that delegate to core modules, matching the CLI's architecture. The approach prioritizes identifying routes with inline business logic, extracting that logic to appropriate core modules, and establishing 1:1 mapping between CLI commands and server routes as documented in file:docs/CLI_WIREFRAME.md. This maintains the v2 architecture principle where CLI and server are siblings both calling core, ensuring the server remains optional and the CLI-first philosophy is preserved.

Implementation Plan

1. Route Audit and Documentation

Objective: Create comprehensive inventory of all routes and their current implementation patterns.

Steps:

1. Inventory all routes across file:codeframe/ui/routers/ directory:

   • file:codeframe/ui/routers/agents.py
   • file:codeframe/ui/routers/blockers.py
   • file:codeframe/ui/routers/chat.py
   • file:codeframe/ui/routers/checkpoints.py
   • file:codeframe/ui/routers/context.py
   • file:codeframe/ui/routers/discovery.py
   • file:codeframe/ui/routers/git.py
   • file:codeframe/ui/routers/lint.py
   • file:codeframe/ui/routers/metrics.py
   • file:codeframe/ui/routers/projects.py
   • file:codeframe/ui/routers/prs.py
   • file:codeframe/ui/routers/quality_gates.py
   • file:codeframe/ui/routers/review.py
   • file:codeframe/ui/routers/schedule.py
   • file:codeframe/ui/routers/session.py
   • file:codeframe/ui/routers/tasks.py
   • file:codeframe/ui/routers/templates.py
   • file:codeframe/ui/routers/websocket.py
   • file:codeframe/auth/router.py

2. Classify each route into three categories:

   • Already delegating: Routes that properly call core modules (e.g., file:codeframe/ui/routers/blockers.py → file:codeframe/core/blockers.py)
   • Needs extraction: Routes with inline business logic requiring extraction to core
   • No CLI equivalent: Routes specific to server/UI functionality (WebSocket, auth)

3. Create audit document with table format:

Route	HTTP Method	Current Logic Location	Target Core Module	CLI Command Equivalent	Priority
/api/projects	POST	Inline in projects.py	core.workspace	cf init	HIGH
/api/projects/{id}/prd	GET	Database direct	core.prd	cf prd show	HIGH
/api/projects/{id}/discovery/answer	POST	Inline in discovery.py	core.prd_discovery	cf prd generate	CRITICAL
/api/tasks	POST	Inline in tasks.py	core.tasks	cf tasks generate	HIGH
/api/tasks/{id}/start	POST	Inline in tasks.py	core.runtime	cf work start	CRITICAL
/api/blockers/{id}/resolve	POST	Delegates to core.blockers	✓ Already correct	cf blocker answer	✓ DONE

2. Core Module Mapping and Gap Analysis

Objective: Ensure all required core functionality exists to support server routes.

Steps:

1. Map CLI commands to core modules using file:docs/CLI_WIREFRAME.md as reference:

   • cf init → core.workspace.create_or_load()
   • cf prd add → core.prd.store()
   • cf prd generate → core.prd_discovery.start_discovery_session() (needs creation)
   • cf tasks generate → core.tasks.generate_from_prd()
   • cf work start → core.runtime.start_task_run()
   • cf work follow → core.streaming.stream_task_output() (needs creation)
   • cf blocker answer → core.blockers.answer()
   • cf checkpoint create → core.checkpoints.create()

2. Identify missing core modules:

   • file:codeframe/core/prd_discovery.py - Interactive PRD generation (referenced in roadmap)
   • file:codeframe/core/streaming.py - Real-time output streaming (exists, verify completeness)
   • Any other gaps discovered during audit

3. Verify existing core modules have necessary functions:

   • file:codeframe/core/workspace.py - workspace creation/loading
   • file:codeframe/core/prd.py - PRD CRUD operations
   • file:codeframe/core/tasks.py - task generation and management
   • file:codeframe/core/runtime.py - task execution orchestration
   • file:codeframe/core/blockers.py - blocker management
   • file:codeframe/core/checkpoints.py - state snapshots

3. Extract Inline Business Logic to Core Modules

Objective: Move business logic from routes to core modules.

Priority Order (based on criticality):

3.1 HIGH PRIORITY: Discovery and PRD Generation

Current State: file:codeframe/ui/routers/discovery.py contains:

• generate_prd_background() - PRD generation logic
• generate_planning_background() - Issue/task generation logic
• Direct LeadAgent instantiation and orchestration

Target State:

• Extract to file:codeframe/core/prd_discovery.py (or enhance existing file:codeframe/core/prd.py)
• Create functions:
  • start_discovery_session(workspace_id) -> DiscoverySession
  • process_discovery_answer(session_id, answer) -> DiscoverySession
  • generate_prd_from_discovery(session_id) -> PrdRecord
  • generate_issues_from_prd(prd_id) -> list[Issue]
  • decompose_prd_to_tasks(prd_id) -> list[Task]

Route Refactor:

• POST /api/projects/{id}/discovery/answer → calls core.prd_discovery.process_discovery_answer()
• POST /api/projects/{id}/discovery/generate-prd → calls core.prd_discovery.generate_prd_from_discovery()
• POST /api/projects/{id}/discovery/generate-tasks → calls core.prd_discovery.decompose_prd_to_tasks()

3.2 HIGH PRIORITY: Task Execution

Current State: file:codeframe/ui/routers/tasks.py contains:

• start_development_execution() - Multi-agent execution orchestration
• Direct LeadAgent instantiation
• Background task management

Target State:

• Verify file:codeframe/core/runtime.py has:
  • start_task_run(workspace_id, task_id) -> Run
  • resume_task_run(workspace_id, task_id) -> Run
  • stop_task_run(workspace_id, task_id) -> Run
  • start_multi_agent_execution(workspace_id, task_ids) -> BatchRun

Route Refactor:

• POST /api/tasks/{id}/start → calls core.runtime.start_task_run()
• POST /api/projects/{id}/tasks/approve → calls core.runtime.start_multi_agent_execution()
• POST /api/projects/{id}/tasks/assign → calls core.runtime.start_multi_agent_execution()

3.3 MEDIUM PRIORITY: Project Management

Current State: file:codeframe/ui/routers/projects.py contains:

• Project creation with workspace setup
• Direct database operations
• Workspace manager calls

Target State:

• Enhance file:codeframe/core/workspace.py with:
  • create_workspace(name, description, source_config) -> Workspace
  • get_workspace_status(workspace_id) -> WorkspaceStatus
  • calculate_project_progress(workspace_id) -> ProgressMetrics

Route Refactor:

• POST /api/projects → calls core.workspace.create_workspace()
• GET /api/projects/{id}/status → calls core.workspace.get_workspace_status()

3.4 MEDIUM PRIORITY: Session Management

Current State: file:codeframe/ui/routers/projects.py has session endpoint using SessionManager directly

Target State:

• Verify file:codeframe/core/session_manager.py is properly abstracted
• Ensure no HTTP-specific logic in session management

Route Refactor:

• GET /api/projects/{id}/session → calls core.session_manager.load_session()

4. Establish Route Consistency

Objective: Ensure consistent URL patterns and response formats.

Standards:

1. URL Pattern: /api/{resource}/{id}/{action}

   • Resources: projects, tasks, blockers, checkpoints, prds
   • Actions: start, stop, resume, approve, resolve

2. Response Format:

   {
     "success": true,
     "data": { ... },
     "message": "Optional human-readable message"
   }

3. Error Format:

   {
     "error": "Error description",
     "detail": "Additional context",
     "code": "ERROR_CODE"
   }

Review and Update:

• Audit all routes for consistency
• Update response models in file:codeframe/ui/models.py
• Ensure all routes use dependency injection for Database and WorkspaceManager

5. Route-to-CLI Mapping Verification

Objective: Ensure 1:1 mapping between CLI commands and server routes.

Create mapping table:

CLI Command	Core Module	Core Function	Server Route	HTTP Method
cf init	core.workspace	create_or_load()	/api/workspaces	POST
cf prd add	core.prd	store()	/api/projects/{id}/prd	POST
cf prd generate	core.prd_discovery	start_discovery_session()	/api/projects/{id}/discovery/start	POST
cf prd show	core.prd	get_latest()	/api/projects/{id}/prd	GET
cf tasks generate	core.tasks	generate_from_prd()	/api/projects/{id}/tasks/generate	POST
cf tasks list	core.tasks	list_tasks()	/api/projects/{id}/tasks	GET
cf work start	core.runtime	start_task_run()	/api/tasks/{id}/start	POST
cf work resume	core.runtime	resume_task_run()	/api/tasks/{id}/resume	POST
cf work stop	core.runtime	stop_task_run()	/api/tasks/{id}/stop	POST
cf work follow	core.streaming	stream_task_output()	/api/tasks/{id}/stream	GET (SSE)
cf blocker list	core.blockers	list_open()	/api/projects/{id}/blockers	GET
cf blocker answer	core.blockers	answer()	/api/blockers/{id}/resolve	POST
cf checkpoint create	core.checkpoints	create()	/api/projects/{id}/checkpoints	POST
cf checkpoint restore	core.checkpoints	restore()	/api/checkpoints/{id}/restore	POST

Identify gaps:

• Missing routes for existing CLI commands
• Routes without CLI equivalents (document as server-only)

6. Refactor Pattern Implementation

For each route requiring refactor:

1. Before (example from file:codeframe/ui/routers/tasks.py):

@router.post("/tasks/{task_id}/start")
async def start_task(
    task_id: str,
    db: Database = Depends(get_db),
):
    # Inline business logic
    task = db.get_task(task_id)
    task.status = "IN_PROGRESS"
    db.save(task)
    
    # Direct agent instantiation
    agent = LeadAgent(...)
    result = await agent.start_execution()
    
    return {"status": "started"}

2. After (delegating to core):

@router.post("/tasks/{task_id}/start")
async def start_task(
    task_id: str,
    db: Database = Depends(get_db),
    current_user: User = Depends(get_current_user),
):
    from codeframe.core import runtime
    from codeframe.core.workspace import get_workspace
    
    # Authorization check
    task = db.get_task(task_id)
    if not db.user_has_project_access(current_user.id, task.project_id):
        raise HTTPException(status_code=403, detail="Access denied")
    
    # Get workspace
    project = db.get_project(task.project_id)
    workspace = get_workspace(project["workspace_path"])
    
    # Delegate to core
    run = runtime.start_task_run(workspace, task_id)
    
    # Return response
    return {
        "success": True,
        "data": {
            "run_id": run.id,
            "task_id": task_id,
            "status": run.status
        }
    }

Apply pattern to all routes:

• Extract business logic to core modules
• Keep only request parsing, authorization, and response formatting in routes
• Use dependency injection for database and workspace manager
• Maintain consistent error handling

7. Integration Testing

Objective: Ensure refactored routes maintain functionality.

Test Strategy:

1. Verify existing integration tests in file:tests/cli/test_v2_cli_integration.py still pass

2. Create server integration tests for refactored routes:

   • Test each route with valid inputs
   • Test authorization checks
   • Test error handling
   • Verify core module delegation

3. Test CLI-Server equivalence:

   • Same core function called by both CLI and server
   • Same results produced
   • Same state changes

8. Documentation Updates

Update documentation:

1. Route audit document - Final mapping of all routes to core modules
2. API documentation - Update OpenAPI specs (relates to issue [Phase 2] Complete OpenAPI documentation for all endpoints #119)
3. Architecture documentation - Update file:docs/V2_STRATEGIC_ROADMAP.md with completion status
4. Developer guide - Document the thin adapter pattern for future route additions

9. Acceptance Criteria Verification

Verify all criteria met:

• All routes delegate to core.* modules
• No business logic in route handlers (only request parsing, response formatting, authorization)
• Route audit document created and complete
• Integration tests pass with refactored routes
• 1:1 mapping between CLI commands and server routes established
• Consistent URL patterns across all routes
• Consistent response formats across all routes
• Server remains optional (CLI works independently)

Architecture Diagram

sequenceDiagram
    participant Client as Web Client
    participant Route as FastAPI Route
    participant Core as Core Module
    participant DB as Database
    participant Adapter as Adapter (LLM/Git)

    Client->>Route: POST /api/tasks/{id}/start
    Route->>Route: Parse request
    Route->>Route: Authorize user
    Route->>Core: runtime.start_task_run(workspace, task_id)
    Core->>DB: Get task details
    DB-->>Core: Task data
    Core->>Core: Validate state transition
    Core->>Adapter: Initialize agent
    Adapter-->>Core: Agent ready
    Core->>DB: Update task status
    Core->>Adapter: Start execution
    Core-->>Route: Run object
    Route->>Route: Format response
    Route-->>Client: {"success": true, "data": {...}}

Loading

Refactor Sequence

graph TD
    A[1. Route Audit] --> B[2. Core Module Mapping]
    B --> C[3. Extract Discovery Logic]
    B --> D[3. Extract Task Execution Logic]
    B --> E[3. Extract Project Management Logic]
    C --> F[4. Establish Route Consistency]
    D --> F
    E --> F
    F --> G[5. Verify CLI-Route Mapping]
    G --> H[6. Apply Refactor Pattern]
    H --> I[7. Integration Testing]
    I --> J[8. Documentation Updates]
    J --> K[9. Acceptance Criteria Check]

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a well-established v2 architecture with clear separation between CLI (`file:codeframe/cli/app.py`) and core modules (`file:codeframe/core/`). The server layer (`file:codeframe/ui/server.py` and `file:codeframe/ui/routers/`) currently contains mixed patterns: some routes delegate to core modules (e.g., `file:codeframe/ui/routers/blockers.py` uses `file:codeframe/core/blockers.py`), while others contain inline business logic (e.g., `file:codeframe/ui/routers/tasks.py` has multi-agent execution logic, `file:codeframe/ui/routers/discovery.py` has PRD generation logic). The CLI already demonstrates proper delegation to core modules like `file:codeframe/core/prd.py`, `file:codeframe/core/tasks.py`, `file:codeframe/core/runtime.py`, and `file:codeframe/core/workspace.py`.

## Approach

The refactor will follow a systematic audit-then-refactor pattern, ensuring all server routes become thin adapters that delegate to core modules, matching the CLI's architecture. The approach prioritizes identifying routes with inline business logic, extracting that logic to appropriate core modules, and establishing 1:1 mapping between CLI commands and server routes as documented in `file:docs/CLI_WIREFRAME.md`. This maintains the v2 architecture principle where CLI and server are siblings both calling core, ensuring the server remains optional and the CLI-first philosophy is preserved.

## Implementation Plan

### 1. Route Audit and Documentation

**Objective:** Create comprehensive inventory of all routes and their current implementation patterns.

**Steps:**

1. **Inventory all routes** across `file:codeframe/ui/routers/` directory:
   - `file:codeframe/ui/routers/agents.py`
   - `file:codeframe/ui/routers/blockers.py`
   - `file:codeframe/ui/routers/chat.py`
   - `file:codeframe/ui/routers/checkpoints.py`
   - `file:codeframe/ui/routers/context.py`
   - `file:codeframe/ui/routers/discovery.py`
   - `file:codeframe/ui/routers/git.py`
   - `file:codeframe/ui/routers/lint.py`
   - `file:codeframe/ui/routers/metrics.py`
   - `file:codeframe/ui/routers/projects.py`
   - `file:codeframe/ui/routers/prs.py`
   - `file:codeframe/ui/routers/quality_gates.py`
   - `file:codeframe/ui/routers/review.py`
   - `file:codeframe/ui/routers/schedule.py`
   - `file:codeframe/ui/routers/session.py`
   - `file:codeframe/ui/routers/tasks.py`
   - `file:codeframe/ui/routers/templates.py`
   - `file:codeframe/ui/routers/websocket.py`
   - `file:codeframe/auth/router.py`

2. **Classify each route** into three categories:
   - **Already delegating:** Routes that properly call core modules (e.g., `file:codeframe/ui/routers/blockers.py` → `file:codeframe/core/blockers.py`)
   - **Needs extraction:** Routes with inline business logic requiring extraction to core
   - **No CLI equivalent:** Routes specific to server/UI functionality (WebSocket, auth)

3. **Create audit document** with table format:

| Route | HTTP Method | Current Logic Location | Target Core Module | CLI Command Equivalent | Priority |
|-------|-------------|------------------------|-------------------|----------------------|----------|
| `/api/projects` | POST | Inline in `projects.py` | `core.workspace` | `cf init` | HIGH |
| `/api/projects/{id}/prd` | GET | Database direct | `core.prd` | `cf prd show` | HIGH |
| `/api/projects/{id}/discovery/answer` | POST | Inline in `discovery.py` | `core.prd_discovery` | `cf prd generate` | CRITICAL |
| `/api/tasks` | POST | Inline in `tasks.py` | `core.tasks` | `cf tasks generate` | HIGH |
| `/api/tasks/{id}/start` | POST | Inline in `tasks.py` | `core.runtime` | `cf work start` | CRITICAL |
| `/api/blockers/{id}/resolve` | POST | Delegates to `core.blockers` | ✓ Already correct | `cf blocker answer` | ✓ DONE |

### 2. Core Module Mapping and Gap Analysis

**Objective:** Ensure all required core functionality exists to support server routes.

**Steps:**

1. **Map CLI commands to core modules** using `file:docs/CLI_WIREFRAME.md` as reference:
   - `cf init` → `core.workspace.create_or_load()`
   - `cf prd add` → `core.prd.store()`
   - `cf prd generate` → `core.prd_discovery.start_discovery_session()` (needs creation)
   - `cf tasks generate` → `core.tasks.generate_from_prd()`
   - `cf work start` → `core.runtime.start_task_run()`
   - `cf work follow` → `core.streaming.stream_task_output()` (needs creation)
   - `cf blocker answer` → `core.blockers.answer()`
   - `cf checkpoint create` → `core.checkpoints.create()`

2. **Identify missing core modules:**
   - `file:codeframe/core/prd_discovery.py` - Interactive PRD generation (referenced in roadmap)
   - `file:codeframe/core/streaming.py` - Real-time output streaming (exists, verify completeness)
   - Any other gaps discovered during audit

3. **Verify existing core modules** have necessary functions:
   - `file:codeframe/core/workspace.py` - workspace creation/loading
   - `file:codeframe/core/prd.py` - PRD CRUD operations
   - `file:codeframe/core/tasks.py` - task generation and management
   - `file:codeframe/core/runtime.py` - task execution orchestration
   - `file:codeframe/core/blockers.py` - blocker management
   - `file:codeframe/core/checkpoints.py` - state snapshots

### 3. Extract Inline Business Logic to Core Modules

**Objective:** Move business logic from routes to core modules.

**Priority Order (based on criticality):**

#### 3.1 HIGH PRIORITY: Discovery and PRD Generation

**Current State:** `file:codeframe/ui/routers/discovery.py` contains:
- `generate_prd_background()` - PRD generation logic
- `generate_planning_background()` - Issue/task generation logic
- Direct `LeadAgent` instantiation and orchestration

**Target State:**
- Extract to `file:codeframe/core/prd_discovery.py` (or enhance existing `file:codeframe/core/prd.py`)
- Create functions:
  - `start_discovery_session(workspace_id) -> DiscoverySession`
  - `process_discovery_answer(session_id, answer) -> DiscoverySession`
  - `generate_prd_from_discovery(session_id) -> PrdRecord`
  - `generate_issues_from_prd(prd_id) -> list[Issue]`
  - `decompose_prd_to_tasks(prd_id) -> list[Task]`

**Route Refactor:**
- `POST /api/projects/{id}/discovery/answer` → calls `core.prd_discovery.process_discovery_answer()`
- `POST /api/projects/{id}/discovery/generate-prd` → calls `core.prd_discovery.generate_prd_from_discovery()`
- `POST /api/projects/{id}/discovery/generate-tasks` → calls `core.prd_discovery.decompose_prd_to_tasks()`

#### 3.2 HIGH PRIORITY: Task Execution

**Current State:** `file:codeframe/ui/routers/tasks.py` contains:
- `start_development_execution()` - Multi-agent execution orchestration
- Direct `LeadAgent` instantiation
- Background task management

**Target State:**
- Verify `file:codeframe/core/runtime.py` has:
  - `start_task_run(workspace_id, task_id) -> Run`
  - `resume_task_run(workspace_id, task_id) -> Run`
  - `stop_task_run(workspace_id, task_id) -> Run`
  - `start_multi_agent_execution(workspace_id, task_ids) -> BatchRun`

**Route Refactor:**
- `POST /api/tasks/{id}/start` → calls `core.runtime.start_task_run()`
- `POST /api/projects/{id}/tasks/approve` → calls `core.runtime.start_multi_agent_execution()`
- `POST /api/projects/{id}/tasks/assign` → calls `core.runtime.start_multi_agent_execution()`

#### 3.3 MEDIUM PRIORITY: Project Management

**Current State:** `file:codeframe/ui/routers/projects.py` contains:
- Project creation with workspace setup
- Direct database operations
- Workspace manager calls

**Target State:**
- Enhance `file:codeframe/core/workspace.py` with:
  - `create_workspace(name, description, source_config) -> Workspace`
  - `get_workspace_status(workspace_id) -> WorkspaceStatus`
  - `calculate_project_progress(workspace_id) -> ProgressMetrics`

**Route Refactor:**
- `POST /api/projects` → calls `core.workspace.create_workspace()`
- `GET /api/projects/{id}/status` → calls `core.workspace.get_workspace_status()`

#### 3.4 MEDIUM PRIORITY: Session Management

**Current State:** `file:codeframe/ui/routers/projects.py` has session endpoint using `SessionManager` directly

**Target State:**
- Verify `file:codeframe/core/session_manager.py` is properly abstracted
- Ensure no HTTP-specific logic in session management

**Route Refactor:**
- `GET /api/projects/{id}/session` → calls `core.session_manager.load_session()`

### 4. Establish Route Consistency

**Objective:** Ensure consistent URL patterns and response formats.

**Standards:**

1. **URL Pattern:** `/api/{resource}/{id}/{action}`
   - Resources: `projects`, `tasks`, `blockers`, `checkpoints`, `prds`
   - Actions: `start`, `stop`, `resume`, `approve`, `resolve`

2. **Response Format:**
   ```json
   {
     "success": true,
     "data": { ... },
     "message": "Optional human-readable message"
   }
   ```

3. **Error Format:**
   ```json
   {
     "error": "Error description",
     "detail": "Additional context",
     "code": "ERROR_CODE"
   }
   ```

**Review and Update:**
- Audit all routes for consistency
- Update response models in `file:codeframe/ui/models.py`
- Ensure all routes use dependency injection for `Database` and `WorkspaceManager`

### 5. Route-to-CLI Mapping Verification

**Objective:** Ensure 1:1 mapping between CLI commands and server routes.

**Create mapping table:**

| CLI Command | Core Module | Core Function | Server Route | HTTP Method |
|-------------|-------------|---------------|--------------|-------------|
| `cf init` | `core.workspace` | `create_or_load()` | `/api/workspaces` | POST |
| `cf prd add` | `core.prd` | `store()` | `/api/projects/{id}/prd` | POST |
| `cf prd generate` | `core.prd_discovery` | `start_discovery_session()` | `/api/projects/{id}/discovery/start` | POST |
| `cf prd show` | `core.prd` | `get_latest()` | `/api/projects/{id}/prd` | GET |
| `cf tasks generate` | `core.tasks` | `generate_from_prd()` | `/api/projects/{id}/tasks/generate` | POST |
| `cf tasks list` | `core.tasks` | `list_tasks()` | `/api/projects/{id}/tasks` | GET |
| `cf work start` | `core.runtime` | `start_task_run()` | `/api/tasks/{id}/start` | POST |
| `cf work resume` | `core.runtime` | `resume_task_run()` | `/api/tasks/{id}/resume` | POST |
| `cf work stop` | `core.runtime` | `stop_task_run()` | `/api/tasks/{id}/stop` | POST |
| `cf work follow` | `core.streaming` | `stream_task_output()` | `/api/tasks/{id}/stream` | GET (SSE) |
| `cf blocker list` | `core.blockers` | `list_open()` | `/api/projects/{id}/blockers` | GET |
| `cf blocker answer` | `core.blockers` | `answer()` | `/api/blockers/{id}/resolve` | POST |
| `cf checkpoint create` | `core.checkpoints` | `create()` | `/api/projects/{id}/checkpoints` | POST |
| `cf checkpoint restore` | `core.checkpoints` | `restore()` | `/api/checkpoints/{id}/restore` | POST |

**Identify gaps:**
- Missing routes for existing CLI commands
- Routes without CLI equivalents (document as server-only)

### 6. Refactor Pattern Implementation

**For each route requiring refactor:**

1. **Before (example from `file:codeframe/ui/routers/tasks.py`):**
```python
@router.post("/tasks/{task_id}/start")
async def start_task(
    task_id: str,
    db: Database = Depends(get_db),
):
    # Inline business logic
    task = db.get_task(task_id)
    task.status = "IN_PROGRESS"
    db.save(task)
    
    # Direct agent instantiation
    agent = LeadAgent(...)
    result = await agent.start_execution()
    
    return {"status": "started"}
```

2. **After (delegating to core):**
```python
@router.post("/tasks/{task_id}/start")
async def start_task(
    task_id: str,
    db: Database = Depends(get_db),
    current_user: User = Depends(get_current_user),
):
    from codeframe.core import runtime
    from codeframe.core.workspace import get_workspace
    
    # Authorization check
    task = db.get_task(task_id)
    if not db.user_has_project_access(current_user.id, task.project_id):
        raise HTTPException(status_code=403, detail="Access denied")
    
    # Get workspace
    project = db.get_project(task.project_id)
    workspace = get_workspace(project["workspace_path"])
    
    # Delegate to core
    run = runtime.start_task_run(workspace, task_id)
    
    # Return response
    return {
        "success": True,
        "data": {
            "run_id": run.id,
            "task_id": task_id,
            "status": run.status
        }
    }
```

**Apply pattern to all routes:**
- Extract business logic to core modules
- Keep only request parsing, authorization, and response formatting in routes
- Use dependency injection for database and workspace manager
- Maintain consistent error handling

### 7. Integration Testing

**Objective:** Ensure refactored routes maintain functionality.

**Test Strategy:**

1. **Verify existing integration tests** in `file:tests/cli/test_v2_cli_integration.py` still pass
2. **Create server integration tests** for refactored routes:
   - Test each route with valid inputs
   - Test authorization checks
   - Test error handling
   - Verify core module delegation

3. **Test CLI-Server equivalence:**
   - Same core function called by both CLI and server
   - Same results produced
   - Same state changes

### 8. Documentation Updates

**Update documentation:**

1. **Route audit document** - Final mapping of all routes to core modules
2. **API documentation** - Update OpenAPI specs (relates to issue #119)
3. **Architecture documentation** - Update `file:docs/V2_STRATEGIC_ROADMAP.md` with completion status
4. **Developer guide** - Document the thin adapter pattern for future route additions

### 9. Acceptance Criteria Verification

**Verify all criteria met:**

- [ ] All routes delegate to `core.*` modules
- [ ] No business logic in route handlers (only request parsing, response formatting, authorization)
- [ ] Route audit document created and complete
- [ ] Integration tests pass with refactored routes
- [ ] 1:1 mapping between CLI commands and server routes established
- [ ] Consistent URL patterns across all routes
- [ ] Consistent response formats across all routes
- [ ] Server remains optional (CLI works independently)

## Architecture Diagram

```mermaid
sequenceDiagram
    participant Client as Web Client
    participant Route as FastAPI Route
    participant Core as Core Module
    participant DB as Database
    participant Adapter as Adapter (LLM/Git)

    Client->>Route: POST /api/tasks/{id}/start
    Route->>Route: Parse request
    Route->>Route: Authorize user
    Route->>Core: runtime.start_task_run(workspace, task_id)
    Core->>DB: Get task details
    DB-->>Core: Task data
    Core->>Core: Validate state transition
    Core->>Adapter: Initialize agent
    Adapter-->>Core: Agent ready
    Core->>DB: Update task status
    Core->>Adapter: Start execution
    Core-->>Route: Run object
    Route->>Route: Format response
    Route-->>Client: {"success": true, "data": {...}}
```

## Refactor Sequence

```mermaid
graph TD
    A[1. Route Audit] --> B[2. Core Module Mapping]
    B --> C[3. Extract Discovery Logic]
    B --> D[3. Extract Task Execution Logic]
    B --> E[3. Extract Project Management Logic]
    C --> F[4. Establish Route Consistency]
    D --> F
    E --> F
    F --> G[5. Verify CLI-Route Mapping]
    G --> H[6. Apply Refactor Pattern]
    H --> I[7. Integration Testing]
    I --> J[8. Documentation Updates]
    J --> K[9. Acceptance Criteria Check]
```

---

Execution Information

Branch: main
Commit: 7fc6a53

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#82 - Review FastAPI server file refactoring strategy [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!