[P3] Refactor: Split Dashboard.tsx (934 lines) into tab-specific components

[frankbria]

Problem

Dashboard.tsx at 934 lines handles 6 tabs, 20+ state variables, and 10+ effects. Too much responsibility in one component.

Current State

• File: web-ui/src/components/Dashboard.tsx (~934 lines)
• Manages: Overview, Tasks, Quality Gates, Checkpoints, Metrics, Context tabs
• Contains: Complex conditional rendering, tab-specific logic mixed together

Impact

• Hard to maintain and extend
• Performance concerns with unnecessary re-renders
• New developers overwhelmed by file size
• Testing requires mocking too much state

Required Decomposition

New Structure

web-ui/src/components/dashboard/
├── Dashboard.tsx              # Shell with tab navigation (~200 lines)
├── DashboardOverview.tsx      # Overview tab content
├── DashboardTasks.tsx         # Tasks tab (existing TaskList integration)
├── DashboardQualityGates.tsx  # Quality gates tab
├── DashboardCheckpoints.tsx   # Checkpoints tab
├── DashboardMetrics.tsx       # Metrics tab
└── DashboardContext.tsx       # Context tab

Shared State

• Keep AgentStateContext for shared state
• Each tab component subscribes to what it needs
• Dashboard shell manages active tab only

Acceptance Criteria

• Dashboard.tsx reduced to <250 lines
• Each tab component is independently testable
• Tab switching performance unchanged
• All existing tests pass
• No visual regression

Committee Report Reference

Frontend Architect rated Dashboard as "Too High" complexity. Quote: "6 tabs, 20+ state variables, 10+ effects... Should be split."

[traycerai]

Plan

Observations

The file:web-ui/src/components/Dashboard.tsx file is 934 lines managing 6 tabs with 20+ state variables, 10+ effects, and complex conditional rendering. The codebase already follows good patterns: AgentStateContext for shared state, useAgentState hook for consumption, and a file:web-ui/src/components/metrics/ subdirectory showing component organization. The TaskList component demonstrates proper integration with the state context. Each tab has distinct responsibilities: Overview (discovery/progress/agents/activity), Tasks (phase-aware task views/blockers/reviews), Quality Gates (QualityGatesPanel), Metrics (CostDashboard), Context (agent selector/ContextPanel), and Checkpoints (CheckpointList).

Approach

The refactoring will extract each tab's content into dedicated components within a new file:web-ui/src/components/dashboard/ directory, following the existing metrics subdirectory pattern. The shell Dashboard will manage only tab navigation and active tab state, while each tab component subscribes to AgentStateContext for needed state. This approach maintains the existing state management architecture, preserves all functionality, and improves maintainability by reducing file size and separating concerns. The refactoring follows the single responsibility principle without introducing new state management patterns.

Implementation Steps

1. Create Dashboard Directory Structure

Create the new directory structure:

web-ui/src/components/dashboard/
├── Dashboard.tsx              # Shell component
├── DashboardOverview.tsx      # Overview tab
├── DashboardTasks.tsx         # Tasks tab
├── DashboardQualityGates.tsx  # Quality gates tab
├── DashboardCheckpoints.tsx   # Checkpoints tab
├── DashboardMetrics.tsx       # Metrics tab
└── DashboardContext.tsx       # Context tab

2. Extract Tab Components

2.1 DashboardOverview Component

Create file:web-ui/src/components/dashboard/DashboardOverview.tsx:

Props Interface:

• projectId: number
• projectData: ProjectData (phase, time_tracking, cost_tracking)
• progress: { completed_tasks, total_tasks, percentage }
• showChat: boolean
• onViewPRD: () => void
• onNavigateToTasks: () => void
• onAgentClick: (agentId: string) => void

Responsibilities:

• Render DiscoveryProgress component with PRD and task navigation callbacks
• Display SessionStatus component
• Conditionally render ChatInterface based on showChat prop
• Show progress section with task completion bar and time/cost tracking
• Display multi-agent team section using AgentList component
• Show legacy agent cards from AgentStateProvider (backward compatibility)
• Render recent activity feed with activity items

