Aniworld/FRONTEND_INTEGRATION.md

# Frontend Integration Changes

## Overview

This document details the changes made to integrate the existing frontend JavaScript with the new FastAPI backend and native WebSocket implementation.

## Key Changes

### 1. WebSocket Migration (Socket.IO → Native WebSocket)

**Files Created:**

-   `src/server/web/static/js/websocket_client.js` - Native WebSocket wrapper with Socket.IO-compatible interface

**Files Modified:**

-   `src/server/web/templates/index.html` - Replace Socket.IO CDN with websocket_client.js
-   `src/server/web/templates/queue.html` - Replace Socket.IO CDN with websocket_client.js

**Migration Details:**

-   Created `WebSocketClient` class that provides Socket.IO-style `.on()` and `.emit()` methods
-   Automatic reconnection with exponential backoff
-   Room-based subscriptions (join/leave rooms for topic filtering)
-   Message queueing during disconnection
-   Native WebSocket URL: `ws://host:port/ws/connect` (or `wss://` for HTTPS)

### 2. WebSocket Message Format Changes

**Old Format (Socket.IO custom events):**

```javascript
socket.on('download_progress', (data) => { ... });
// data was sent directly
```

**New Format (Structured messages):**

```javascript
{
    "type": "download_progress",
    "timestamp": "2025-10-17T12:34:56.789Z",
    "data": {
        // Message payload
    }
}
```

**Event Mapping:**

| Old Socket.IO Event     | New WebSocket Type  | Room                | Notes                      |
| ----------------------- | ------------------- | ------------------- | -------------------------- |
| `scan_progress`         | `scan_progress`     | `scan_progress`     | Scan updates               |
| `scan_completed`        | `scan_complete`     | `scan_progress`     | Scan finished              |
| `scan_error`            | `scan_failed`       | `scan_progress`     | Scan error                 |
| `download_progress`     | `download_progress` | `download_progress` | Real-time download updates |
| `download_completed`    | `download_complete` | `downloads`         | Single download finished   |
| `download_error`        | `download_failed`   | `downloads`         | Download failed            |
| `download_queue_update` | `queue_status`      | `downloads`         | Queue state changes        |
| `queue_started`         | `queue_started`     | `downloads`         | Queue processing started   |
| `queue_stopped`         | `queue_stopped`     | `downloads`         | Queue processing stopped   |
| `queue_paused`          | `queue_paused`      | `downloads`         | Queue paused               |
| `queue_resumed`         | `queue_resumed`     | `downloads`         | Queue resumed              |

### 3. API Endpoint Changes

**Authentication Endpoints:**

-   ✅ `/api/auth/status` - Check auth status (GET)
-   ✅ `/api/auth/login` - Login (POST)
-   ✅ `/api/auth/logout` - Logout (POST)
-   ✅ `/api/auth/setup` - Initial setup (POST)

**Anime Endpoints:**

-   ✅ `/api/v1/anime` - List anime with missing episodes (GET)
-   ✅ `/api/v1/anime/rescan` - Trigger rescan (POST)
-   ✅ `/api/v1/anime/search` - Search for anime (POST)
-   ✅ `/api/v1/anime/{anime_id}` - Get anime details (GET)

**Download Queue Endpoints:**

-   ✅ `/api/queue/status` - Get queue status (GET)
-   ✅ `/api/queue/add` - Add to queue (POST)
-   ✅ `/api/queue/{item_id}` - Remove single item (DELETE)
-   ✅ `/api/queue/` - Remove multiple items (DELETE)
-   ✅ `/api/queue/start` - Start queue (POST)
-   ✅ `/api/queue/stop` - Stop queue (POST)
-   ✅ `/api/queue/pause` - Pause queue (POST)
-   ✅ `/api/queue/resume` - Resume queue (POST)
-   ✅ `/api/queue/reorder` - Reorder queue (POST)
-   ✅ `/api/queue/completed` - Clear completed (DELETE)
-   ✅ `/api/queue/retry` - Retry failed (POST)

**WebSocket Endpoint:**

-   ✅ `/ws/connect` - WebSocket connection (WebSocket)
-   ✅ `/ws/status` - WebSocket status (GET)

### 4. Required JavaScript Updates

**app.js Changes Needed:**

1. **WebSocket Initialization** - Add room subscriptions:

```javascript
initSocket() {
    this.socket = io();

    // Subscribe to relevant rooms after connection
    this.socket.on('connected', () => {
        this.socket.join('scan_progress');
        this.socket.join('download_progress');
        this.socket.join('downloads');
        this.isConnected = true;
        // ... rest of connect handler
    });

    // ... rest of event handlers
}
```

2. **Event Handler Updates** - Map new message types:

-   `scan_completed` → `scan_complete`
-   `scan_error` → `scan_failed`
-   Legacy events that are no longer sent need to be handled differently or removed

3. **API Call Updates** - Already correct:

-   `/api/v1/anime` for anime list ✅
-   `/api/auth/*` for authentication ✅

