[P0] Create project selection home page

[frankbria]

When the user logs in, they are taken immediately to a Create Project page, even if there are existing projects the user has already created.

The initial "home" page for the user should be a page listing all the existing projects - or No Projects Available if the user hasn't created any projects. The page should also include a button to Create a New Project. That button should lead to the create new project page.

The default page should be changed to the project list page. The project list page should also have some basic information about each project, the description, whether current agents are running and their status, and a status of the project (state: discovery, development, testing, deployment, production, etc.). Whatever information is stored and is available about the project. (this may elicit new requirements for information about projects that need to be stored.) For example, for projects with deployment URLs, there probably should be link to the test, staging, and production environments for these projects.

[traycerai]

Plan

Observations

The codebase currently has:

• A home page (file:web-ui/src/app/page.tsx) that directly shows a project creation form
• An existing ProjectList component (file:web-ui/src/components/ProjectList.tsx) that displays projects in a grid with status, phase, and creation date
• Backend API endpoint /api/projects that returns project data including id, name, description, status, phase, created_at, and config
• Agent API endpoint /api/projects/{project_id}/agents that returns agent information including status and current task
• Authentication flow using AuthContext and ProtectedRoute components
• Navigation component that shows on all pages except login/signup

Approach

The solution involves transforming the home page from a direct project creation form to a project list page with a "Create New Project" button. The ProjectList component already exists and handles most requirements, but needs enhancement to display agent status and deployment URLs. The home page will be wrapped with ProtectedRoute to ensure authentication, and the project list will show comprehensive project information including running agents, their status, and deployment environment links when available. The project creation form will remain accessible via a button that opens it inline or navigates to a dedicated route.

Implementation Steps

1. Update Home Page to Display Project List

File: file:web-ui/src/app/page.tsx

Replace the current project creation form with the ProjectList component:

• Remove the ProjectCreationForm import and related state management
• Import and render the ProjectList component instead
• Wrap the entire page with ProtectedRoute to ensure only authenticated users can access it
• Update the page title and description to reflect "Your Projects" instead of "Welcome to CodeFRAME"
• Keep the same layout structure but replace the form content with the project list

2. Enhance ProjectList Component

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

Extend the component to display additional project information:

• Add agent status display for each project by fetching from /api/projects/{projectId}/agents
• Show count of active agents and their current status (idle, working, blocked)
• Display project description in the project card
• Add deployment URL links if available in project config (test, staging, production environments)
• Enhance the project card layout to accommodate the new information
• Use SWR for efficient data fetching and caching of agent data
• Add loading states for agent information
• Display "No agents running" when no agents are active

Layout structure for each project card:

┌─────────────────────────────────────┐
│ Project Name                        │
│ Description: [project description]  │
│ Status: [status] | Phase: [phase]   │
│ Agents: [X active, Y idle]          │
│ Created: [date]                     │
│ Links: [Test] [Staging] [Production]│
└─────────────────────────────────────┘

3. Create Type Definitions for Enhanced Project Data

File: file:web-ui/src/types/project.ts

Add new type definitions:

• ProjectWithAgents interface extending the existing Project type
• AgentSummary interface for agent status display
• DeploymentUrls interface for environment links
• Update existing types to include optional deployment URL fields

4. Update API Client

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

Add new API methods if needed:

• Ensure projectsApi.list() returns all necessary project fields including description
• Verify agentsApi.list(projectId) returns agent status information
• Add helper function to extract deployment URLs from project config if not already available

5. Update Navigation Flow

File: file:web-ui/src/components/Navigation.tsx

Ensure the navigation properly handles the new home page:

• Verify the "CodeFRAME" logo link points to "/" (home page with project list)
• Ensure navigation remains consistent across authenticated pages

6. Handle Empty State

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

The component already handles the empty state, but verify:

• "No projects yet. Create your first project!" message is displayed when no projects exist
• The "Create New Project" button is prominently displayed
• The empty state is visually appealing and guides users to create their first project

7. Update Project Detail Page Navigation

File: file:web-ui/src/app/projects/[projectId]/page.tsx

Ensure the project detail page has a way to return to the project list:

• Add a "Back to Projects" link or button in the project detail view
• This may require updating the Dashboard component or adding navigation in the layout

8. Add Deployment URL Support (Future Enhancement)

Backend Files: file:codeframe/core/config.py, file:codeframe/ui/models.py

If deployment URLs are not currently stored:

• Add optional deployment_urls field to ProjectConfig in file:codeframe/core/config.py
• Update ProjectResponse model in file:codeframe/ui/models.py to include deployment URLs
• Update project creation/update endpoints to accept and store deployment URLs
• This may be deferred if deployment URLs are not yet a requirement

9. Testing Considerations