State Management:

• Use useAgentState() hook to access agents and activity from context
• No local state needed - all state comes from props or context

Extract from: Lines 542-698 of current Dashboard.tsx

2.2 DashboardTasks Component

Create file:web-ui/src/components/dashboard/DashboardTasks.tsx:

Props Interface:

• projectId: number
• projectData: ProjectData (phase)
• issuesData: IssuesData | null
• blockersData: Blocker[] | null
• reviewData: ReviewResult | null
• reviewLoading: boolean
• selectedTaskForReview: number | null
• onBlockerClick: (blocker: Blocker) => void
• onCloseReview: () => void
• mutateBlockers: () => void

Responsibilities:

• Display TaskStats component with phase and issues data
• Implement phase-aware task view logic:
  • Planning phase: Show TaskReview component
  • Development/Review phase: Show TaskList component
  • Other phases: Show TaskTreeView component
• Render BlockerPanel with blockers and click handler
• Conditionally show ReviewResultsPanel when task is selected
• Display LintTrendChart component
• Show ReviewSummary component with review findings

State Management:

• Use useAgentState() hook to access tasks from context
• No additional local state needed

Extract from: Lines 700-801 of current Dashboard.tsx

2.3 DashboardQualityGates Component

Create file:web-ui/src/components/dashboard/DashboardQualityGates.tsx:

Props Interface:

• projectId: number
• projectData: ProjectData (phase)
• issuesData: IssuesData | null

Responsibilities:

• Manage quality gates panel visibility state
• Implement error boundary with retry/dismiss functionality
• Render QualityGatesPanel component wrapped in ErrorBoundary
• Show/hide toggle when panel is dismissed

State Management:

• Local state: showQualityGatesPanel: boolean
• Local state: qualityGatesPanelKey: number (for error boundary reset)
• Use useAgentState() hook to access tasks from context

Extract from: Lines 803-838 of current Dashboard.tsx

2.4 DashboardMetrics Component

Create file:web-ui/src/components/dashboard/DashboardMetrics.tsx:

Props Interface:

• projectId: number
• phase: string

Responsibilities:

• Render CostDashboard component with project ID and phase
• Wrap in card layout with header

State Management:

• No state needed - purely presentational wrapper

Extract from: Lines 841-855 of current Dashboard.tsx

2.5 DashboardContext Component

Create file:web-ui/src/components/dashboard/DashboardContext.tsx:

Props Interface:

• projectId: number

Responsibilities:

• Render agent selector dropdown
• Display ContextPanel when agent is selected
• Show informational message when no agent selected

State Management:

• Local state: selectedAgentId: string | null
• Use useAgentState() hook to access agents from context for dropdown options

Extract from: Lines 857-902 of current Dashboard.tsx

2.6 DashboardCheckpoints Component

Create file:web-ui/src/components/dashboard/DashboardCheckpoints.tsx:

Props Interface:

• projectId: number

Responsibilities:

• Render CheckpointList component with project ID and refresh interval
• Wrap in card layout with header

State Management:

• No state needed - purely presentational wrapper

Extract from: Lines 904-915 of current Dashboard.tsx

3. Refactor Dashboard Shell

Refactor file:web-ui/src/components/Dashboard.tsx to become the shell component:

Retain in Shell:

• All imports for API hooks, types, and utilities
• DashboardProps interface
• normalizePhase utility function
• Tab state: activeTab (from file:web-ui/src/types/dashboard.ts)
• Modal states: showPRD, selectedBlocker
• UI states: showChat, selectedAgentId, selectedTaskForReview
• Quality gates error boundary states
• All SWR data fetching hooks (project status, blockers, PRD, issues)
• All useEffect hooks for data loading and WebSocket handlers
• Memoized agent lists
• Loading state and error handling
• Header section with navigation, PRD/Chat buttons, status display
• PhaseProgress component
• Tab navigation UI
• Tab panel rendering with conditional logic based on activeTab
• PRDModal and BlockerModal components

Remove from Shell:

• All tab content JSX (lines 542-915)
• Move to respective tab components

