Aniworld/docs/frontend_backend_integration.md

Frontend-Backend Integration Summary

Date: October 24, 2025
Status: Core integration completed

Overview

Successfully integrated the existing frontend JavaScript application with the new FastAPI backend by creating missing API endpoints and updating frontend API calls to match the new endpoint structure.

Completed Work

1. Created Missing API Endpoints

Added the following endpoints to /src/server/api/anime.py:

/api/v1/anime/status (GET)

• Returns anime library status information
• Response includes:
  • directory: Configured anime directory path
  • series_count: Number of series in the library
• Used by frontend configuration modal to display current settings

/api/v1/anime/add (POST)

• Adds a new series to the library from search results
• Request body: {link: string, name: string}
• Validates input and calls SeriesApp.AddSeries() method
• Returns success/error message

/api/v1/anime/download (POST)

• Starts downloading missing episodes from selected folders
• Request body: {folders: string[]}
• Calls SeriesApp.Download() with folder list
• Used when user selects multiple series and clicks download

/api/v1/anime/process/locks (GET)

• Returns current lock status for rescan and download processes
• Response: {success: boolean, locks: {rescan: {is_locked: boolean}, download: {is_locked: boolean}}}
• Used to update UI status indicators and disable buttons during operations

2. Updated Frontend API Calls

Modified /src/server/web/static/js/app.js to use correct endpoint paths:

Old Path	New Path	Purpose
/api/add_series	/api/v1/anime/add	Add new series
/api/download	/api/v1/anime/download	Download selected folders
/api/status	/api/v1/anime/status	Get library status
/api/process/locks/status	/api/v1/anime/process/locks	Check process locks

3. Verified Existing Endpoints

Confirmed the following endpoints are already correctly implemented:

• /api/auth/status - Authentication status check
• /api/auth/logout - User logout
• /api/v1/anime - List anime with missing episodes
• /api/v1/anime/search - Search for anime
• /api/v1/anime/rescan - Trigger library rescan
• /api/v1/anime/{anime_id} - Get anime details
• /api/queue/* - Download queue management
• /api/config/* - Configuration management

Request/Response Models

AddSeriesRequest

class AddSeriesRequest(BaseModel):
    link: str  # Series URL/link
    name: str  # Series name

DownloadFoldersRequest

class DownloadFoldersRequest(BaseModel):
    folders: List[str]  # List of folder names to download

Testing

• All existing tests passing
• Integration tested with frontend JavaScript
• Endpoints follow existing patterns and conventions
• Proper error handling and validation in place

Remaining Work

The following endpoints are referenced in the frontend but not yet implemented:

Scheduler API (/api/scheduler/)

• /api/scheduler/config (GET/POST) - Get/update scheduler configuration
• /api/scheduler/trigger-rescan (POST) - Manually trigger scheduled rescan

Logging API (/api/logging/)

• /api/logging/config (GET/POST) - Get/update logging configuration
• /api/logging/files (GET) - List log files
• /api/logging/files/{filename}/download (GET) - Download log file
• /api/logging/files/{filename}/tail (GET) - Tail log file
• /api/logging/test (POST) - Test logging configuration
• /api/logging/cleanup (POST) - Clean up old log files

Diagnostics API (/api/diagnostics/)

• /api/diagnostics/network (GET) - Network diagnostics

Config API Extensions

The following config endpoints may need verification or implementation:

• /api/config/section/advanced (GET/POST) - Advanced configuration section
• /api/config/directory (POST) - Update anime directory
• /api/config/backup (POST) - Create configuration backup
• /api/config/backups (GET) - List configuration backups
• /api/config/backup/{name}/restore (POST) - Restore backup
• /api/config/backup/{name}/download (GET) - Download backup
• /api/config/export (POST) - Export configuration
• /api/config/validate (POST) - Validate configuration
• /api/config/reset (POST) - Reset configuration to defaults

Architecture Notes

Endpoint Organization

• Anime-related endpoints: /api/v1/anime/
• Queue management: /api/queue/
• Configuration: /api/config/
• Authentication: /api/auth/
• Health checks: /health

Design Patterns Used

• Dependency injection for SeriesApp instance
• Request validation with Pydantic models
• Consistent error handling and HTTP status codes
• Authentication requirements on all endpoints
• Proper async/await patterns

Frontend Integration

• Frontend uses makeAuthenticatedRequest() helper for API calls
• Bearer token authentication in Authorization header
• Consistent response format expected: {status: string, message: string, ...}
• WebSocket integration preserved for real-time updates

Security Considerations

• All endpoints require authentication via require_auth dependency
• Input validation on request models (link length, folder list)
• Proper error messages without exposing internal details
• No injection vulnerabilities in search/add operations

Future Improvements

1. Implement missing APIs: Scheduler, Logging, Diagnostics
2. Enhanced validation: Add more comprehensive input validation
3. Rate limiting: Add per-endpoint rate limiting if needed
4. Caching: Consider caching for status endpoints
5. Pagination: Add pagination to anime list endpoint
6. Filtering: Add filtering options to anime list
7. Batch operations: Support batch add/download operations
8. Progress tracking: Enhance real-time progress updates

Files Modified

• src/server/api/anime.py - Added 4 new endpoints
• src/server/web/static/js/app.js - Updated 4 API call paths
• instructions.md - Marked frontend integration tasks as completed

Conclusion

The core frontend-backend integration is now complete. The main user workflows (listing anime, searching, adding series, downloading) are fully functional. The remaining work involves implementing administrative and configuration features (scheduler, logging, diagnostics) that enhance the application but are not critical for basic operation.

All tests are passing, and the integration follows established patterns and best practices for the project.