PARALLEL_INTEGRATION_PROMPT.MD

# Parallel Frontend-Backend Integration Execution Prompt

## PROJECT CONTEXT
**Project**: Pastebin Viewer Application
**Current State**: Backend API functional, Frontend displaying mock data
**Objective**: Complete frontend-backend integration using parallel agent execution
**Timeline**: 2-3 days maximum
**Execution Mode**: Parallel with defined synchronization points

## CURRENT SYSTEM STATE

### Backend (Kotlin/Spring Boot) - PORT 8080
- ✅ All API endpoints operational
- ✅ Database populated with test data
- ✅ Health checks passing
- ✅ CORS configured
- ✅ Actuator endpoints available

### Frontend (React/TypeScript) - PORT 5173
- ❌ Using hardcoded mock data (`mockStats`)
- ✅ Vite proxy configured correctly
- ✅ API service layer exists but unused
- ❌ Pages showing placeholder content
- ✅ Type definitions present

## PARALLEL EXECUTION PLAN

### PHASE 0: INITIAL VERIFICATION (15 minutes)
**Both Agents Execute Simultaneously**

#### Backend Agent Tasks:
```bash
# Verify backend is running and healthy
curl http://localhost:8080/actuator/health
curl http://localhost:8080/api/stats
curl http://localhost:8080/api/pastes?page=0&size=10

# Check database has data
# Log first 5 pastes with classifications
```

#### Frontend Agent Tasks:
```bash
# Verify frontend dev server is running
curl http://localhost:5173

# Check current mock data structure
# Document all hardcoded values in use
# List all API endpoints that need connection
```

**Synchronization Point 0**: Both agents confirm systems are ready

---

### PHASE 1: FOUNDATION SETUP (30 minutes)
**Parallel Execution with No Dependencies**

#### Backend Agent Tasks:
1. **Create Integration Test Endpoints**
   - `/api/test/connection` - Simple ping endpoint
   - `/api/test/data-summary` - Returns count of pastes, classifications
   - Document actual API response formats

2. **Verify API Contracts**
   - Test each endpoint and document exact response structure
   - Create sample responses for frontend reference
   - File: `/backend/docs/API_RESPONSE_SAMPLES.md`

3. **Add CORS Debug Logging**
   - Enable detailed CORS logging
   - Verify headers are correctly set

#### Frontend Agent Tasks:
1. **Create React Hooks Infrastructure**
   ```typescript
   // /frontend/src/hooks/useApi.ts
   export const useApi = <T>(
     apiCall: () => Promise<T>,
     deps: any[] = []
   ) => {
     const [data, setData] = useState<T | null>(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState<string | null>(null);

     useEffect(() => {
       const fetchData = async () => {
         try {
           setLoading(true);
           setError(null);
           const result = await apiCall();
           setData(result);
         } catch (err) {
           setError(err.message || 'API call failed');
         } finally {
           setLoading(false);
         }
       };

       fetchData();
     }, deps);

     return { data, loading, error, refetch: fetchData };
   };
   ```

2. **Create Common Components**
   - `/frontend/src/components/common/LoadingSpinner.tsx` (if not exists)
   - `/frontend/src/components/common/ErrorBoundary.tsx`
   - `/frontend/src/components/common/RetryError.tsx`

3. **Update Type Definitions**
   - Align with backend response structures
   - Add pagination types
   - Add API error types

**Synchronization Point 1**: Share API response samples between agents

---

### PHASE 2: DASHBOARD INTEGRATION (45 minutes)
**Sequential within phase, parallel between agents**

#### Backend Agent Tasks:
1. **Create Aggregated Stats Endpoint**
   ```kotlin
   @GetMapping("/api/dashboard/stats")
   fun getDashboardStats(): DashboardStats {
     return DashboardStats(
       totalPastes = pasteService.getTotalCount(),
       recentPastes = pasteService.getRecentCount(24.hours),
       classifications = classificationService.getCountByType(),
       systemHealth = healthService.getSystemStatus(),
       lastScrapingTime = scrapingService.getLastRunTime(),
       queueSize = kafkaService?.getQueueSize() ?: 0
     )
   }
   ```

2. **Add Real-time Metrics**
   - Response time metrics
   - Active connections count
   - Error rate calculation