Add to Shell:

• Import all 6 new tab components
• Render appropriate tab component based on activeTab state
• Pass necessary props to each tab component

Target Size: ~200-250 lines (from 934 lines)

4. Update Imports and Exports

In Dashboard.tsx:

• Add imports for all 6 tab components from ./dashboard/ directory
• Keep all existing imports for shared components, hooks, and utilities

In each tab component:

• Import only the components, hooks, and utilities needed for that specific tab
• Import useAgentState hook from file:web-ui/src/hooks/useAgentState
• Import shared types from file:web-ui/src/types/
• Export component as default

5. Preserve Functionality

Ensure no behavioral changes:

• All tab switching logic remains identical
• All data fetching and WebSocket handling stays in shell
• All callback functions passed as props to tab components
• All error boundaries and loading states preserved
• All accessibility attributes (role, aria-*) maintained
• All test IDs (data-testid) preserved for existing tests

State flow:

• Shell fetches data via SWR and WebSocket
• Shell passes data as props to active tab component
• Tab components access additional state via useAgentState() hook
• Tab components call callbacks passed as props for actions

6. Testing Strategy

Component Testing:

• Each tab component should be independently testable
• Mock useAgentState hook in tab component tests
• Mock props passed from shell
• Test tab-specific rendering logic and user interactions

Integration Testing:

• Test Dashboard shell with mocked tab components
• Verify tab switching updates activeTab state
• Verify correct props passed to each tab component
• Ensure data fetching and WebSocket handlers work correctly

Existing Tests:

• Update file:web-ui/__tests__/components/Dashboard.test.tsx to test shell component
• Create new test files for each tab component in file:web-ui/__tests__/components/dashboard/

7. Visual Regression Prevention

Maintain exact styling:

• Copy all className attributes exactly as they are
• Preserve all Tailwind CSS classes
• Keep all inline styles
• Maintain component hierarchy and nesting

Preserve layout:

• Keep all wrapper divs and semantic HTML elements
• Maintain spacing (padding, margin, gap)
• Preserve grid/flex layouts
• Keep all card/panel structures

Architecture Diagram

graph TD
    A[Dashboard Shell] --> B[Tab Navigation]
    A --> C[Data Fetching SWR + WebSocket]
    A --> D[Modals PRD + Blocker]
    
    B --> E[DashboardOverview]
    B --> F[DashboardTasks]
    B --> G[DashboardQualityGates]
    B --> H[DashboardCheckpoints]
    B --> I[DashboardMetrics]
    B --> J[DashboardContext]
    
    C --> K[AgentStateContext]
    
    E --> K
    F --> K
    G --> K
    H --> K
    I --> K
    J --> K
    
    E --> L[DiscoveryProgress]
    E --> M[SessionStatus]
    E --> N[ChatInterface]
    E --> O[AgentList]
    
    F --> P[TaskStats]
    F --> Q[TaskReview/TaskList/TaskTreeView]
    F --> R[BlockerPanel]
    F --> S[LintTrendChart]
    
    G --> T[QualityGatesPanel]
    
    I --> U[CostDashboard]
    
    J --> V[ContextPanel]
    
    H --> W[CheckpointList]

Loading

Component Responsibility Matrix

Component	Lines	State Variables	Effects	Primary Responsibility
Dashboard Shell	~200	8-10	5-7	Tab navigation, data fetching, modals
DashboardOverview	~150	0	0	Discovery, progress, agents, activity
DashboardTasks	~120	0	0	Phase-aware task views, blockers, reviews
DashboardQualityGates	~60	2	0	Quality gates with error handling
DashboardCheckpoints	~30	0	0	Checkpoint list display
DashboardMetrics	~30	0	0	Cost dashboard display
DashboardContext	~50	1	0	Agent context panel

Benefits

