[P2] Enhance project list with agent status and deployment URLs

[frankbria]

Overview

Enhance the project list page with additional project information including running agent status and deployment environment URLs.

Parent Issue: #174 (Project selection home page - core functionality complete)

Background

The core project list home page was implemented in PR (pending). The following enhancements were identified but deferred to this follow-up issue:

Implementation Steps

1. Display Agent Status on Project Cards

File: web-ui/src/components/ProjectList.tsx

• Show whether agents are currently running for each project
• Display agent count and status (e.g., "2 agents running", "1 agent blocked")
• Add visual indicator (badge/icon) for active vs idle projects
• Requires API call to /api/projects/{id}/agents endpoint

2. Add Deployment URLs to Project Cards

File: web-ui/src/components/ProjectList.tsx

• Display links to deployment environments when available:
  • Test environment URL
  • Staging environment URL
  • Production environment URL
• Only show if URLs are configured in project settings
• May require backend schema update to store deployment URLs

3. Enhance Project Status Display

File: web-ui/src/components/ProjectList.tsx

• Show more detailed project phase information:
  • Discovery
  • Development
  • Testing
  • Deployment
  • Production
• Add visual progress indicator for project lifecycle

4. Backend Schema Updates (if needed)

File: codeframe/persistence/schema_manager.py

• Add deployment URLs fields to project config:
  • test_url
  • staging_url
  • production_url
• Add migration script if schema changes required

Acceptance Criteria

• Project cards show agent count and status
• Active projects have visual indicator
• Deployment URLs are clickable links when available
• Project phase is clearly displayed
• Unit tests cover new functionality
• E2E tests verify agent status display

Technical Notes

• Agent data available via existing /api/projects/{id}/agents endpoint
• Consider SWR for efficient data fetching with caching
• Use Nova design system tokens for styling

[traycerai]

Plan

Observations

The project list page (file:web-ui/src/components/ProjectList.tsx) currently displays basic project information (name, status, phase, created date) in a grid layout. The backend has an existing /api/projects/{id}/agents endpoint that returns agent data with status information. The database schema stores agent status in the agents table but lacks deployment URL fields in the projects table. The codebase uses SWR for data fetching, Nova design system components (Badge, Card, Progress), and has established patterns for status indicators (BlockerBadge, SessionStatus).

Approach

The implementation will enhance the project cards with three key features: agent status indicators showing running/blocked counts, deployment environment URLs when configured, and enhanced phase visualization. This requires frontend updates to ProjectList component with additional API calls per project, backend schema migration to add deployment URL fields to projects table, and comprehensive test coverage. The approach leverages existing UI components (Badge, Card) and follows established patterns for data fetching with SWR and status display.

Implementation Steps

1. Backend Schema Updates

Add deployment URL fields to projects table

Update file:codeframe/persistence/schema_manager.py in the _create_project_tables method:

• Add three new TEXT columns to the projects table: test_url, staging_url, production_url
• These fields should be nullable since not all projects will have deployment URLs configured
• Add these fields after the config column in the CREATE TABLE statement

Create migration script

Create new file file:codeframe/persistence/migrations/add_deployment_urls.py:

• Implement migration to add the three URL columns using ALTER TABLE statements
• Include rollback capability to remove columns if needed
• Follow existing migration patterns in the codebase

Update database methods

Modify file:codeframe/persistence/database.py:

• Update get_project() method to include the new URL fields in SELECT queries
• Update get_user_projects() method to include URL fields in the returned project dictionaries
• Ensure the fields are properly serialized in API responses

2. Frontend Type Definitions

Extend Project interface

Update file:web-ui/src/types/index.ts:

• Add optional deployment URL fields to the Project interface:
  • test_url?: string
  • staging_url?: string
  • production_url?: string
• Add agent summary fields for display:
  • agent_summary?: { total: number; running: number; blocked: number; idle: number }

Create agent status types

Add to file:web-ui/src/types/index.ts:

• Create helper type for agent status counts: AgentStatusSummary
• This will be used to aggregate agent data for display on project cards

3. API Client Updates

