[Future] ProjectList performance optimizations and test coverage

[frankbria]

Summary

Performance optimizations and test coverage improvements identified during code review of the home page feature.

Performance Optimizations

React.memo for Components

• Add React.memo to ProjectList component to prevent unnecessary re-renders
• Consider extracting ProjectCard as a memoized sub-component

useMemo for Computed Values

• Use useMemo for sorted/filtered projects array if sorting is added
• Memoize formatted dates to avoid recalculating on every render

useCallback for Event Handlers

• Wrap handleProjectClick in useCallback
• Wrap handleProjectKeyDown in useCallback
• Wrap handleSubmit, handleError, handleProjectCreated in useCallback

Test Coverage Gaps

Concurrent Project Creation

• Test behavior when user rapidly clicks "Create" multiple times
• Ensure form is disabled during creation to prevent duplicates

Discovery Failure Recovery

• Test user flow when discovery fails but project was created
• Verify project appears in list with correct status
• Test manual discovery restart from project dashboard

Network Timeout Handling

• Test behavior when API requests timeout
• Ensure loading states resolve properly on timeout
• Test retry mechanisms if implemented

Acceptance Criteria

• Performance: No unnecessary re-renders on project list updates
• Performance: Event handlers are stable references
• Tests: Concurrent creation scenario covered
• Tests: Discovery failure recovery covered
• Tests: Timeout handling covered

[traycerai]

Plan

Observations

The codebase has a well-structured React/Next.js frontend with TypeScript. The ProjectList component uses SWR for data fetching and includes a ProjectCreationForm. Current implementation lacks performance optimizations (React.memo, useCallback, useMemo) and has test coverage gaps around concurrent creation scenarios and timeout handling. The form already prevents concurrent submissions via isSubmitting state, but this needs explicit test coverage.

Approach

The plan focuses on two parallel tracks: (1) adding React performance optimizations to prevent unnecessary re-renders, and (2) filling test coverage gaps for edge cases. Performance optimizations will use React.memo for components, useCallback for event handlers, and useMemo for computed values. Test coverage will add scenarios for concurrent creation attempts, timeout handling, and verify discovery failure recovery works correctly.

Implementation Steps

Phase 1: Performance Optimizations

1.1 Optimize ProjectList Component (file:web-ui/src/components/ProjectList.tsx)

Add React.memo wrapper:

• Wrap the default export with React.memo to prevent re-renders when parent components update
• No custom comparison function needed since props are stable

Memoize event handlers with useCallback:

• Wrap handleProjectClick with useCallback - dependencies: [router]
• Wrap handleProjectCreated with useCallback - dependencies: [mutate]
• Wrap the inline setShowForm callbacks with useCallback where appropriate

Extract and memoize ProjectCard sub-component:

• Create a new memoized ProjectCard component inside the file (before the main component)
• Props: project, onClick, formatDate
• Wrap with React.memo to prevent re-renders when other projects change
• Move the project card JSX (lines 114-132) into this component

Memoize formatDate calls:

• Move formatDate function inside the component
• Wrap it with useCallback to create a stable reference
• Pass the memoized function to ProjectCard components

Add useMemo for projects array:

• Wrap const projects = data || [] with useMemo - dependencies: [data]
• This prepares for future sorting/filtering optimizations

1.2 Optimize ProjectCreationForm Component (file:web-ui/src/components/ProjectCreationForm.tsx)

Wrap event handlers with useCallback:

• Wrap handleSubmit with useCallback - dependencies: [name, description, errors, onSubmit, onSuccess, onError]
• Wrap validateName with useCallback - dependencies: [name, errors]
• Wrap validateDescription with useCallback - dependencies: [description, errors]

Add React.memo wrapper:

• Wrap the component export with React.memo
• Add custom comparison function to check if onSuccess, onSubmit, onError props have changed

1.3 Optimize HomePage Component (file:web-ui/src/app/page.tsx)

Wrap event handlers with useCallback:

• Wrap handleProjectCreated with useCallback - dependencies: [router]
• Wrap handleSubmit with useCallback - dependencies: []
• Wrap handleError with useCallback - dependencies: []

Phase 2: Test Coverage Enhancements

2.1 Add Concurrent Creation Tests (file:web-ui/src/components/__tests__/ProjectCreationForm.test.tsx)

Test: Rapid multiple submit clicks are prevented:

• Set up form with valid data
• Click submit button multiple times rapidly (3-5 times)
• Verify API is called only once
• Verify button shows "Creating..." state
• Verify all inputs remain disabled until completion

Test: Form re-enables after successful creation:

• Submit form successfully
• Verify isSubmitting returns to false
• Verify form can be submitted again (if not unmounted)