1. Maintainability: Each tab component is <200 lines, easy to understand and modify
2. Testability: Tab components can be tested independently with mocked context
3. Performance: No change to rendering performance, same component tree depth
4. Developer Experience: New developers can focus on one tab at a time
5. Code Organization: Clear separation of concerns following single responsibility principle
6. Extensibility: Easy to add new tabs or modify existing ones without affecting others

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `file:web-ui/src/components/Dashboard.tsx` file is 934 lines managing 6 tabs with 20+ state variables, 10+ effects, and complex conditional rendering. The codebase already follows good patterns: `AgentStateContext` for shared state, `useAgentState` hook for consumption, and a `file:web-ui/src/components/metrics/` subdirectory showing component organization. The `TaskList` component demonstrates proper integration with the state context. Each tab has distinct responsibilities: Overview (discovery/progress/agents/activity), Tasks (phase-aware task views/blockers/reviews), Quality Gates (QualityGatesPanel), Metrics (CostDashboard), Context (agent selector/ContextPanel), and Checkpoints (CheckpointList).

## Approach

The refactoring will extract each tab's content into dedicated components within a new `file:web-ui/src/components/dashboard/` directory, following the existing `metrics` subdirectory pattern. The shell Dashboard will manage only tab navigation and active tab state, while each tab component subscribes to `AgentStateContext` for needed state. This approach maintains the existing state management architecture, preserves all functionality, and improves maintainability by reducing file size and separating concerns. The refactoring follows the single responsibility principle without introducing new state management patterns.

## Implementation Steps

### 1. Create Dashboard Directory Structure

Create the new directory structure:
```
web-ui/src/components/dashboard/
├── Dashboard.tsx              # Shell component
├── DashboardOverview.tsx      # Overview tab
├── DashboardTasks.tsx         # Tasks tab
├── DashboardQualityGates.tsx  # Quality gates tab
├── DashboardCheckpoints.tsx   # Checkpoints tab
├── DashboardMetrics.tsx       # Metrics tab
└── DashboardContext.tsx       # Context tab
```

### 2. Extract Tab Components

#### 2.1 DashboardOverview Component

Create `file:web-ui/src/components/dashboard/DashboardOverview.tsx`:

**Props Interface:**
- `projectId: number`
- `projectData: ProjectData` (phase, time_tracking, cost_tracking)
- `progress: { completed_tasks, total_tasks, percentage }`
- `showChat: boolean`
- `onViewPRD: () => void`
- `onNavigateToTasks: () => void`
- `onAgentClick: (agentId: string) => void`

**Responsibilities:**
- Render `DiscoveryProgress` component with PRD and task navigation callbacks
- Display `SessionStatus` component
- Conditionally render `ChatInterface` based on `showChat` prop
- Show progress section with task completion bar and time/cost tracking
- Display multi-agent team section using `AgentList` component
- Show legacy agent cards from `AgentStateProvider` (backward compatibility)
- Render recent activity feed with activity items

**State Management:**
- Use `useAgentState()` hook to access `agents` and `activity` from context
- No local state needed - all state comes from props or context

**Extract from:** Lines 542-698 of current Dashboard.tsx

#### 2.2 DashboardTasks Component

Create `file:web-ui/src/components/dashboard/DashboardTasks.tsx`:

**Props Interface:**
- `projectId: number`
- `projectData: ProjectData` (phase)
- `issuesData: IssuesData | null`
- `blockersData: Blocker[] | null`
- `reviewData: ReviewResult | null`
- `reviewLoading: boolean`
- `selectedTaskForReview: number | null`
- `onBlockerClick: (blocker: Blocker) => void`
- `onCloseReview: () => void`
- `mutateBlockers: () => void`

**Responsibilities:**
- Display `TaskStats` component with phase and issues data
- Implement phase-aware task view logic:
  - Planning phase: Show `TaskReview` component
  - Development/Review phase: Show `TaskList` component
  - Other phases: Show `TaskTreeView` component
- Render `BlockerPanel` with blockers and click handler
- Conditionally show `ReviewResultsPanel` when task is selected
- Display `LintTrendChart` component
- Show `ReviewSummary` component with review findings

**State Management:**
- Use `useAgentState()` hook to access `tasks` from context
- No additional local state needed

**Extract from:** Lines 700-801 of current Dashboard.tsx

#### 2.3 DashboardQualityGates Component

