ai-wpa/todo/services-backend-integration.md

# Services Backend Integration

## Overview
The Active Services Management UI is complete, but requires backend API integration to replace dummy data and implement real functionality for service management, configuration downloads, and service operations.

## Current Status
- ✅ Frontend UI complete with service cards, action buttons, and empty states
- ✅ Service-specific download buttons (Kubernetes config, Hosting config) 
- ✅ Settings/configuration buttons with tooltips
- ❌ Backend API integration pending
- ❌ Real service data fetching not implemented
- ❌ Actual download functionality not connected

## Backend APIs Required

### 1. Get Active Services
```typescript
GET /api/services/active
Response: {
  success: boolean
  data: Service[]
}

interface Service {
  id: string
  name: string
  serviceId: string
  billingId: string
  clusterId?: string
  startDate: string
  nextBilling: string
  status: 'active' | 'suspended' | 'cancelled'
  type: 'hosting' | 'kubernetes' | 'database' | 'domain' | 'vps' | 'cloud'
}
```

### 2. Service Configuration/Settings
```typescript
GET /api/services/{serviceId}/config
POST /api/services/{serviceId}/config
Response: Service configuration data
```

### 3. Download Service Configurations
```typescript
GET /api/services/download/kubernetes/{clusterId}
GET /api/services/download/hosting/{billingId}
Response: File download (ZIP, YAML, etc.)
```

### 4. Service Management Actions
```typescript
POST /api/services/{serviceId}/suspend
POST /api/services/{serviceId}/resume  
DELETE /api/services/{serviceId}
```

## Frontend Integration Tasks

### Phase 1: Data Integration
- [ ] Replace mock data with API calls
- [ ] Implement service fetching with loading states
- [ ] Add error handling for API failures
- [ ] Implement proper TypeScript interfaces

### Phase 2: Download Functionality
- [ ] Implement Kubernetes config download
- [ ] Implement hosting config download
- [ ] Add download progress indicators
- [ ] Handle download errors gracefully

### Phase 3: Service Management
- [ ] Connect settings buttons to service configuration
- [ ] Implement service suspension/resumption
- [ ] Add service deletion with confirmation
- [ ] Real-time service status updates

### Phase 4: Enhanced Features
- [ ] Service usage statistics
- [ ] Service health monitoring
- [ ] Automated service alerts
- [ ] Service upgrade/downgrade options

## Database Schema Requirements

### Services Table
```sql
CREATE TABLE services (
  id VARCHAR(255) PRIMARY KEY,
  user_id VARCHAR(255) NOT NULL,
  service_id VARCHAR(255) UNIQUE NOT NULL,
  billing_id VARCHAR(255),
  cluster_id VARCHAR(255),
  name VARCHAR(255) NOT NULL,
  type ENUM('hosting', 'kubernetes', 'database', 'domain', 'vps', 'cloud'),
  status ENUM('active', 'suspended', 'cancelled') DEFAULT 'active',
  start_date DATETIME NOT NULL,
  next_billing_date DATETIME,
  config JSON,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  INDEX idx_user_status (user_id, status),
  INDEX idx_service_type (type),
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);
```

## Implementation Steps

### Step 1: API Route Creation
1. Create `/api/services/active` route
2. Create `/api/services/download/[type]/[id]` route  
3. Create `/api/services/[serviceId]/config` route
4. Add authentication middleware to all routes

### Step 2: Frontend Service Integration
1. Create `useServices` hook for state management
2. Replace mock data with API calls
3. Add loading and error states to components
4. Implement proper TypeScript interfaces

### Step 3: Download Implementation
1. Implement file download logic for different service types
2. Generate Kubernetes YAML configs dynamically
3. Create hosting configuration files
4. Add download progress tracking

### Step 4: Service Management
1. Add service configuration modal/page
2. Implement service suspension/cancellation
3. Add confirmation dialogs for destructive actions
4. Real-time status updates via WebSocket/polling

## Security Considerations

### Authentication & Authorization
- Ensure user can only access their own services
- Validate service ownership before operations
- Rate limiting for download endpoints
- Secure file generation and cleanup

### Data Protection
- Sanitize service configuration data
- Encrypt sensitive service credentials
- Audit logging for service operations
- Secure temporary file handling

## Testing Requirements

### Unit Tests
- Service API route handlers
- Service data transformation
- Download file generation
- Error handling scenarios

### Integration Tests
- End-to-end service management flow
- File download functionality
- Service configuration updates
- Authentication and authorization

### Performance Tests
- Large service list rendering
- Concurrent download requests
- Service configuration loading
- Database query optimization

## Error Handling

### API Error Responses
```typescript
interface APIError {
  success: false
  error: {
    code: string
    message: string
    details?: any
  }
}
```

### Common Error Scenarios
- Service not found (404)
- Unauthorized access (403)
- Service configuration errors (500)
- Download generation failures (500)
- Rate limiting exceeded (429)

## Future Enhancements

### Advanced Features
- Service monitoring dashboard
- Automated service scaling
- Service backup management
- Cost optimization suggestions
- Service dependency mapping

### Integration Possibilities
- Third-party monitoring tools
- Payment gateway integration
- Infrastructure automation
- Service mesh integration
- Container orchestration platforms

## Estimated Implementation Time
- **Phase 1** (Data Integration): 4-6 hours
- **Phase 2** (Download Functionality): 6-8 hours  
- **Phase 3** (Service Management): 8-10 hours
- **Phase 4** (Enhanced Features): 10-15 hours

**Total Estimated Time**: 28-39 hours (4-5 development sessions)

## Dependencies
- User authentication system (complete)
- Database models for services
- File generation utilities
- Service configuration templates
- Download handling middleware

## Success Criteria
- ✅ Real service data displays correctly
- ✅ Download buttons generate and serve actual files
- ✅ Service management operations work reliably
- ✅ Error states handled gracefully
- ✅ Performance meets requirements (< 2s load time)
- ✅ Security audit passes

---
**Created**: 2025-08-06  
**Priority**: High - Core functionality  
**Status**: Ready for backend implementation  
**Next Session**: Begin Phase 1 (Data Integration)