Test: Form re-enables after error:

• Submit form with error response
• Verify isSubmitting returns to false
• Verify form can be submitted again

2.2 Add Discovery Failure Recovery Tests (file:web-ui/src/app/__tests__/page.test.tsx)

Test: Project appears in list after creation despite discovery failure:

• Mock projectsApi.createProject to succeed
• Mock projectsApi.startProject to fail
• Mock projectsApi.list to return the new project
• Trigger project creation
• Verify redirect happens to /projects/:id
• Verify console.error was called with discovery failure message

Test: User can manually restart discovery from dashboard:

• This is more of an integration test scenario
• Document that manual restart is handled by the project dashboard page
• Verify the redirect happens correctly so user lands on dashboard

2.3 Add Timeout Handling Tests

In file:web-ui/src/components/__tests__/ProjectCreationForm.test.tsx:

Test: API timeout during project creation:

• Mock projectsApi.createProject to reject with timeout error (e.g., ECONNABORTED or custom timeout error)
• Submit form
• Verify error message displays: "Failed to create project. Please check your connection and try again."
• Verify onError callback is called
• Verify form re-enables for retry

Test: Loading state resolves on timeout:

• Mock API to timeout after delay
• Submit form
• Verify "Creating..." state shows
• Wait for timeout
• Verify form returns to normal state with error message

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

Test: Discovery start timeout:

• Mock projectsApi.createProject to succeed
• Mock projectsApi.startProject to timeout
• Verify redirect still happens (graceful degradation)
• Verify loading message changes from "Creating..." to "Starting discovery..."
• Verify user lands on project dashboard despite timeout

In file:web-ui/src/lib/__tests__/api.test.ts:

Test: projectsApi.createProject handles timeout:

• Mock axios to reject with timeout error
• Call projectsApi.createProject
• Verify promise rejects with timeout error

Test: projectsApi.startProject handles timeout:

• Mock axios to reject with timeout error
• Call projectsApi.startProject
• Verify promise rejects with timeout error

2.4 Add Performance/Re-render Tests (file:web-ui/src/components/__tests__/ProjectList.test.tsx)

Test: ProjectList doesn't re-render when parent updates:

• Wrap ProjectList in a parent component with state
• Update parent state
• Use React Testing Library's render count tracking or spy on component
• Verify ProjectList doesn't re-render unnecessarily

Test: Event handlers maintain stable references:

• Render ProjectList
• Get reference to event handler
• Trigger re-render (via SWR mutation)
• Verify event handler reference hasn't changed

Test: formatDate is not recalculated on every render:

• Mock formatDate to track call count
• Render ProjectList with projects
• Trigger re-render
• Verify formatDate is called only once per project (memoized)

Phase 3: Documentation Updates

3.1 Update Component Documentation

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

• Add JSDoc comment explaining React.memo usage and performance optimizations
• Document that ProjectCard is memoized to prevent unnecessary re-renders

In file:web-ui/src/components/ProjectCreationForm.tsx:

• Add JSDoc comment explaining concurrent submission prevention
• Document that form is disabled during submission to prevent duplicates

Implementation Flow

sequenceDiagram
    participant Dev as Developer
    participant PL as ProjectList.tsx
    participant PCF as ProjectCreationForm.tsx
    participant HP as HomePage (page.tsx)
    participant Tests as Test Files

    Note over Dev,Tests: Phase 1: Performance Optimizations
    Dev->>PL: Add React.memo wrapper
    Dev->>PL: Extract & memoize ProjectCard
    Dev->>PL: Wrap handlers with useCallback
    Dev->>PL: Add useMemo for computed values
    
    Dev->>PCF: Wrap handlers with useCallback
    Dev->>PCF: Add React.memo wrapper
    
    Dev->>HP: Wrap handlers with useCallback

    Note over Dev,Tests: Phase 2: Test Coverage
    Dev->>Tests: Add concurrent creation tests
    Dev->>Tests: Add discovery failure tests
    Dev->>Tests: Add timeout handling tests
    Dev->>Tests: Add re-render prevention tests

    Note over Dev,Tests: Phase 3: Verification
    Dev->>Tests: Run all tests
    Dev->>Tests: Verify coverage metrics
    Dev->>PL: Update documentation

Loading

Acceptance Criteria Mapping