Files: file:web-ui/src/app/__tests__/page.test.tsx

Update existing tests:

• Modify home page tests to expect project list instead of creation form
• Add tests for authenticated access (ProtectedRoute behavior)
• Add tests for project list rendering with various data states
• Test agent status display
• Test deployment URL links when available

Architecture Diagram

sequenceDiagram
    participant User
    participant HomePage
    participant ProjectList
    participant API
    participant Backend

    User->>HomePage: Navigate to /
    HomePage->>ProtectedRoute: Check authentication
    alt Not authenticated
        ProtectedRoute->>User: Redirect to /login
    else Authenticated
        ProtectedRoute->>ProjectList: Render component
        ProjectList->>API: GET /api/projects
        API->>Backend: Fetch user projects
        Backend-->>API: Return projects list
        API-->>ProjectList: Projects data
        
        loop For each project
            ProjectList->>API: GET /api/projects/{id}/agents
            API->>Backend: Fetch agent status
            Backend-->>API: Return agents
            API-->>ProjectList: Agent data
        end
        
        ProjectList->>User: Display projects with details
        
        alt User clicks "Create New Project"
            User->>ProjectList: Click button
            ProjectList->>ProjectList: Show creation form
        else User clicks project card
            User->>ProjectList: Click project
            ProjectList->>User: Navigate to /projects/{id}
        end
    end

Loading

Data Flow

Component	Data Source	Data Displayed
HomePage	N/A	Container for ProjectList
ProjectList	/api/projects	Project name, description, status, phase, created date
ProjectList	/api/projects/{id}/agents	Agent count, status (active/idle/blocked)
ProjectList	Project config	Deployment URLs (test, staging, production)
ProjectCreationForm	User input	Inline form when "Create New Project" clicked

Key Files Modified

1. file:web-ui/src/app/page.tsx - Transform to project list page
2. file:web-ui/src/components/ProjectList.tsx - Enhance with agent status and deployment URLs
3. file:web-ui/src/types/project.ts - Add new type definitions
4. file:web-ui/src/lib/api.ts - Verify API methods (minimal changes)
5. file:web-ui/src/app/__tests__/page.test.tsx - Update tests

Implementation Priority

1. P0 (Critical): Update home page to show project list with basic information
2. P0 (Critical): Wrap home page with ProtectedRoute for authentication
3. P1 (High): Add agent status display to project cards
4. P2 (Medium): Add deployment URL links (if data available)
5. P2 (Medium): Update tests for new home page behavior

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has:
- A home page (`file:web-ui/src/app/page.tsx`) that directly shows a project creation form
- An existing `ProjectList` component (`file:web-ui/src/components/ProjectList.tsx`) that displays projects in a grid with status, phase, and creation date
- Backend API endpoint `/api/projects` that returns project data including `id`, `name`, `description`, `status`, `phase`, `created_at`, and `config`
- Agent API endpoint `/api/projects/{project_id}/agents` that returns agent information including status and current task
- Authentication flow using `AuthContext` and `ProtectedRoute` components
- Navigation component that shows on all pages except login/signup

## Approach

The solution involves transforming the home page from a direct project creation form to a project list page with a "Create New Project" button. The `ProjectList` component already exists and handles most requirements, but needs enhancement to display agent status and deployment URLs. The home page will be wrapped with `ProtectedRoute` to ensure authentication, and the project list will show comprehensive project information including running agents, their status, and deployment environment links when available. The project creation form will remain accessible via a button that opens it inline or navigates to a dedicated route.

## Implementation Steps

### 1. Update Home Page to Display Project List

**File:** `file:web-ui/src/app/page.tsx`

Replace the current project creation form with the `ProjectList` component:
- Remove the `ProjectCreationForm` import and related state management
- Import and render the `ProjectList` component instead
- Wrap the entire page with `ProtectedRoute` to ensure only authenticated users can access it
- Update the page title and description to reflect "Your Projects" instead of "Welcome to CodeFRAME"
- Keep the same layout structure but replace the form content with the project list

### 2. Enhance ProjectList Component

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

Extend the component to display additional project information:
- Add agent status display for each project by fetching from `/api/projects/{projectId}/agents`
- Show count of active agents and their current status (idle, working, blocked)
- Display project description in the project card
- Add deployment URL links if available in project config (test, staging, production environments)
- Enhance the project card layout to accommodate the new information
- Use SWR for efficient data fetching and caching of agent data
- Add loading states for agent information
- Display "No agents running" when no agents are active

**Layout structure for each project card:**
```
┌─────────────────────────────────────┐
│ Project Name                        │
│ Description: [project description]  │
│ Status: [status] | Phase: [phase]   │
│ Agents: [X active, Y idle]          │
│ Created: [date]                     │
│ Links: [Test] [Staging] [Production]│
└─────────────────────────────────────┘
```