Add agent status fetching

Update file:web-ui/src/lib/api.ts:

• The agentsApi.list() method already exists and returns agents for a project
• No changes needed to API client, will use existing endpoint

4. ProjectList Component Enhancement

Add agent status display

Update file:web-ui/src/components/ProjectList.tsx:

Create a new helper function useProjectAgents:

• Use SWR to fetch agents for each project using agentsApi.list(projectId)
• Aggregate agent data to calculate counts by status (running, blocked, idle)
• Return agent summary object with counts

Create a new sub-component ProjectAgentStatus:

• Accept agent summary data as props
• Display agent count badges using file:web-ui/src/components/ui/badge.tsx
• Show different badge variants for different statuses:
  • Running agents: primary variant with green indicator
  • Blocked agents: destructive variant with red indicator
  • Idle agents: secondary variant with gray indicator
• Display format: "2 running • 1 blocked" or "No agents" if none exist
• Add visual indicator dot (●) before count for active projects

Update the project card rendering:

• Add ProjectAgentStatus component below the phase information
• Position it in the card's content area, before the date

Add deployment URLs display

Create a new sub-component ProjectDeploymentLinks:

• Accept deployment URLs as props (test_url, staging_url, production_url)
• Only render if at least one URL is configured
• Display as a list of clickable links with environment labels
• Use icons or badges to distinguish environments:
  • Test: 🧪 or "TEST" badge
  • Staging: 🚀 or "STAGING" badge
  • Production: ✅ or "PROD" badge
• Links should open in new tab (target="_blank" rel="noopener noreferrer")
• Style links using text-primary with hover effects

Update the project card rendering:

• Add ProjectDeploymentLinks component in the card footer area
• Only render when URLs are available

Enhance phase display

Create a new sub-component ProjectPhaseIndicator:

• Accept phase as prop (discovery, planning, active, review, complete)
• Display phase with visual progress indicator using file:web-ui/src/components/ui/progress.tsx
• Map phases to progress percentages:
  • discovery: 20%
  • planning: 40%
  • active: 60%
  • review: 80%
  • complete: 100%
• Show phase name with progress bar below
• Use color coding: primary for active phases, success for complete

Update the project card rendering:

• Replace simple phase text with ProjectPhaseIndicator component
• Position it prominently in the card header area

Optimize data fetching

Implement efficient data loading strategy:

• Use SWR's useSWR with project-specific keys for agent data
• Enable SWR's revalidateOnFocus and dedupingInterval for caching
• Consider using useSWRConfig to prefetch agent data for visible projects
• Add loading states for agent data (show skeleton or "Loading..." text)
• Handle errors gracefully (show "Unable to load agents" message)

5. Styling and Visual Design

Update project card layout

Modify card structure in file:web-ui/src/components/ProjectList.tsx:

• Use file:web-ui/src/components/ui/card.tsx components (Card, CardHeader, CardContent, CardFooter)
• Restructure card to accommodate new elements:
  • CardHeader: Project name + active indicator dot
  • CardContent: Status, Phase indicator, Agent status
  • CardFooter: Deployment links, Created date
• Add visual indicator for active projects (green dot or pulse animation)
• Increase card height if needed to accommodate new content

Apply Nova design tokens

Use existing design system:

• Badge variants from file:web-ui/src/components/ui/badge.tsx
• Color tokens: primary, destructive, secondary, muted-foreground
• Spacing: consistent padding and gaps using Tailwind classes
• Typography: font-semibold for labels, text-sm for secondary info

6. Unit Tests

Test ProjectList enhancements

Update file:web-ui/src/components/__tests__/ProjectList.test.tsx:

Add test cases for agent status display:

• "displays agent count when agents are running"
• "shows blocked agent indicator with correct count"
• "displays 'No agents' when project has no agents"
• "handles agent data loading state"
• "handles agent data fetch error gracefully"

Add test cases for deployment URLs:

• "displays deployment links when URLs are configured"
• "hides deployment section when no URLs configured"
• "renders correct environment labels for each URL"
• "opens deployment links in new tab"