Criterion	Implementation Location	Verification Method
No unnecessary re-renders	ProjectList.tsx with React.memo, useCallback, useMemo	Performance tests in ProjectList.test.tsx
Event handlers are stable	All three components with useCallback	Reference stability tests
Concurrent creation covered	ProjectCreationForm.test.tsx	New test cases for rapid clicks
Discovery failure recovery	page.test.tsx	Existing + new tests for timeout scenarios
Timeout handling covered	All test files	New timeout test cases across API, form, and page tests

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a well-structured React/Next.js frontend with TypeScript. The `ProjectList` component uses SWR for data fetching and includes a `ProjectCreationForm`. Current implementation lacks performance optimizations (React.memo, useCallback, useMemo) and has test coverage gaps around concurrent creation scenarios and timeout handling. The form already prevents concurrent submissions via `isSubmitting` state, but this needs explicit test coverage.

## Approach

The plan focuses on two parallel tracks: (1) adding React performance optimizations to prevent unnecessary re-renders, and (2) filling test coverage gaps for edge cases. Performance optimizations will use React.memo for components, useCallback for event handlers, and useMemo for computed values. Test coverage will add scenarios for concurrent creation attempts, timeout handling, and verify discovery failure recovery works correctly.

## Implementation Steps

### Phase 1: Performance Optimizations

#### 1.1 Optimize ProjectList Component (`file:web-ui/src/components/ProjectList.tsx`)

**Add React.memo wrapper:**
- Wrap the default export with `React.memo` to prevent re-renders when parent components update
- No custom comparison function needed since props are stable

**Memoize event handlers with useCallback:**
- Wrap `handleProjectClick` with `useCallback` - dependencies: `[router]`
- Wrap `handleProjectCreated` with `useCallback` - dependencies: `[mutate]`
- Wrap the inline `setShowForm` callbacks with `useCallback` where appropriate

**Extract and memoize ProjectCard sub-component:**
- Create a new memoized `ProjectCard` component inside the file (before the main component)
- Props: `project`, `onClick`, `formatDate`
- Wrap with `React.memo` to prevent re-renders when other projects change
- Move the project card JSX (lines 114-132) into this component

**Memoize formatDate calls:**
- Move `formatDate` function inside the component
- Wrap it with `useCallback` to create a stable reference
- Pass the memoized function to `ProjectCard` components

**Add useMemo for projects array:**
- Wrap `const projects = data || []` with `useMemo` - dependencies: `[data]`
- This prepares for future sorting/filtering optimizations

#### 1.2 Optimize ProjectCreationForm Component (`file:web-ui/src/components/ProjectCreationForm.tsx`)

**Wrap event handlers with useCallback:**
- Wrap `handleSubmit` with `useCallback` - dependencies: `[name, description, errors, onSubmit, onSuccess, onError]`
- Wrap `validateName` with `useCallback` - dependencies: `[name, errors]`
- Wrap `validateDescription` with `useCallback` - dependencies: `[description, errors]`

**Add React.memo wrapper:**
- Wrap the component export with `React.memo`
- Add custom comparison function to check if `onSuccess`, `onSubmit`, `onError` props have changed

#### 1.3 Optimize HomePage Component (`file:web-ui/src/app/page.tsx`)

**Wrap event handlers with useCallback:**
- Wrap `handleProjectCreated` with `useCallback` - dependencies: `[router]`
- Wrap `handleSubmit` with `useCallback` - dependencies: `[]`
- Wrap `handleError` with `useCallback` - dependencies: `[]`

### Phase 2: Test Coverage Enhancements

#### 2.1 Add Concurrent Creation Tests (`file:web-ui/src/components/__tests__/ProjectCreationForm.test.tsx`)

**Test: Rapid multiple submit clicks are prevented:**
- Set up form with valid data
- Click submit button multiple times rapidly (3-5 times)
- Verify API is called only once
- Verify button shows "Creating..." state
- Verify all inputs remain disabled until completion

**Test: Form re-enables after successful creation:**
- Submit form successfully
- Verify `isSubmitting` returns to false
- Verify form can be submitted again (if not unmounted)

**Test: Form re-enables after error:**
- Submit form with error response
- Verify `isSubmitting` returns to false
- Verify form can be submitted again

#### 2.2 Add Discovery Failure Recovery Tests (`file:web-ui/src/app/__tests__/page.test.tsx`)

**Test: Project appears in list after creation despite discovery failure:**
- Mock `projectsApi.createProject` to succeed
- Mock `projectsApi.startProject` to fail
- Mock `projectsApi.list` to return the new project
- Trigger project creation
- Verify redirect happens to `/projects/:id`
- Verify console.error was called with discovery failure message

**Test: User can manually restart discovery from dashboard:**
- This is more of an integration test scenario
- Document that manual restart is handled by the project dashboard page
- Verify the redirect happens correctly so user lands on dashboard

#### 2.3 Add Timeout Handling Tests

**In `file:web-ui/src/components/__tests__/ProjectCreationForm.test.tsx`:**