#### Frontend Agent Tasks:
1. **Replace Mock Data in App.tsx**
   ```typescript
   // REMOVE: import { mockStats } from '@/services/mockData';
   // ADD:
   import { apiService } from '@/services/api';
   import { useApi } from '@/hooks/useApi';

   function App() {
     const { data: stats, loading, error, refetch } = useApi(
       () => apiService.getDashboardStats(),
       []
     );

     // Auto-refresh every 30 seconds
     useEffect(() => {
       const interval = setInterval(refetch, 30000);
       return () => clearInterval(interval);
     }, [refetch]);

     if (loading) return <LoadingSpinner fullScreen />;
     if (error) return <ErrorMessage message={error} onRetry={refetch} />;
     if (!stats) return <EmptyState message="No data available" />;

     // Rest of component...
   }
   ```

2. **Update Dashboard Component**
   - Add refresh button
   - Show last updated timestamp
   - Implement skeleton loading for cards

**Validation Checkpoint**: Dashboard shows real backend data

---

### PHASE 3: PASTES PAGE IMPLEMENTATION (1 hour)
**Agents work on complementary tasks**

#### Backend Agent Tasks:
1. **Optimize Paste Endpoints**
   ```kotlin
   @GetMapping("/api/pastes")
   fun getPastes(
     @RequestParam(defaultValue = "0") page: Int,
     @RequestParam(defaultValue = "20") size: Int,
     @RequestParam(required = false) search: String?,
     @RequestParam(required = false) classification: String?,
     @RequestParam(defaultValue = "createdAt,desc") sort: String
   ): Page<PasteDto>
   ```

2. **Add Paste Details Endpoint**
   ```kotlin
   @GetMapping("/api/pastes/{id}/full")
   fun getPasteWithDetails(@PathVariable id: String): PasteDetailsDto
   ```

3. **Create Search Suggestions Endpoint**
   ```kotlin
   @GetMapping("/api/pastes/suggestions")
   fun getSearchSuggestions(@RequestParam query: String): List<String>
   ```

#### Frontend Agent Tasks:
1. **Create Paste List Components**
   ```typescript
   // /frontend/src/components/pastes/PasteList.tsx
   export const PasteList: React.FC = () => {
     const [page, setPage] = useState(0);
     const [filters, setFilters] = useState<PasteFilters>({});

     const { data, loading, error } = useApi(
       () => apiService.getPastes(page, 20, filters),
       [page, filters]
     );

     return (
       <div className="space-y-4">
         <PasteFilters onChange={setFilters} />
         {loading && <LoadingSpinner />}
         {error && <ErrorMessage message={error} />}
         {data && (
           <>
             <div className="grid gap-4">
               {data.content.map(paste => (
                 <PasteCard key={paste.id} paste={paste} />
               ))}
             </div>
             <Pagination
               current={page}
               total={data.totalPages}
               onChange={setPage}
             />
           </>
         )}
       </div>
     );
   };
   ```

2. **Implement Pastes Page**
   - Replace placeholder content
   - Add paste details modal
   - Implement search functionality

**Validation Checkpoint**: Pastes page displays paginated data from backend

---

### PHASE 4: CLASSIFICATIONS PAGE (45 minutes)
**Parallel implementation with shared components**

#### Backend Agent Tasks:
1. **Create Classification Statistics Endpoint**
   ```kotlin
   @GetMapping("/api/classifications/statistics")
   fun getClassificationStats(): ClassificationStats

   @GetMapping("/api/classifications/timeline")
   fun getClassificationTimeline(
     @RequestParam days: Int = 7
   ): List<TimelineEntry>
   ```

2. **Add Filtering Capabilities**
   ```kotlin
   @GetMapping("/api/classifications")
   fun getClassifications(
     @RequestParam(required = false) type: ClassificationType?,
     @RequestParam(required = false) minConfidence: Double?,
     @RequestParam(required = false) startDate: LocalDateTime?,
     @RequestParam(required = false) endDate: LocalDateTime?
   ): Page<ClassificationDto>
   ```

#### Frontend Agent Tasks:
1. **Create Classification Components**
   ```typescript
   // /frontend/src/components/classifications/ClassificationList.tsx
   export const ClassificationList: React.FC = () => {
     const [filters, setFilters] = useState<ClassificationFilters>({
       type: null,
       minConfidence: 0.5,
       dateRange: 'week'
     });

     const { data, loading, error } = useApi(
       () => apiService.getClassifications(filters),
       [filters]
     );

     // Component implementation
   };
   ```

2. **Add Visualization Components**
   - Classification type distribution chart
   - Confidence score histogram
   - Timeline graph

**Validation Checkpoint**: Classifications page shows filtered results