Add test cases for phase indicator:

• "displays phase with progress bar"
• "shows correct progress percentage for each phase"
• "applies correct styling for complete phase"

Mock agent API responses:

• Mock agentsApi.list() to return test agent data
• Include various agent statuses in mock data
• Test with empty agent arrays

Test new sub-components

Create new test files:

• file:web-ui/src/components/__tests__/ProjectAgentStatus.test.tsx
• file:web-ui/src/components/__tests__/ProjectDeploymentLinks.test.tsx
• file:web-ui/src/components/__tests__/ProjectPhaseIndicator.test.tsx

Each should test:

• Rendering with various prop combinations
• Correct badge/indicator display
• Edge cases (null/undefined values)
• Accessibility (ARIA labels, semantic HTML)

7. E2E Tests

Add project list E2E tests

Create or update file:tests/e2e/test_project_list.spec.ts:

Test agent status display:

• Navigate to project list page
• Verify agent status badges are visible
• Check correct agent counts are displayed
• Verify visual indicators for active projects

Test deployment URLs:

• Create project with deployment URLs configured
• Verify links are displayed with correct labels
• Click deployment link and verify new tab opens
• Test with projects without URLs (should not show section)

Test phase indicators:

• Verify phase progress bars render correctly
• Check different phases show appropriate progress
• Verify color coding for different phases

Test data loading and errors:

• Test loading states for agent data
• Simulate API errors and verify error handling
• Test with slow network conditions

8. API Endpoint Testing

Test agent endpoint integration

Update file:tests/api/test_api_projects.py:

Add tests for agent data in project list:

• Test that /api/projects returns projects
• Test that /api/projects/{id}/agents returns agent data
• Verify agent status values are correct
• Test with multiple agents per project
• Test with no agents

Add tests for deployment URLs:

• Test creating project with deployment URLs
• Test updating project with deployment URLs
• Test retrieving project with URLs in response
• Verify URL validation (optional: check URL format)

Data Flow Diagram

sequenceDiagram
    participant User
    participant ProjectList
    participant SWR
    participant API
    participant Database

    User->>ProjectList: Load page
    ProjectList->>SWR: useSWR('/projects')
    SWR->>API: GET /api/projects
    API->>Database: get_user_projects()
    Database-->>API: projects with deployment URLs
    API-->>SWR: projects array
    SWR-->>ProjectList: projects data
    
    loop For each project
        ProjectList->>SWR: useSWR(`/projects/${id}/agents`)
        SWR->>API: GET /api/projects/{id}/agents
        API->>Database: get_agents_for_project()
        Database-->>API: agents array
        API-->>SWR: agents with status
        SWR-->>ProjectList: agent data
        ProjectList->>ProjectList: Calculate agent summary
    end
    
    ProjectList->>User: Display enhanced project cards

Loading

Component Structure

graph TD
    A[ProjectList] --> B[Project Card]
    B --> C[CardHeader: Name + Active Indicator]
    B --> D[CardContent]
    B --> E[CardFooter]
    
    D --> F[Status Display]
    D --> G[ProjectPhaseIndicator]
    D --> H[ProjectAgentStatus]
    
    H --> I[Badge: Running]
    H --> J[Badge: Blocked]
    H --> K[Badge: Idle]
    
    E --> L[ProjectDeploymentLinks]
    E --> M[Created Date]
    
    L --> N[Test URL Link]
    L --> O[Staging URL Link]
    L --> P[Production URL Link]
    
    G --> Q[Progress Bar]
    G --> R[Phase Label]

Loading

Implementation Checklist

Step	Component	Files Modified	Dependencies
1	Schema	schema_manager.py, migration file	None
2	Types	types/index.ts	Step 1
3	API	lib/api.ts (verify existing)	Step 2
4	ProjectList	ProjectList.tsx	Steps 2-3
5	Styling	ProjectList.tsx, UI components	Step 4
6	Unit Tests	__tests__/ProjectList.test.tsx	Step 4-5
7	E2E Tests	test_project_list.spec.ts	Step 4-5
8	API Tests	test_api_projects.py	Step 1