**Test: API timeout during project creation:**
- Mock `projectsApi.createProject` to reject with timeout error (e.g., `ECONNABORTED` or custom timeout error)
- Submit form
- Verify error message displays: "Failed to create project. Please check your connection and try again."
- Verify `onError` callback is called
- Verify form re-enables for retry

**Test: Loading state resolves on timeout:**
- Mock API to timeout after delay
- Submit form
- Verify "Creating..." state shows
- Wait for timeout
- Verify form returns to normal state with error message

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

**Test: Discovery start timeout:**
- Mock `projectsApi.createProject` to succeed
- Mock `projectsApi.startProject` to timeout
- Verify redirect still happens (graceful degradation)
- Verify loading message changes from "Creating..." to "Starting discovery..."
- Verify user lands on project dashboard despite timeout

**In `file:web-ui/src/lib/__tests__/api.test.ts`:**

**Test: projectsApi.createProject handles timeout:**
- Mock axios to reject with timeout error
- Call `projectsApi.createProject`
- Verify promise rejects with timeout error

**Test: projectsApi.startProject handles timeout:**
- Mock axios to reject with timeout error
- Call `projectsApi.startProject`
- Verify promise rejects with timeout error

#### 2.4 Add Performance/Re-render Tests (`file:web-ui/src/components/__tests__/ProjectList.test.tsx`)

**Test: ProjectList doesn't re-render when parent updates:**
- Wrap ProjectList in a parent component with state
- Update parent state
- Use React Testing Library's render count tracking or spy on component
- Verify ProjectList doesn't re-render unnecessarily

**Test: Event handlers maintain stable references:**
- Render ProjectList
- Get reference to event handler
- Trigger re-render (via SWR mutation)
- Verify event handler reference hasn't changed

**Test: formatDate is not recalculated on every render:**
- Mock formatDate to track call count
- Render ProjectList with projects
- Trigger re-render
- Verify formatDate is called only once per project (memoized)

### Phase 3: Documentation Updates

#### 3.1 Update Component Documentation

**In `file:web-ui/src/components/ProjectList.tsx`:**
- Add JSDoc comment explaining React.memo usage and performance optimizations
- Document that ProjectCard is memoized to prevent unnecessary re-renders

**In `file:web-ui/src/components/ProjectCreationForm.tsx`:**
- Add JSDoc comment explaining concurrent submission prevention
- Document that form is disabled during submission to prevent duplicates

## Implementation Flow

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant PL as ProjectList.tsx
    participant PCF as ProjectCreationForm.tsx
    participant HP as HomePage (page.tsx)
    participant Tests as Test Files

    Note over Dev,Tests: Phase 1: Performance Optimizations
    Dev->>PL: Add React.memo wrapper
    Dev->>PL: Extract & memoize ProjectCard
    Dev->>PL: Wrap handlers with useCallback
    Dev->>PL: Add useMemo for computed values
    
    Dev->>PCF: Wrap handlers with useCallback
    Dev->>PCF: Add React.memo wrapper
    
    Dev->>HP: Wrap handlers with useCallback

    Note over Dev,Tests: Phase 2: Test Coverage
    Dev->>Tests: Add concurrent creation tests
    Dev->>Tests: Add discovery failure tests
    Dev->>Tests: Add timeout handling tests
    Dev->>Tests: Add re-render prevention tests

    Note over Dev,Tests: Phase 3: Verification
    Dev->>Tests: Run all tests
    Dev->>Tests: Verify coverage metrics
    Dev->>PL: Update documentation
```

## Acceptance Criteria Mapping

| Criterion | Implementation Location | Verification Method |
|-----------|------------------------|---------------------|
| No unnecessary re-renders | `ProjectList.tsx` with React.memo, useCallback, useMemo | Performance tests in `ProjectList.test.tsx` |
| Event handlers are stable | All three components with useCallback | Reference stability tests |
| Concurrent creation covered | `ProjectCreationForm.test.tsx` | New test cases for rapid clicks |
| Discovery failure recovery | `page.test.tsx` | Existing + new tests for timeout scenarios |
| Timeout handling covered | All test files | New timeout test cases across API, form, and page tests |

---

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

---

🔗 Related PRs

#24 - feat: Implement project creation flow (011-project-creation-flow) [merged]
#176 - feat: Create project selection home page [merged]
#187 - refactor: Consolidate web-ui test files to tests/ directory [merged]
#196 - fix(discovery): Synchronize PRD buttons and fix state persistence on tab revisit [merged]
#211 - feat(dashboard): Add PhaseProgress component for phase visualization [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!

[frankbria]

Closing: v1 React home page component. Phase 3 web UI is a fresh build on v2 foundation.