---

### PHASE 5: ERROR HANDLING & RESILIENCE (30 minutes)
**Both agents implement complementary error handling**

#### Backend Agent Tasks:
1. **Implement Global Exception Handler**
   ```kotlin
   @RestControllerAdvice
   class GlobalExceptionHandler {
     @ExceptionHandler(ResourceNotFoundException::class)
     fun handleNotFound(e: ResourceNotFoundException): ResponseEntity<ApiError> {
       return ResponseEntity.status(404).body(
         ApiError(
           timestamp = Instant.now(),
           status = 404,
           error = "Not Found",
           message = e.message ?: "Resource not found",
           path = request.servletPath
         )
       )
     }
   }
   ```

2. **Add Circuit Breaker for External Services**
3. **Implement Request Validation**

#### Frontend Agent Tasks:
1. **Create Toast Notification System**
   ```typescript
   // /frontend/src/contexts/ToastContext.tsx
   export const useToast = () => {
     const show = (message: string, type: 'success' | 'error' | 'info') => {
       // Implementation
     };

     return { show };
   };
   ```

2. **Add Retry Logic to API Service**
   ```typescript
   const retryWithBackoff = async <T>(
     fn: () => Promise<T>,
     maxRetries = 3
   ): Promise<T> => {
     for (let i = 0; i < maxRetries; i++) {
       try {
         return await fn();
       } catch (error) {
         if (i === maxRetries - 1) throw error;
         await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
       }
     }
     throw new Error('Max retries exceeded');
   };
   ```

3. **Implement Offline Detection**

**Validation Checkpoint**: Error scenarios handled gracefully

---

### PHASE 6: REAL-TIME UPDATES (30 minutes)
**Optional - Implement if time permits**

#### Backend Agent Tasks:
1. **Add SSE Endpoint for Live Updates**
   ```kotlin
   @GetMapping("/api/stream/updates", produces = [MediaType.TEXT_EVENT_STREAM_VALUE])
   fun streamUpdates(): Flux<ServerSentEvent<UpdateEvent>>
   ```

2. **Implement Change Detection Service**

#### Frontend Agent Tasks:
1. **Create SSE Hook**
   ```typescript
   export const useServerSentEvents = (url: string) => {
     const [events, setEvents] = useState<any[]>([]);

     useEffect(() => {
       const eventSource = new EventSource(url);

       eventSource.onmessage = (event) => {
         const data = JSON.parse(event.data);
         setEvents(prev => [...prev, data]);
       };

       return () => eventSource.close();
     }, [url]);

     return events;
   };
   ```

2. **Add Live Update Indicators**
   - New paste notifications
   - Classification completion alerts

---

### PHASE 7: TESTING & VALIDATION (45 minutes)
**Both agents run comprehensive tests**

#### Backend Agent Tasks:
1. **Integration Test Suite**
   ```kotlin
   @Test
   fun `should return dashboard stats`() {
     val stats = restTemplate.getForObject(
       "http://localhost:8080/api/dashboard/stats",
       DashboardStats::class.java
     )

     assertThat(stats).isNotNull
     assertThat(stats.totalPastes).isGreaterThan(0)
   }
   ```

2. **Load Testing**
   ```bash
   # Using Apache Bench
   ab -n 1000 -c 10 http://localhost:8080/api/pastes
   ```

#### Frontend Agent Tasks:
1. **Component Tests**
   ```typescript
   describe('PasteList', () => {
     it('should fetch and display pastes', async () => {
       render(<PasteList />);

       await waitFor(() => {
         expect(screen.getByText(/paste title/i)).toBeInTheDocument();
       });
     });

     it('should handle API errors', async () => {
       // Mock API error
       apiService.getPastes = jest.fn().mockRejectedValue(new Error('API Error'));

       render(<PasteList />);

       await waitFor(() => {
         expect(screen.getByText(/API Error/i)).toBeInTheDocument();
       });
     });
   });
   ```

2. **E2E Test Scenarios**
   - User journey from dashboard to paste details
   - Filter and search functionality
   - Error recovery flows

---

## ERROR HANDLING STRATEGIES

### Backend Agent Error Handling:
1. **Database Connection Lost**: Implement retry with exponential backoff
2. **Kafka Unavailable**: Fallback to direct database writes
3. **External API Timeout**: Circuit breaker pattern
4. **Out of Memory**: Implement request throttling