Import In IDE

🤖 Prompt for AI Agents

## Observations

The project list page (`file:web-ui/src/components/ProjectList.tsx`) currently displays basic project information (name, status, phase, created date) in a grid layout. The backend has an existing `/api/projects/{id}/agents` endpoint that returns agent data with status information. The database schema stores agent status in the `agents` table but lacks deployment URL fields in the `projects` table. The codebase uses SWR for data fetching, Nova design system components (Badge, Card, Progress), and has established patterns for status indicators (BlockerBadge, SessionStatus).

## Approach

The implementation will enhance the project cards with three key features: agent status indicators showing running/blocked counts, deployment environment URLs when configured, and enhanced phase visualization. This requires frontend updates to ProjectList component with additional API calls per project, backend schema migration to add deployment URL fields to projects table, and comprehensive test coverage. The approach leverages existing UI components (Badge, Card) and follows established patterns for data fetching with SWR and status display.

## Implementation Steps

### 1. Backend Schema Updates

**Add deployment URL fields to projects table**

Update `file:codeframe/persistence/schema_manager.py` in the `_create_project_tables` method:
- Add three new TEXT columns to the projects table: `test_url`, `staging_url`, `production_url`
- These fields should be nullable since not all projects will have deployment URLs configured
- Add these fields after the `config` column in the CREATE TABLE statement

**Create migration script**

Create new file `file:codeframe/persistence/migrations/add_deployment_urls.py`:
- Implement migration to add the three URL columns using ALTER TABLE statements
- Include rollback capability to remove columns if needed
- Follow existing migration patterns in the codebase

**Update database methods**

Modify `file:codeframe/persistence/database.py`:
- Update `get_project()` method to include the new URL fields in SELECT queries
- Update `get_user_projects()` method to include URL fields in the returned project dictionaries
- Ensure the fields are properly serialized in API responses

### 2. Frontend Type Definitions

**Extend Project interface**

Update `file:web-ui/src/types/index.ts`:
- Add optional deployment URL fields to the Project interface:
  - `test_url?: string`
  - `staging_url?: string`
  - `production_url?: string`
- Add agent summary fields for display:
  - `agent_summary?: { total: number; running: number; blocked: number; idle: number }`

**Create agent status types**

Add to `file:web-ui/src/types/index.ts`:
- Create helper type for agent status counts: `AgentStatusSummary`
- This will be used to aggregate agent data for display on project cards

### 3. API Client Updates

**Add agent status fetching**

Update `file:web-ui/src/lib/api.ts`:
- The `agentsApi.list()` method already exists and returns agents for a project
- No changes needed to API client, will use existing endpoint

### 4. ProjectList Component Enhancement

**Add agent status display**

Update `file:web-ui/src/components/ProjectList.tsx`:

Create a new helper function `useProjectAgents`:
- Use SWR to fetch agents for each project using `agentsApi.list(projectId)`
- Aggregate agent data to calculate counts by status (running, blocked, idle)
- Return agent summary object with counts

Create a new sub-component `ProjectAgentStatus`:
- Accept agent summary data as props
- Display agent count badges using `file:web-ui/src/components/ui/badge.tsx`
- Show different badge variants for different statuses:
  - Running agents: primary variant with green indicator
  - Blocked agents: destructive variant with red indicator
  - Idle agents: secondary variant with gray indicator
- Display format: "2 running • 1 blocked" or "No agents" if none exist
- Add visual indicator dot (●) before count for active projects

Update the project card rendering:
- Add `ProjectAgentStatus` component below the phase information
- Position it in the card's content area, before the date

**Add deployment URLs display**

Create a new sub-component `ProjectDeploymentLinks`:
- Accept deployment URLs as props (test_url, staging_url, production_url)
- Only render if at least one URL is configured
- Display as a list of clickable links with environment labels
- Use icons or badges to distinguish environments:
  - Test: 🧪 or "TEST" badge
  - Staging: 🚀 or "STAGING" badge  
  - Production: ✅ or "PROD" badge