Create `file:web-ui/src/components/dashboard/DashboardQualityGates.tsx`:

**Props Interface:**
- `projectId: number`
- `projectData: ProjectData` (phase)
- `issuesData: IssuesData | null`

**Responsibilities:**
- Manage quality gates panel visibility state
- Implement error boundary with retry/dismiss functionality
- Render `QualityGatesPanel` component wrapped in `ErrorBoundary`
- Show/hide toggle when panel is dismissed

**State Management:**
- Local state: `showQualityGatesPanel: boolean`
- Local state: `qualityGatesPanelKey: number` (for error boundary reset)
- Use `useAgentState()` hook to access `tasks` from context

**Extract from:** Lines 803-838 of current Dashboard.tsx

#### 2.4 DashboardMetrics Component

Create `file:web-ui/src/components/dashboard/DashboardMetrics.tsx`:

**Props Interface:**
- `projectId: number`
- `phase: string`

**Responsibilities:**
- Render `CostDashboard` component with project ID and phase
- Wrap in card layout with header

**State Management:**
- No state needed - purely presentational wrapper

**Extract from:** Lines 841-855 of current Dashboard.tsx

#### 2.5 DashboardContext Component

Create `file:web-ui/src/components/dashboard/DashboardContext.tsx`:

**Props Interface:**
- `projectId: number`

**Responsibilities:**
- Render agent selector dropdown
- Display `ContextPanel` when agent is selected
- Show informational message when no agent selected

**State Management:**
- Local state: `selectedAgentId: string | null`
- Use `useAgentState()` hook to access `agents` from context for dropdown options

**Extract from:** Lines 857-902 of current Dashboard.tsx

#### 2.6 DashboardCheckpoints Component

Create `file:web-ui/src/components/dashboard/DashboardCheckpoints.tsx`:

**Props Interface:**
- `projectId: number`

**Responsibilities:**
- Render `CheckpointList` component with project ID and refresh interval
- Wrap in card layout with header

**State Management:**
- No state needed - purely presentational wrapper

**Extract from:** Lines 904-915 of current Dashboard.tsx

### 3. Refactor Dashboard Shell

Refactor `file:web-ui/src/components/Dashboard.tsx` to become the shell component:

**Retain in Shell:**
- All imports for API hooks, types, and utilities
- `DashboardProps` interface
- `normalizePhase` utility function
- Tab state: `activeTab` (from `file:web-ui/src/types/dashboard.ts`)
- Modal states: `showPRD`, `selectedBlocker`
- UI states: `showChat`, `selectedAgentId`, `selectedTaskForReview`
- Quality gates error boundary states
- All SWR data fetching hooks (project status, blockers, PRD, issues)
- All useEffect hooks for data loading and WebSocket handlers
- Memoized agent lists
- Loading state and error handling
- Header section with navigation, PRD/Chat buttons, status display
- `PhaseProgress` component
- Tab navigation UI
- Tab panel rendering with conditional logic based on `activeTab`
- `PRDModal` and `BlockerModal` components

**Remove from Shell:**
- All tab content JSX (lines 542-915)
- Move to respective tab components

**Add to Shell:**
- Import all 6 new tab components
- Render appropriate tab component based on `activeTab` state
- Pass necessary props to each tab component

**Target Size:** ~200-250 lines (from 934 lines)

### 4. Update Imports and Exports

**In Dashboard.tsx:**
- Add imports for all 6 tab components from `./dashboard/` directory
- Keep all existing imports for shared components, hooks, and utilities

**In each tab component:**
- Import only the components, hooks, and utilities needed for that specific tab
- Import `useAgentState` hook from `file:web-ui/src/hooks/useAgentState`
- Import shared types from `file:web-ui/src/types/`
- Export component as default

### 5. Preserve Functionality

**Ensure no behavioral changes:**
- All tab switching logic remains identical
- All data fetching and WebSocket handling stays in shell
- All callback functions passed as props to tab components
- All error boundaries and loading states preserved
- All accessibility attributes (role, aria-*) maintained
- All test IDs (data-testid) preserved for existing tests