### Frontend Agent Error Handling:
1. **Network Failure**: Show offline banner, queue actions
2. **401 Unauthorized**: Redirect to login (if auth implemented)
3. **500 Server Error**: Show friendly error with retry
4. **Timeout**: Show timeout message with retry option

## ROLLBACK PROCEDURES

### If Integration Fails:
1. **Frontend Rollback**:
   ```bash
   # Revert to mock data
   git checkout -- frontend/src/App.tsx
   npm run dev
   ```

2. **Backend Rollback**:
   ```bash
   # Revert to previous version
   git checkout -- backend/src/main/kotlin/
   ./gradlew bootRun
   ```

## SUCCESS CRITERIA

### Must Have (Critical):
- [ ] Dashboard displays real backend data
- [ ] Pastes list loads with pagination
- [ ] Classifications page shows data
- [ ] No console errors in production mode
- [ ] API error handling works

### Should Have (Important):
- [ ] Auto-refresh on dashboard
- [ ] Search functionality works
- [ ] Filters work correctly
- [ ] Loading states for all async operations
- [ ] Toast notifications for actions

### Nice to Have (Optional):
- [ ] Real-time updates via SSE/WebSocket
- [ ] Offline mode support
- [ ] Advanced search with suggestions
- [ ] Export functionality
- [ ] Keyboard shortcuts

## VALIDATION COMMANDS

### Backend Validation:
```bash
# Health check
curl http://localhost:8080/actuator/health

# Stats endpoint
curl http://localhost:8080/api/dashboard/stats | jq .

# Pastes with pagination
curl "http://localhost:8080/api/pastes?page=0&size=5" | jq .

# Classifications
curl http://localhost:8080/api/classifications | jq .
```

### Frontend Validation:
```bash
# Build check
cd frontend && npm run build

# Type check
npm run type-check

# Test suite
npm test

# Lint check
npm run lint
```

### Integration Validation:
```bash
# Check proxy is working
curl http://localhost:5173/api/health

# Check CORS headers
curl -H "Origin: http://localhost:5173" \
     -I http://localhost:8080/api/pastes

# Monitor network tab in browser DevTools
# Should see API calls to /api/* endpoints
```

## COMMON ISSUES & SOLUTIONS

### Issue: CORS Errors
**Solution**: Ensure backend has proper CORS configuration:
```kotlin
@CrossOrigin(origins = ["http://localhost:5173"])
```

### Issue: Type Mismatches
**Solution**: Generate types from backend OpenAPI spec or manually align

### Issue: Proxy Not Working
**Solution**: Verify vite.config.ts proxy configuration:
```typescript
proxy: {
  '/api': {
    target: 'http://localhost:8080',
    changeOrigin: true,
    secure: false
  }
}
```

### Issue: Data Not Updating
**Solution**: Check React dependency arrays in useEffect hooks

### Issue: Memory Leaks
**Solution**: Clean up intervals/subscriptions in useEffect cleanup

## EXECUTION NOTES

1. **Communication Protocol**:
   - Agents should log progress every 15 minutes
   - Use clear markers for synchronization points
   - Document any blockers immediately

2. **File Organization**:
   - Backend changes: `/backend/src/main/kotlin/`
   - Frontend changes: `/frontend/src/`
   - Shared docs: `/docs/integration/`

3. **Testing Protocol**:
   - Test each phase before moving to next
   - Keep both systems running during integration
   - Use browser DevTools Network tab to monitor API calls

4. **Performance Targets**:
   - API response time < 200ms (P95)
   - Frontend initial load < 2 seconds
   - Smooth scrolling with 100+ items

## FINAL CHECKLIST

### Before Starting:
- [ ] Backend running on port 8080
- [ ] Frontend running on port 5173
- [ ] Database has test data
- [ ] All dependencies installed

### After Completion:
- [ ] All mock data removed
- [ ] All API endpoints connected
- [ ] Error handling implemented
- [ ] Loading states implemented
- [ ] Tests passing
- [ ] No console errors
- [ ] Documentation updated

## AGENT COORDINATION MARKERS

Use these markers in your responses for clarity:

```
[BACKEND-AGENT: PHASE_1_START]
[FRONTEND-AGENT: PHASE_1_START]
[SYNC_POINT_1: READY]
[VALIDATION: DASHBOARD_CONNECTED]
[BLOCKER: <description>]
[COMPLETE: PHASE_3]
```

---

**Execute this plan systematically. Prioritize working features over perfect code. Focus on getting the integration working end-to-end first, then optimize.**