- Links should open in new tab (target="_blank" rel="noopener noreferrer")
- Style links using text-primary with hover effects

Update the project card rendering:
- Add `ProjectDeploymentLinks` component in the card footer area
- Only render when URLs are available

**Enhance phase display**

Create a new sub-component `ProjectPhaseIndicator`:
- Accept phase as prop (discovery, planning, active, review, complete)
- Display phase with visual progress indicator using `file:web-ui/src/components/ui/progress.tsx`
- Map phases to progress percentages:
  - discovery: 20%
  - planning: 40%
  - active: 60%
  - review: 80%
  - complete: 100%
- Show phase name with progress bar below
- Use color coding: primary for active phases, success for complete

Update the project card rendering:
- Replace simple phase text with `ProjectPhaseIndicator` component
- Position it prominently in the card header area

**Optimize data fetching**

Implement efficient data loading strategy:
- Use SWR's `useSWR` with project-specific keys for agent data
- Enable SWR's `revalidateOnFocus` and `dedupingInterval` for caching
- Consider using `useSWRConfig` to prefetch agent data for visible projects
- Add loading states for agent data (show skeleton or "Loading..." text)
- Handle errors gracefully (show "Unable to load agents" message)

### 5. Styling and Visual Design

**Update project card layout**

Modify card structure in `file:web-ui/src/components/ProjectList.tsx`:
- Use `file:web-ui/src/components/ui/card.tsx` components (Card, CardHeader, CardContent, CardFooter)
- Restructure card to accommodate new elements:
  - CardHeader: Project name + active indicator dot
  - CardContent: Status, Phase indicator, Agent status
  - CardFooter: Deployment links, Created date
- Add visual indicator for active projects (green dot or pulse animation)
- Increase card height if needed to accommodate new content

**Apply Nova design tokens**

Use existing design system:
- Badge variants from `file:web-ui/src/components/ui/badge.tsx`
- Color tokens: primary, destructive, secondary, muted-foreground
- Spacing: consistent padding and gaps using Tailwind classes
- Typography: font-semibold for labels, text-sm for secondary info

### 6. Unit Tests

**Test ProjectList enhancements**

Update `file:web-ui/src/components/__tests__/ProjectList.test.tsx`:

Add test cases for agent status display:
- "displays agent count when agents are running"
- "shows blocked agent indicator with correct count"
- "displays 'No agents' when project has no agents"
- "handles agent data loading state"
- "handles agent data fetch error gracefully"

Add test cases for deployment URLs:
- "displays deployment links when URLs are configured"
- "hides deployment section when no URLs configured"
- "renders correct environment labels for each URL"
- "opens deployment links in new tab"

Add test cases for phase indicator:
- "displays phase with progress bar"
- "shows correct progress percentage for each phase"
- "applies correct styling for complete phase"

Mock agent API responses:
- Mock `agentsApi.list()` to return test agent data
- Include various agent statuses in mock data
- Test with empty agent arrays

**Test new sub-components**

Create new test files:
- `file:web-ui/src/components/__tests__/ProjectAgentStatus.test.tsx`
- `file:web-ui/src/components/__tests__/ProjectDeploymentLinks.test.tsx`
- `file:web-ui/src/components/__tests__/ProjectPhaseIndicator.test.tsx`

Each should test:
- Rendering with various prop combinations
- Correct badge/indicator display
- Edge cases (null/undefined values)
- Accessibility (ARIA labels, semantic HTML)

### 7. E2E Tests

**Add project list E2E tests**

Create or update `file:tests/e2e/test_project_list.spec.ts`:

Test agent status display:
- Navigate to project list page
- Verify agent status badges are visible
- Check correct agent counts are displayed
- Verify visual indicators for active projects

Test deployment URLs:
- Create project with deployment URLs configured
- Verify links are displayed with correct labels
- Click deployment link and verify new tab opens
- Test with projects without URLs (should not show section)

Test phase indicators:
- Verify phase progress bars render correctly
- Check different phases show appropriate progress
- Verify color coding for different phases