**State flow:**
- Shell fetches data via SWR and WebSocket
- Shell passes data as props to active tab component
- Tab components access additional state via `useAgentState()` hook
- Tab components call callbacks passed as props for actions

### 6. Testing Strategy

**Component Testing:**
- Each tab component should be independently testable
- Mock `useAgentState` hook in tab component tests
- Mock props passed from shell
- Test tab-specific rendering logic and user interactions

**Integration Testing:**
- Test Dashboard shell with mocked tab components
- Verify tab switching updates `activeTab` state
- Verify correct props passed to each tab component
- Ensure data fetching and WebSocket handlers work correctly

**Existing Tests:**
- Update `file:web-ui/__tests__/components/Dashboard.test.tsx` to test shell component
- Create new test files for each tab component in `file:web-ui/__tests__/components/dashboard/`

### 7. Visual Regression Prevention

**Maintain exact styling:**
- Copy all className attributes exactly as they are
- Preserve all Tailwind CSS classes
- Keep all inline styles
- Maintain component hierarchy and nesting

**Preserve layout:**
- Keep all wrapper divs and semantic HTML elements
- Maintain spacing (padding, margin, gap)
- Preserve grid/flex layouts
- Keep all card/panel structures

## Architecture Diagram

```mermaid
graph TD
    A[Dashboard Shell] --> B[Tab Navigation]
    A --> C[Data Fetching SWR + WebSocket]
    A --> D[Modals PRD + Blocker]
    
    B --> E[DashboardOverview]
    B --> F[DashboardTasks]
    B --> G[DashboardQualityGates]
    B --> H[DashboardCheckpoints]
    B --> I[DashboardMetrics]
    B --> J[DashboardContext]
    
    C --> K[AgentStateContext]
    
    E --> K
    F --> K
    G --> K
    H --> K
    I --> K
    J --> K
    
    E --> L[DiscoveryProgress]
    E --> M[SessionStatus]
    E --> N[ChatInterface]
    E --> O[AgentList]
    
    F --> P[TaskStats]
    F --> Q[TaskReview/TaskList/TaskTreeView]
    F --> R[BlockerPanel]
    F --> S[LintTrendChart]
    
    G --> T[QualityGatesPanel]
    
    I --> U[CostDashboard]
    
    J --> V[ContextPanel]
    
    H --> W[CheckpointList]
```

## Component Responsibility Matrix

| Component | Lines | State Variables | Effects | Primary Responsibility |
|-----------|-------|-----------------|---------|------------------------|
| Dashboard Shell | ~200 | 8-10 | 5-7 | Tab navigation, data fetching, modals |
| DashboardOverview | ~150 | 0 | 0 | Discovery, progress, agents, activity |
| DashboardTasks | ~120 | 0 | 0 | Phase-aware task views, blockers, reviews |
| DashboardQualityGates | ~60 | 2 | 0 | Quality gates with error handling |
| DashboardCheckpoints | ~30 | 0 | 0 | Checkpoint list display |
| DashboardMetrics | ~30 | 0 | 0 | Cost dashboard display |
| DashboardContext | ~50 | 1 | 0 | Agent context panel |

## Benefits

1. **Maintainability**: Each tab component is <200 lines, easy to understand and modify
2. **Testability**: Tab components can be tested independently with mocked context
3. **Performance**: No change to rendering performance, same component tree depth
4. **Developer Experience**: New developers can focus on one tab at a time
5. **Code Organization**: Clear separation of concerns following single responsibility principle
6. **Extensibility**: Easy to add new tabs or modify existing ones without affecting others

---

Execution Information

Branch: main
Commit: a107395

---

💡 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

#26 - Feature 013: Context Panel Integration with TypeScript Fixes [merged]
#51 - feat: Add TaskStats component to Dashboard Overview tab [merged]
#93 - fix(e2e): Fix dashboard and metrics tests for tab-based UI rendering [merged]
#169 - feat(dashboard): Add dedicated tabs for Tasks, Quality Gates, and Metrics [merged]
#215 - feat(dashboard): Add phase-aware task view integration (#16-6) [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!