### 3. Create Type Definitions for Enhanced Project Data

**File:** `file:web-ui/src/types/project.ts`

Add new type definitions:
- `ProjectWithAgents` interface extending the existing `Project` type
- `AgentSummary` interface for agent status display
- `DeploymentUrls` interface for environment links
- Update existing types to include optional deployment URL fields

### 4. Update API Client

**File:** `file:web-ui/src/lib/api.ts`

Add new API methods if needed:
- Ensure `projectsApi.list()` returns all necessary project fields including description
- Verify `agentsApi.list(projectId)` returns agent status information
- Add helper function to extract deployment URLs from project config if not already available

### 5. Update Navigation Flow

**File:** `file:web-ui/src/components/Navigation.tsx`

Ensure the navigation properly handles the new home page:
- Verify the "CodeFRAME" logo link points to "/" (home page with project list)
- Ensure navigation remains consistent across authenticated pages

### 6. Handle Empty State

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

The component already handles the empty state, but verify:
- "No projects yet. Create your first project!" message is displayed when no projects exist
- The "Create New Project" button is prominently displayed
- The empty state is visually appealing and guides users to create their first project

### 7. Update Project Detail Page Navigation

**File:** `file:web-ui/src/app/projects/[projectId]/page.tsx`

Ensure the project detail page has a way to return to the project list:
- Add a "Back to Projects" link or button in the project detail view
- This may require updating the `Dashboard` component or adding navigation in the layout

### 8. Add Deployment URL Support (Future Enhancement)

**Backend Files:** `file:codeframe/core/config.py`, `file:codeframe/ui/models.py`

If deployment URLs are not currently stored:
- Add optional `deployment_urls` field to `ProjectConfig` in `file:codeframe/core/config.py`
- Update `ProjectResponse` model in `file:codeframe/ui/models.py` to include deployment URLs
- Update project creation/update endpoints to accept and store deployment URLs
- This may be deferred if deployment URLs are not yet a requirement

### 9. Testing Considerations

**Files:** `file:web-ui/src/app/__tests__/page.test.tsx`

Update existing tests:
- Modify home page tests to expect project list instead of creation form
- Add tests for authenticated access (ProtectedRoute behavior)
- Add tests for project list rendering with various data states
- Test agent status display
- Test deployment URL links when available

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant HomePage
    participant ProjectList
    participant API
    participant Backend

    User->>HomePage: Navigate to /
    HomePage->>ProtectedRoute: Check authentication
    alt Not authenticated
        ProtectedRoute->>User: Redirect to /login
    else Authenticated
        ProtectedRoute->>ProjectList: Render component
        ProjectList->>API: GET /api/projects
        API->>Backend: Fetch user projects
        Backend-->>API: Return projects list
        API-->>ProjectList: Projects data
        
        loop For each project
            ProjectList->>API: GET /api/projects/{id}/agents
            API->>Backend: Fetch agent status
            Backend-->>API: Return agents
            API-->>ProjectList: Agent data
        end
        
        ProjectList->>User: Display projects with details
        
        alt User clicks "Create New Project"
            User->>ProjectList: Click button
            ProjectList->>ProjectList: Show creation form
        else User clicks project card
            User->>ProjectList: Click project
            ProjectList->>User: Navigate to /projects/{id}
        end
    end
```

## Data Flow

| Component | Data Source | Data Displayed |
|-----------|-------------|----------------|
| HomePage | N/A | Container for ProjectList |
| ProjectList | `/api/projects` | Project name, description, status, phase, created date |
| ProjectList | `/api/projects/{id}/agents` | Agent count, status (active/idle/blocked) |
| ProjectList | Project config | Deployment URLs (test, staging, production) |
| ProjectCreationForm | User input | Inline form when "Create New Project" clicked |

## Key Files Modified

1. `file:web-ui/src/app/page.tsx` - Transform to project list page
2. `file:web-ui/src/components/ProjectList.tsx` - Enhance with agent status and deployment URLs
3. `file:web-ui/src/types/project.ts` - Add new type definitions
4. `file:web-ui/src/lib/api.ts` - Verify API methods (minimal changes)
5. `file:web-ui/src/app/__tests__/page.test.tsx` - Update tests

## Implementation Priority

1. **P0 (Critical):** Update home page to show project list with basic information
2. **P0 (Critical):** Wrap home page with ProtectedRoute for authentication
3. **P1 (High):** Add agent status display to project cards
4. **P2 (Medium):** Add deployment URL links (if data available)
5. **P2 (Medium):** Update tests for new home page behavior

---

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

Related Issues

• After creating a project on the main screen, the app returns to the create project screen #94
• The project discovery process doesn't kick off on new project creation #170

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