Test data loading and errors:
- Test loading states for agent data
- Simulate API errors and verify error handling
- Test with slow network conditions

### 8. API Endpoint Testing

**Test agent endpoint integration**

Update `file:tests/api/test_api_projects.py`:

Add tests for agent data in project list:
- Test that `/api/projects` returns projects
- Test that `/api/projects/{id}/agents` returns agent data
- Verify agent status values are correct
- Test with multiple agents per project
- Test with no agents

Add tests for deployment URLs:
- Test creating project with deployment URLs
- Test updating project with deployment URLs
- Test retrieving project with URLs in response
- Verify URL validation (optional: check URL format)

## Data Flow Diagram

```mermaid
sequenceDiagram
    participant User
    participant ProjectList
    participant SWR
    participant API
    participant Database

    User->>ProjectList: Load page
    ProjectList->>SWR: useSWR('/projects')
    SWR->>API: GET /api/projects
    API->>Database: get_user_projects()
    Database-->>API: projects with deployment URLs
    API-->>SWR: projects array
    SWR-->>ProjectList: projects data
    
    loop For each project
        ProjectList->>SWR: useSWR(`/projects/${id}/agents`)
        SWR->>API: GET /api/projects/{id}/agents
        API->>Database: get_agents_for_project()
        Database-->>API: agents array
        API-->>SWR: agents with status
        SWR-->>ProjectList: agent data
        ProjectList->>ProjectList: Calculate agent summary
    end
    
    ProjectList->>User: Display enhanced project cards
```

## Component Structure

```mermaid
graph TD
    A[ProjectList] --> B[Project Card]
    B --> C[CardHeader: Name + Active Indicator]
    B --> D[CardContent]
    B --> E[CardFooter]
    
    D --> F[Status Display]
    D --> G[ProjectPhaseIndicator]
    D --> H[ProjectAgentStatus]
    
    H --> I[Badge: Running]
    H --> J[Badge: Blocked]
    H --> K[Badge: Idle]
    
    E --> L[ProjectDeploymentLinks]
    E --> M[Created Date]
    
    L --> N[Test URL Link]
    L --> O[Staging URL Link]
    L --> P[Production URL Link]
    
    G --> Q[Progress Bar]
    G --> R[Phase Label]
```

## Implementation Checklist

| Step | Component | Files Modified | Dependencies |
|------|-----------|----------------|--------------|
| 1 | Schema | `schema_manager.py`, migration file | None |
| 2 | Types | `types/index.ts` | Step 1 |
| 3 | API | `lib/api.ts` (verify existing) | Step 2 |
| 4 | ProjectList | `ProjectList.tsx` | Steps 2-3 |
| 5 | Styling | `ProjectList.tsx`, UI components | Step 4 |
| 6 | Unit Tests | `__tests__/ProjectList.test.tsx` | Step 4-5 |
| 7 | E2E Tests | `test_project_list.spec.ts` | Step 4-5 |
| 8 | API Tests | `test_api_projects.py` | Step 1 |

---

Execution Information

Branch: main
Commit: 4202976

---

💡 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

---

🔗 Similar Issues

Possible Duplicates

• [P0] Create project selection home page #174

Related Issues

• [P1] Improve E2E test coverage for API and WebSocket failures #172
• [P1] Implement missing CostDashboard UI elements (date filter, task breakdown, trend chart) #86
• Rework UI components to match shadcn Nova template #138

🔗 Related PRs

#9 - Merge Sprint 4 Multi-Agent Coordination work into main [merged]
#38 - fix(e2e): Improve Playwright test pass rate from 18% to 57% [merged]
#51 - feat: Add TaskStats component to Dashboard Overview tab [merged]
#136 - Implement comprehensive database-backed Project.get_status() method [merged]
#152 - Implement agent maturity level system [merged]

👤 Suggested Assignees

• frankbria

---

🧪 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!

[frankbria]

Closing as part of v2 roadmap cleanup. This v1-specific issue is retained with the v1-legacy label as reference material for Phase 3 (Web UI rebuild). See the v2 strategic roadmap for current priorities.