**queue.js Changes Needed:**

1. **WebSocket Initialization** - Add room subscriptions:

```javascript
initSocket() {
    this.socket = io();

    this.socket.on('connected', () => {
        this.socket.join('downloads');
        this.socket.join('download_progress');
        // ... rest of connect handler
    });

    // ... rest of event handlers
}
```

2. **API Calls** - Already mostly correct:

-   `/api/queue/status` ✅
-   `/api/queue/*` operations ✅

3. **Event Handlers** - Map to new types:

-   `queue_updated` → `queue_status`
-   `download_progress_update` → `download_progress`

### 5. Authentication Flow

**Current Implementation:**

-   JWT tokens stored in localStorage (via auth service)
-   Tokens included in Authorization header for API requests
-   WebSocket connections can optionally authenticate (user_id in session)

**JavaScript Implementation Needed:**
Add helper for authenticated requests:

```javascript
async makeAuthenticatedRequest(url, options = {}) {
    const token = localStorage.getItem('auth_token');

    if (!token) {
        window.location.href = '/login';
        return null;
    }

    const headers = {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`,
        ...options.headers
    };

    const response = await fetch(url, { ...options, headers });

    if (response.status === 401) {
        // Token expired or invalid
        localStorage.removeItem('auth_token');
        window.location.href = '/login';
        return null;
    }

    return response;
}
```

### 6. Backend Router Registration

**Fixed in fastapi_app.py:**

-   ✅ Added `anime_router` import
-   ✅ Registered `app.include_router(anime_router)`

All routers now properly registered:

-   health_router
-   page_router
-   auth_router
-   anime_router ⭐ (newly added)
-   download_router
-   websocket_router

## Implementation Status

### ✅ Completed

1. Created native WebSocket client wrapper
2. Updated HTML templates to use new WebSocket client
3. Registered anime router in FastAPI app
4. Documented API endpoint mappings
5. Documented WebSocket message format changes

### 🔄 In Progress

1. Update app.js WebSocket initialization and room subscriptions
2. Update app.js event handlers for new message types
3. Update queue.js WebSocket initialization and room subscriptions
4. Update queue.js event handlers for new message types

### ⏳ Pending

1. Add authentication token handling to all API requests
2. Test complete workflow (auth → scan → download)
3. Update other JavaScript modules if they use WebSocket/API
4. Integration tests for frontend-backend communication
5. Update infrastructure.md documentation

## Testing Plan

1. **Authentication Flow:**

    - Test setup page → creates master password
    - Test login page → authenticates with master password
    - Test logout → clears session
    - Test protected pages redirect to login

2. **Anime Management:**

    - Test loading anime list
    - Test rescan functionality with progress updates
    - Test search functionality

3. **Download Queue:**

    - Test adding items to queue
    - Test queue operations (start, stop, pause, resume)
    - Test progress updates via WebSocket
    - Test retry and clear operations

4. **WebSocket Communication:**
    - Test connection/reconnection
    - Test room subscriptions
    - Test message routing to correct handlers
    - Test disconnect handling

## Known Issues & Limitations

1. **Legacy Events:** Some Socket.IO events in app.js don't have backend equivalents:

    - `scheduled_rescan_*` events
    - `auto_download_*` events
    - `download_episode_update` event
    - `download_series_completed` event

    **Solution:** Either remove these handlers or implement corresponding backend events

2. **Configuration Endpoints:** Many config-related API calls in app.js don't have backend implementations:

    - Scheduler configuration
    - Logging configuration
    - Advanced configuration
    - Config backups

    **Solution:** Implement these endpoints or remove the UI features

3. **Process Status Monitoring:** `checkProcessLocks()` method may not work with new backend

    **Solution:** Implement equivalent status endpoint or remove feature

## Migration Guide for Developers

### Adding New WebSocket Events

1. Define message type in `src/server/models/websocket.py`:

```python
class WebSocketMessageType(str, Enum):
    MY_NEW_EVENT = "my_new_event"
```

2. Broadcast from service:

```python
await ws_service.broadcast_to_room(
    {"type": "my_new_event", "data": {...}},
    "my_room"
)
```

3. Subscribe and handle in JavaScript:

```javascript
this.socket.join("my_room");
this.socket.on("my_new_event", (data) => {
    // Handle event
});
```

### Adding New API Endpoints

1. Define Pydantic models in `src/server/models/`
2. Create endpoint in appropriate router file in `src/server/api/`
3. Add endpoint to this documentation
4. Update JavaScript to call new endpoint

## References

-   FastAPI Application: `src/server/fastapi_app.py`
-   WebSocket Service: `src/server/services/websocket_service.py`
-   WebSocket Models: `src/server/models/websocket.py`
-   Download Service: `src/server/services/download_service.py`
-   Anime Service: `src/server/services/anime_service.py`
-   Progress Service: `src/server/services/progress_service.py`
-   Infrastructure Doc: `infrastructure.md`