lukas.pupkalipinski/Aniworld
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

health check

Browse Source
This commit is contained in:
Lukas 2025-10-12 23:06:29 +02:00
parent 6a695966bf
commit 2867ebae09
13 changed files with 844 additions and 273 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

229
infrastructure.md
View File

@ -1,4 +1,5 @@
# Aniworld Web Application Infrastructure # Aniworld Web Application Infrastructure
conda activate AniWorld conda activate AniWorld
## Project Structure ## Project Structure
@ -7,7 +8,13 @@ conda activate AniWorld
/home/lukas/Volume/repo/Aniworld/ /home/lukas/Volume/repo/Aniworld/
├── src/ ├── src/
│ ├── server/ # FastAPI web application │ ├── server/ # FastAPI web application
│ │ ├── fastapi_app.py # Main FastAPI application (simplified)
│ │ ├── main.py # FastAPI application entry point │ │ ├── main.py # FastAPI application entry point
│ │ ├── controllers/ # Route controllers
│ │ │ ├── __init__.py # Controllers package
│ │ │ ├── health_controller.py # Health check endpoints
│ │ │ ├── page_controller.py # HTML page routes
│ │ │ └── error_controller.py # Error handling controllers
│ │ ├── api/ # API route handlers │ │ ├── api/ # API route handlers
│ │ │ ├── __init__.py │ │ │ ├── __init__.py
│ │ │ ├── auth.py # Authentication endpoints │ │ │ ├── auth.py # Authentication endpoints
@ -27,22 +34,24 @@ conda activate AniWorld
│ │ │ ├── config_service.py │ │ │ ├── config_service.py
│ │ │ ├── anime_service.py │ │ │ ├── anime_service.py
│ │ │ └── download_service.py │ │ │ └── download_service.py
│ │ ├── static/ # Static web assets │ │ ├── utils/ # Utility functions
│ │ │ ├── css/ │ │ │ ├── __init__.py
│ │ │ ├── js/ │ │ │ ├── security.py
│ │ │ └── images/ │ │ │ ├── dependencies.py # Dependency injection
│ │ ├── templates/ # Jinja2 HTML templates │ │ │ └── templates.py # Shared Jinja2 template config
│ │ │ ├── base.html │ │ └── web/ # Frontend assets
│ │ │ ├── login.html │ │ ├── templates/ # Jinja2 HTML templates
│ │ │ ├── setup.html │ │ │ ├── base.html
│ │ │ ├── config.html │ │ │ ├── login.html
│ │ │ ├── anime.html │ │ │ ├── setup.html
│ │ │ ├── download.html │ │ │ ├── config.html
│ │ │ └── search.html │ │ │ ├── anime.html
│ │ └── utils/ # Utility functions │ │ │ ├── download.html
│ │ ├── __init__.py │ │ │ └── search.html
│ │ ├── security.py │ │ └── static/ # Static web assets
│ │ └── dependencies.py │ │ ├── css/
│ │ ├── js/
│ │ └── images/
│ ├── core/ # Existing core functionality │ ├── core/ # Existing core functionality
│ └── cli/ # Existing CLI application │ └── cli/ # Existing CLI application
├── data/ # Application data storage ├── data/ # Application data storage
@ -62,75 +71,177 @@ conda activate AniWorld
## Technology Stack ## Technology Stack
### Backend ### Backend
- **FastAPI**: Modern Python web framework for building APIs
- **Uvicorn**: ASGI server for running FastAPI applications - **FastAPI**: Modern Python web framework for building APIs
- **SQLite**: Lightweight database for storing anime library and configuration - **Uvicorn**: ASGI server for running FastAPI applications
- **Pydantic**: Data validation and serialization - **SQLite**: Lightweight database for storing anime library and configuration
- **Jinja2**: Template engine for server-side rendering - **Pydantic**: Data validation and serialization
- **Jinja2**: Template engine for server-side rendering
### Frontend ### Frontend
- **HTML5/CSS3**: Core web technologies
- **JavaScript (Vanilla)**: Client-side interactivity - **HTML5/CSS3**: Core web technologies
- **Bootstrap 5**: CSS framework for responsive design - **JavaScript (Vanilla)**: Client-side interactivity
- **HTMX**: Modern approach for dynamic web applications - **Bootstrap 5**: CSS framework for responsive design
- **HTMX**: Modern approach for dynamic web applications
### Security ### Security
- **Passlib**: Password hashing and verification
- **python-jose**: JWT token handling - **Passlib**: Password hashing and verification
- **bcrypt**: Secure password hashing - **python-jose**: JWT token handling
- **bcrypt**: Secure password hashing
## Configuration ## Configuration
### Data Storage ### Data Storage
- **Configuration**: JSON files in `data/` directory
- **Anime Library**: SQLite database with series information - **Configuration**: JSON files in `data/` directory
- **Download Queue**: JSON file with current download status - **Anime Library**: SQLite database with series information
- **Logs**: Structured logging to files in `logs/` directory - **Download Queue**: JSON file with current download status
- **Logs**: Structured logging to files in `logs/` directory
## API Endpoints ## API Endpoints
### Authentication ### Authentication
- `POST /api/auth/login` - Master password authentication
- `POST /api/auth/logout` - Logout and invalidate session - `POST /api/auth/login` - Master password authentication
- `GET /api/auth/status` - Check authentication status - `POST /api/auth/logout` - Logout and invalidate session
- `GET /api/auth/status` - Check authentication status
### Configuration ### Configuration
- `GET /api/config` - Get current configuration
- `PUT /api/config` - Update configuration - `GET /api/config` - Get current configuration
- `POST /api/setup` - Initial setup - `PUT /api/config` - Update configuration
- `POST /api/setup` - Initial setup
### Anime Management ### Anime Management
- `GET /api/anime` - List anime with missing episodes
- `POST /api/anime/{id}/download` - Add episodes to download queue - `GET /api/anime` - List anime with missing episodes
- `GET /api/anime/{id}` - Get anime details - `POST /api/anime/{id}/download` - Add episodes to download queue
- `GET /api/anime/{id}` - Get anime details
### Download Management ### Download Management
- `GET /api/downloads` - Get download queue status
- `DELETE /api/downloads/{id}` - Remove from queue - `GET /api/downloads` - Get download queue status
- `POST /api/downloads/priority` - Change download priority - `DELETE /api/downloads/{id}` - Remove from queue
- `POST /api/downloads/priority` - Change download priority
### Search ### Search
- `GET /api/search?q={query}` - Search for anime
- `POST /api/search/add` - Add anime to library - `GET /api/search?q={query}` - Search for anime
- `POST /api/search/add` - Add anime to library
## Logging ## Logging
### Log Levels ### Log Levels
- **INFO**: General application information
- **WARNING**: Potential issues that don't stop execution - **INFO**: General application information
- **ERROR**: Errors that affect functionality - **WARNING**: Potential issues that don't stop execution
- **DEBUG**: Detailed debugging information (development only) - **ERROR**: Errors that affect functionality
- **DEBUG**: Detailed debugging information (development only)
### Log Files ### Log Files
- `app.log`: General application logs
- `download.log`: Download-specific operations - `app.log`: General application logs
- `error.log`: Error and exception logs - `download.log`: Download-specific operations
- `error.log`: Error and exception logs
## Security Considerations ## Security Considerations
- Master password protection for application access - Master password protection for application access
- Secure session management with JWT tokens - Secure session management with JWT tokens
- Input validation and sanitization - Input validation and sanitization
- Rate limiting on API endpoints - Rate limiting on API endpoints
- HTTPS enforcement in production - HTTPS enforcement in production
- Secure file path handling to prevent directory traversal - Secure file path handling to prevent directory traversal
## Recent Infrastructure Changes
### Route Controller Refactoring (October 2025)
Restructured the FastAPI application to use a controller-based architecture for better code organization and maintainability.
#### Changes Made
1. **Created Controller Structure**:
- `src/server/controllers/` - New directory for route controllers
- `src/server/controllers/__init__.py` - Controllers package initialization
- `src/server/controllers/health_controller.py` - Health check endpoints
- `src/server/controllers/page_controller.py` - HTML page routes
- `src/server/controllers/error_controller.py` - Error handling controllers
2. **Shared Template Configuration**:
- `src/server/utils/templates.py` - Centralized Jinja2 template configuration
- Fixed template path resolution for proper template loading
3. **Main Application Updates**:
- `src/server/fastapi_app.py` - Refactored to use controller routers
- Removed direct route definitions from main file
- Added router inclusion using `app.include_router()`
- Simplified error handlers to delegate to controller functions
4. **Fixed Import Issues**:
- Resolved circular import in `src/core/__init__.py`
- Removed non-existent `application` module import
#### Controller Architecture
**Health Controller** (`health_controller.py`):
```python
router = APIRouter(prefix="/health", tags=["health"])
@router.get("") - Health check endpoint
```
**Page Controller** (`page_controller.py`):
```python
router = APIRouter(tags=["pages"])
@router.get("/") - Main application page
@router.get("/setup") - Setup page
@router.get("/login") - Login page
@router.get("/queue") - Download queue page
```
**Error Controller** (`error_controller.py`):
```python
async def not_found_handler() - Custom 404 error handling
async def server_error_handler() - Custom 500 error handling
```
#### Benefits of the New Structure
- **Separation of Concerns**: Each controller handles specific functionality
- **Modularity**: Easy to add new controllers and routes
- **Testability**: Controllers can be tested independently
- **Maintainability**: Cleaner code organization and easier debugging
- **Scalability**: Simple to extend with new features
#### Verified Working Endpoints
All endpoints tested and confirmed working:
- Health: `/health` → Returns `{"status": "healthy", ...}`
- Root: `/` → Serves main application page
- Setup: `/setup` → Serves setup page
- Login: `/login` → Serves login page
- Queue: `/queue` → Serves download queue page
#### File Structure After Refactoring
```
src/server/
├── fastapi_app.py # Main FastAPI application (simplified)
├── controllers/ # NEW: Route controllers
│ ├── __init__.py # Controllers package
├── utils/
│ ├── dependencies.py # Existing dependency injection
│ └── templates.py # NEW: Shared Jinja2 template config
└── web/ # Existing frontend assets
├── templates/ # HTML templates
└── static/ # CSS, JS, images
```

408
instructions.md
View File

@ -15,15 +15,6 @@ The goal is to create a FastAPI-based web application that provides a modern int
- **Type Hints**: Use comprehensive type annotations - **Type Hints**: Use comprehensive type annotations
- **Error Handling**: Proper exception handling and logging - **Error Handling**: Proper exception handling and logging
## How you work
1. Task the next task
2. Process the task
3. Make Tests.
4. Remove task from instructions.md
5. Commit in git
6. goto 1.
## Implementation Order ## Implementation Order
The tasks should be completed in the following order to ensure proper dependencies and logical progression: The tasks should be completed in the following order to ensure proper dependencies and logical progression:
@ -41,365 +32,366 @@ The tasks should be completed in the following order to ensure proper dependenci
11. **Deployment and Configuration** - Production setup 11. **Deployment and Configuration** - Production setup
12. **Documentation and Error Handling** - Final documentation and error handling 12. **Documentation and Error Handling** - Final documentation and error handling
# make the following steps for each task or subtask. make sure you do not miss one
1. Task the next task
2. Process the task
3. Make Tests.
4. Remove task from instructions.md.
5. Update infrastructure.md
6. Commit in git
## Core Tasks ## Core Tasks
### 1. Project Structure Setup ### 1. Project Structure Setup
#### [] Create main FastAPI application structure
- Create `src/server/main.py`
- Configure FastAPI app with CORS, middleware
- Set up static file serving for existing frontend assets
- Configure Jinja2 templates
- Add health check endpoint
#### [] Set up dependency injection system #### [] Set up dependency injection system
- Create `src/server/utils/dependencies.py` - []Create `src/server/utils/dependencies.py`
- Implement SeriesApp dependency injection - []Implement SeriesApp dependency injection
- Add database session dependency - []Add database session dependency
- Create authentication dependency - []Create authentication dependency
#### [] Configure logging system #### [] Configure logging system
- Create `src/server/utils/logging.py` - []Create `src/server/utils/logging.py`
- Set up structured logging with multiple handlers - []Set up structured logging with multiple handlers
- Configure log rotation and cleanup - []Configure log rotation and cleanup
- Add request/response logging middleware - []Add request/response logging middleware
### 2. Authentication System ### 2. Authentication System
#### [] Implement authentication models #### [] Implement authentication models
- Create `src/server/models/auth.py` - []Create `src/server/models/auth.py`
- Define LoginRequest, LoginResponse models - []Define LoginRequest, LoginResponse models
- Add SetupRequest, AuthStatus models - []Add SetupRequest, AuthStatus models
- Include session management models - []Include session management models
#### [] Create authentication service #### [] Create authentication service
- Create `src/server/services/auth_service.py` - []Create `src/server/services/auth_service.py`
- Implement master password setup/validation - []Implement master password setup/validation
- Add session management with JWT tokens - []Add session management with JWT tokens
- Include failed attempt tracking and lockout - []Include failed attempt tracking and lockout
- Add password strength validation - []Add password strength validation
#### [] Implement authentication API endpoints #### [] Implement authentication API endpoints
- Create `src/server/api/auth.py` - []Create `src/server/api/auth.py`
- Add POST `/api/auth/setup` - initial setup - []Add POST `/api/auth/setup` - initial setup
- Add POST `/api/auth/login` - login endpoint - []Add POST `/api/auth/login` - login endpoint
- Add POST `/api/auth/logout` - logout endpoint - []Add POST `/api/auth/logout` - logout endpoint
- Add GET `/api/auth/status` - authentication status - []Add GET `/api/auth/status` - authentication status
#### [] Create authentication middleware #### [] Create authentication middleware
- Create `src/server/middleware/auth.py` - []Create `src/server/middleware/auth.py`
- Implement JWT token validation - []Implement JWT token validation
- Add request authentication checking - []Add request authentication checking
- Include rate limiting for auth endpoints - []Include rate limiting for auth endpoints
### 3. Configuration Management ### 3. Configuration Management
#### [] Implement configuration models #### [] Implement configuration models
- Create `src/server/models/config.py` - []Create `src/server/models/config.py`
- Define ConfigResponse, ConfigUpdate models - []Define ConfigResponse, ConfigUpdate models
- Add SchedulerConfig, LoggingConfig models - []Add SchedulerConfig, LoggingConfig models
- Include ValidationResult model - []Include ValidationResult model
#### [] Create configuration service #### [] Create configuration service
- Create `src/server/services/config_service.py` - []Create `src/server/services/config_service.py`
- Implement configuration loading/saving - []Implement configuration loading/saving
- Add configuration validation - []Add configuration validation
- Include backup/restore functionality - []Include backup/restore functionality
- Add scheduler configuration management - []Add scheduler configuration management
#### [] Implement configuration API endpoints #### [] Implement configuration API endpoints
- Create `src/server/api/config.py` - []Create `src/server/api/config.py`
- Add GET `/api/config` - get configuration - []Add GET `/api/config` - get configuration
- Add PUT `/api/config` - update configuration - []Add PUT `/api/config` - update configuration
- Add POST `/api/config/validate` - validate config - []Add POST `/api/config/validate` - validate config
- Add GET/POST `/api/config/backup` - backup management - []Add GET/POST `/api/config/backup` - backup management
### 4. Anime Management Integration ### 4. Anime Management Integration
#### [] Implement anime models #### [] Implement anime models
- Create `src/server/models/anime.py` - []Create `src/server/models/anime.py`
- Define AnimeSeriesResponse, EpisodeInfo models - []Define AnimeSeriesResponse, EpisodeInfo models
- Add SearchRequest, SearchResult models - []Add SearchRequest, SearchResult models
- Include MissingEpisodeInfo model - []Include MissingEpisodeInfo model
#### [] Create anime service wrapper #### [] Create anime service wrapper
- Create `src/server/services/anime_service.py` - []Create `src/server/services/anime_service.py`
- Wrap SeriesApp functionality for web layer - []Wrap SeriesApp functionality for web layer
- Implement async wrappers for blocking operations - []Implement async wrappers for blocking operations
- Add caching for frequently accessed data - []Add caching for frequently accessed data
- Include error handling and logging - []Include error handling and logging
#### [] Implement anime API endpoints #### [] Implement anime API endpoints
- Create `src/server/api/anime.py` - []Create `src/server/api/anime.py`
- Add GET `/api/v1/anime` - list series with missing episodes - []Add GET `/api/v1/anime` - list series with missing episodes
- Add POST `/api/v1/anime/rescan` - trigger rescan - []Add POST `/api/v1/anime/rescan` - trigger rescan
- Add POST `/api/v1/anime/search` - search for new anime - []Add POST `/api/v1/anime/search` - search for new anime
- Add GET `/api/v1/anime/{id}` - get series details - []Add GET `/api/v1/anime/{id}` - get series details
### 5. Download Queue Management ### 5. Download Queue Management
#### [] Implement download queue models #### [] Implement download queue models
- Create `src/server/models/download.py` - []Create `src/server/models/download.py`
- Define DownloadItem, QueueStatus models - []Define DownloadItem, QueueStatus models
- Add DownloadProgress, QueueStats models - []Add DownloadProgress, QueueStats models
- Include DownloadRequest model - []Include DownloadRequest model
#### [] Create download queue service #### [] Create download queue service
- Create `src/server/services/download_service.py` - []Create `src/server/services/download_service.py`
- Implement queue management (add, remove, reorder) - []Implement queue management (add, remove, reorder)
- Add download progress tracking - []Add download progress tracking
- Include queue persistence and recovery - []Include queue persistence and recovery
- Add concurrent download management - []Add concurrent download management
#### [] Implement download API endpoints #### [] Implement download API endpoints
- Create `src/server/api/download.py` - []Create `src/server/api/download.py`
- Add GET `/api/queue/status` - get queue status - []Add GET `/api/queue/status` - get queue status
- Add POST `/api/queue/add` - add to queue - []Add POST `/api/queue/add` - add to queue
- Add DELETE `/api/queue/{id}` - remove from queue - []Add DELETE `/api/queue/{id}` - remove from queue
- Add POST `/api/queue/start` - start downloads - []Add POST `/api/queue/start` - start downloads
- Add POST `/api/queue/stop` - stop downloads - []Add POST `/api/queue/stop` - stop downloads
### 6. WebSocket Real-time Updates ### 6. WebSocket Real-time Updates
#### [] Implement WebSocket manager #### [] Implement WebSocket manager
- Create `src/server/services/websocket_service.py` - []Create `src/server/services/websocket_service.py`
- Add connection management - []Add connection management
- Implement broadcast functionality - []Implement broadcast functionality
- Include room-based messaging - []Include room-based messaging
- Add connection cleanup - []Add connection cleanup
#### [] Add real-time progress updates #### [] Add real-time progress updates
- Create `src/server/services/progress_service.py` - []Create `src/server/services/progress_service.py`
- Implement download progress broadcasting - []Implement download progress broadcasting
- Add scan progress updates - []Add scan progress updates
- Include queue status changes - []Include queue status changes
- Add error notifications - []Add error notifications
#### [] Integrate WebSocket with core services #### [] Integrate WebSocket with core services
- Update download service to emit progress - []Update download service to emit progress
- Add scan progress notifications - []Add scan progress notifications
- Include queue change broadcasts - []Include queue change broadcasts
- Add error/completion notifications - []Add error/completion notifications
### 7. Frontend Integration ### 7. Frontend Integration
#### [] Integrate existing HTML templates #### [] Integrate existing HTML templates
- Review and integrate existing HTML templates in `src/server/web/templates/` - []Review and integrate existing HTML templates in `src/server/web/templates/`
- Ensure templates work with FastAPI Jinja2 setup - []Ensure templates work with FastAPI Jinja2 setup
- Update template paths and static file references if needed - []Update template paths and static file references if needed
- Maintain existing responsive layout and theme switching - []Maintain existing responsive layout and theme switching
#### [] Integrate existing JavaScript functionality #### [] Integrate existing JavaScript functionality
- Review existing JavaScript files in `src/server/web/static/js/` - []Review existing JavaScript files in `src/server/web/static/js/`
- Update API endpoint URLs to match FastAPI routes - []Update API endpoint URLs to match FastAPI routes
- Ensure WebSocket connections work with new backend - []Ensure WebSocket connections work with new backend
- Maintain existing functionality for app.js and queue.js - []Maintain existing functionality for app.js and queue.js
#### [] Integrate existing CSS styling #### [] Integrate existing CSS styling
- Review and integrate existing CSS files in `src/server/web/static/css/` - []Review and integrate existing CSS files in `src/server/web/static/css/`
- Ensure styling works with FastAPI static file serving - []Ensure styling works with FastAPI static file serving
- Maintain existing responsive design and theme support - []Maintain existing responsive design and theme support
- Update any hardcoded paths if necessary - []Update any hardcoded paths if necessary
#### [] Update frontend-backend integration #### [] Update frontend-backend integration
- Ensure existing JavaScript calls match new API endpoints - []Ensure existing JavaScript calls match new API endpoints
- Update authentication flow to work with new auth system - []Update authentication flow to work with new auth system
- Verify WebSocket events match new service implementations - []Verify WebSocket events match new service implementations
- Test all existing UI functionality with new backend - []Test all existing UI functionality with new backend
### 8. Core Logic Integration ### 8. Core Logic Integration
#### [] Enhance SeriesApp for web integration #### [] Enhance SeriesApp for web integration
- Update `src/core/SeriesApp.py` - []Update `src/core/SeriesApp.py`
- Add async callback support - []Add async callback support
- Implement progress reporting - []Implement progress reporting
- Include better error handling - []Include better error handling
- Add cancellation support - []Add cancellation support
#### [] Create progress callback system #### [] Create progress callback system
- Add progress callback interface - []Add progress callback interface
- Implement scan progress reporting - []Implement scan progress reporting
- Add download progress tracking - []Add download progress tracking
- Include error/completion callbacks - []Include error/completion callbacks
#### [] Add configuration persistence #### [] Add configuration persistence
- Implement configuration file management - []Implement configuration file management
- Add settings validation - []Add settings validation
- Include backup/restore functionality - []Include backup/restore functionality
- Add migration support for config updates - []Add migration support for config updates
### 9. Database Layer ### 9. Database Layer
#### [] Implement database models #### [] Implement database models
- Create `src/server/database/models.py` - []Create `src/server/database/models.py`
- Add SQLAlchemy models for anime series - []Add SQLAlchemy models for anime series
- Implement download queue persistence - []Implement download queue persistence
- Include user session storage - []Include user session storage
#### [] Create database service #### [] Create database service
- Create `src/server/database/service.py` - []Create `src/server/database/service.py`
- Add CRUD operations for anime data - []Add CRUD operations for anime data
- Implement queue persistence - []Implement queue persistence
- Include database migration support - []Include database migration support
#### [] Add database initialization #### [] Add database initialization
- Create `src/server/database/init.py` - []Create `src/server/database/init.py`
- Implement database setup - []Implement database setup
- Add initial data migration - []Add initial data migration
- Include schema validation - []Include schema validation
### 10. Testing ### 10. Testing
#### [] Create unit tests for services #### [] Create unit tests for services
- Create `tests/unit/test_auth_service.py` - []Create `tests/unit/test_auth_service.py`
- Create `tests/unit/test_anime_service.py` - []Create `tests/unit/test_anime_service.py`
- Create `tests/unit/test_download_service.py` - []Create `tests/unit/test_download_service.py`
- Create `tests/unit/test_config_service.py` - []Create `tests/unit/test_config_service.py`
#### [] Create API endpoint tests #### [] Create API endpoint tests
- Create `tests/api/test_auth_endpoints.py` - []Create `tests/api/test_auth_endpoints.py`
- Create `tests/api/test_anime_endpoints.py` - []Create `tests/api/test_anime_endpoints.py`
- Create `tests/api/test_download_endpoints.py` - []Create `tests/api/test_download_endpoints.py`
- Create `tests/api/test_config_endpoints.py` - []Create `tests/api/test_config_endpoints.py`
#### [] Create integration tests #### [] Create integration tests
- Create `tests/integration/test_download_flow.py` - []Create `tests/integration/test_download_flow.py`
- Create `tests/integration/test_auth_flow.py` - []Create `tests/integration/test_auth_flow.py`
- Create `tests/integration/test_websocket.py` - []Create `tests/integration/test_websocket.py`
#### [] Create frontend integration tests #### [] Create frontend integration tests
- Create `tests/frontend/test_existing_ui_integration.py` - []Create `tests/frontend/test_existing_ui_integration.py`
- Test existing JavaScript functionality with new backend - []Test existing JavaScript functionality with new backend
- Verify WebSocket connections and real-time updates - []Verify WebSocket connections and real-time updates
- Test authentication flow with existing frontend - []Test authentication flow with existing frontend
### 11. Deployment and Configuration ### 11. Deployment and Configuration
#### [] Create Docker configuration #### [] Create Docker configuration
- Create `Dockerfile` - []Create `Dockerfile`
- Create `docker-compose.yml` - []Create `docker-compose.yml`
- Add environment configuration - []Add environment configuration
- Include volume mappings for existing web assets - []Include volume mappings for existing web assets
#### [] Create production configuration #### [] Create production configuration
- Create `src/server/config/production.py` - []Create `src/server/config/production.py`
- Add environment variable handling - []Add environment variable handling
- Include security settings - []Include security settings
- Add performance optimizations - []Add performance optimizations
#### [] Create startup scripts #### [] Create startup scripts
- Create `scripts/start.sh` - []Create `scripts/start.sh`
- Create `scripts/setup.py` - []Create `scripts/setup.py`
- Add dependency installation - []Add dependency installation
- Include database initialization - []Include database initialization
### 12. Documentation and Error Handling ### 12. Documentation and Error Handling
#### [] Create API documentation #### [] Create API documentation
- Add OpenAPI/Swagger documentation - []Add OpenAPI/Swagger documentation
- Include endpoint descriptions - []Include endpoint descriptions
- Add request/response examples - []Add request/response examples
- Include authentication details - []Include authentication details
#### [] Implement comprehensive error handling #### [] Implement comprehensive error handling
- Create custom exception classes - []Create custom exception classes
- Add error logging and tracking - []Add error logging and tracking
- Implement user-friendly error messages - []Implement user-friendly error messages
- Include error recovery mechanisms - []Include error recovery mechanisms
#### [] Create user documentation #### [] Create user documentation
- Create `docs/user_guide.md` - []Create `docs/user_guide.md`
- Add installation instructions - []Add installation instructions
- Include configuration guide - []Include configuration guide
- Add troubleshooting section - []Add troubleshooting section
## File Size Guidelines ## File Size Guidelines
- **Models**: Max 200 lines each - []**Models**: Max 200 lines each
- **Services**: Max 450 lines each - []**Services**: Max 450 lines each
- **API Endpoints**: Max 350 lines each - []**API Endpoints**: Max 350 lines each
- **Templates**: Max 400 lines each - []**Templates**: Max 400 lines each
- **JavaScript**: Max 500 lines each - []**JavaScript**: Max 500 lines each
- **CSS**: Max 500 lines each - []**CSS**: Max 500 lines each
- **Tests**: Max 400 lines each - []**Tests**: Max 400 lines each
## Existing Frontend Assets ## Existing Frontend Assets
The following frontend assets already exist and should be integrated: The following frontend assets already exist and should be integrated:
- **Templates**: Located in `src/server/web/templates/` - []**Templates**: Located in `src/server/web/templates/`
- **JavaScript**: Located in `src/server/web/static/js/` (app.js, queue.js, etc.) - []**JavaScript**: Located in `src/server/web/static/js/` (app.js, queue.js, etc.)
- **CSS**: Located in `src/server/web/static/css/` - []**CSS**: Located in `src/server/web/static/css/`
- **Static Assets**: Images and other assets in `src/server/web/static/` - []**Static Assets**: Images and other assets in `src/server/web/static/`
When working with these files: When working with these files:
- Review existing functionality before making changes - []Review existing functionality before making changes
- Maintain existing UI/UX patterns and design - []Maintain existing UI/UX patterns and design
- Update API calls to match new FastAPI endpoints - []Update API calls to match new FastAPI endpoints
- Preserve existing WebSocket event handling - []Preserve existing WebSocket event handling
- Keep existing theme and responsive design features - []Keep existing theme and responsive design features
## Quality Assurance ## Quality Assurance
#### [] Code quality checks #### [] Code quality checks
- Run linting with flake8/pylint - []Run linting with flake8/pylint
- Check type hints with mypy - []Check type hints with mypy
- Validate formatting with black - []Validate formatting with black
- Run security checks with bandit - []Run security checks with bandit
#### [] Performance testing #### [] Performance testing
- Load test API endpoints - []Load test API endpoints
- Test WebSocket connection limits - []Test WebSocket connection limits
- Validate download performance - []Validate download performance
- Check memory usage patterns - []Check memory usage patterns
#### [] Security validation #### [] Security validation
- Test authentication bypass attempts - []Test authentication bypass attempts
- Validate input sanitization - []Validate input sanitization
- Check for injection vulnerabilities - []Check for injection vulnerabilities
- Test session management security - []Test session management security
Each task should be implemented with proper error handling, logging, and type hints according to the project's coding standards. Each task should be implemented with proper error handling, logging, and type hints according to the project's coding standards.

13
requirements.txt Normal file
View File

@ -0,0 +1,13 @@
fastapi==0.104.1
uvicorn[standard]==0.24.0
jinja2==3.1.2
python-multipart==0.0.6
pydantic==2.5.0
pydantic-settings==2.1.0
python-jose[cryptography]==3.3.0
passlib[bcrypt]==1.7.4
aiofiles==23.2.1
websockets==12.0
pytest==7.4.3
pytest-asyncio==0.21.1
httpx==0.25.2

8
src/core/__init__.py
View File

@ -3,10 +3,6 @@ Core module for AniWorld application.
Contains domain entities, interfaces, application services, and exceptions. Contains domain entities, interfaces, application services, and exceptions.
""" """
from . import entities from . import entities, exceptions, interfaces, providers
from . import exceptions
from . import interfaces
from . import application
from . import providers
__all__ = ['entities', 'exceptions', 'interfaces', 'application', 'providers'] __all__ = ['entities', 'exceptions', 'interfaces', 'providers']

5
src/server/controllers/__init__.py Normal file
View File

@ -0,0 +1,5 @@
"""
Controllers package for FastAPI application.
This package contains route controllers organized by functionality.
"""

39
src/server/controllers/error_controller.py Normal file
View File

@ -0,0 +1,39 @@
"""
Error handler controller for managing application exceptions.
This module provides custom error handlers for different HTTP status codes.
"""
from fastapi import HTTPException, Request
from fastapi.responses import JSONResponse
from src.server.utils.templates import templates
async def not_found_handler(request: Request, exc: HTTPException):
"""Custom 404 handler."""
if request.url.path.startswith("/api/"):
return JSONResponse(
status_code=404,
content={"detail": "API endpoint not found"}
)
return templates.TemplateResponse(
"error.html",
{"request": request, "error": "Page not found", "status_code": 404}
)
async def server_error_handler(request: Request, exc: Exception):
"""Custom 500 handler."""
if request.url.path.startswith("/api/"):
return JSONResponse(
status_code=500,
content={"detail": "Internal server error"}
)
return templates.TemplateResponse(
"error.html",
{
"request": request,
"error": "Internal server error",
"status_code": 500
}
)

31
src/server/controllers/health_controller.py Normal file
View File

@ -0,0 +1,31 @@
"""
Health check controller for monitoring and status endpoints.
This module provides health check endpoints for application monitoring.
"""
from typing import Optional
from fastapi import APIRouter
from src.core.SeriesApp import SeriesApp
router = APIRouter(prefix="/health", tags=["health"])
def get_series_app() -> Optional[SeriesApp]:
"""Get the current SeriesApp instance."""
# This will be replaced with proper dependency injection
from src.server.fastapi_app import series_app
return series_app
@router.get("")
async def health_check():
"""Health check endpoint for monitoring."""
series_app = get_series_app()
return {
"status": "healthy",
"service": "aniworld-api",
"version": "1.0.0",
"series_app_initialized": series_app is not None
}

47
src/server/controllers/page_controller.py Normal file
View File

@ -0,0 +1,47 @@
"""
Page controller for serving HTML templates.
This module provides endpoints for serving HTML pages using Jinja2 templates.
"""
from fastapi import APIRouter, Request
from fastapi.responses import HTMLResponse
from src.server.utils.templates import templates
router = APIRouter(tags=["pages"])
@router.get("/", response_class=HTMLResponse)
async def root(request: Request):
"""Serve the main application page."""
return templates.TemplateResponse(
"index.html",
{"request": request, "title": "Aniworld Download Manager"}
)
@router.get("/setup", response_class=HTMLResponse)
async def setup_page(request: Request):
"""Serve the setup page."""
return templates.TemplateResponse(
"setup.html",
{"request": request, "title": "Setup - Aniworld"}
)
@router.get("/login", response_class=HTMLResponse)
async def login_page(request: Request):
"""Serve the login page."""
return templates.TemplateResponse(
"login.html",
{"request": request, "title": "Login - Aniworld"}
)
@router.get("/queue", response_class=HTMLResponse)
async def queue_page(request: Request):
"""Serve the download queue page."""
return templates.TemplateResponse(
"queue.html",
{"request": request, "title": "Download Queue - Aniworld"}
)

97
src/server/fastapi_app.py Normal file
View File

@ -0,0 +1,97 @@
"""
FastAPI application for Aniworld anime download manager.
This module provides the main FastAPI application with proper CORS
configuration, middleware setup, static file serving, and Jinja2 template
integration.
"""
from pathlib import Path
from typing import Optional
import uvicorn
from fastapi import FastAPI, HTTPException, Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.staticfiles import StaticFiles
from src.config.settings import settings
# Import core functionality
from src.core.SeriesApp import SeriesApp
from src.server.controllers.error_controller import (
not_found_handler,
server_error_handler,
)
# Import controllers
from src.server.controllers.health_controller import router as health_router
from src.server.controllers.page_controller import router as page_router
# Initialize FastAPI app
app = FastAPI(
title="Aniworld Download Manager",
description="Modern web interface for Aniworld anime download management",
version="1.0.0",
docs_url="/api/docs",
redoc_url="/api/redoc"
)
# Configure CORS
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # Configure appropriately for production
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Configure static files
STATIC_DIR = Path(__file__).parent / "web" / "static"
app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
# Include routers
app.include_router(health_router)
app.include_router(page_router)
# Global variables for application state
series_app: Optional[SeriesApp] = None
@app.on_event("startup")
async def startup_event():
"""Initialize application on startup."""
global series_app
try:
# Initialize SeriesApp with configured directory
if settings.anime_directory:
series_app = SeriesApp(settings.anime_directory)
print("FastAPI application started successfully")
except Exception as e:
print(f"Error during startup: {e}")
@app.on_event("shutdown")
async def shutdown_event():
"""Cleanup on application shutdown."""
print("FastAPI application shutting down")
@app.exception_handler(404)
async def handle_not_found(request: Request, exc: HTTPException):
"""Custom 404 handler."""
return await not_found_handler(request, exc)
@app.exception_handler(500)
async def handle_server_error(request: Request, exc: Exception):
"""Custom 500 handler."""
return await server_error_handler(request, exc)
if __name__ == "__main__":
uvicorn.run(
"fastapi_app:app",
host="127.0.0.1",
port=8000,
reload=True,
log_level="info"
)

6
src/server/utils/__init__.py Normal file
View File

@ -0,0 +1,6 @@
"""
Utility modules for the FastAPI application.
This package contains dependency injection, security utilities, and other
helper functions for the web application.
"""

180
src/server/utils/dependencies.py Normal file
View File

@ -0,0 +1,180 @@
"""
Dependency injection utilities for FastAPI.
This module provides dependency injection functions for the FastAPI
application, including SeriesApp instances, database sessions, and
authentication dependencies.
"""
from typing import AsyncGenerator, Optional
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from sqlalchemy.ext.asyncio import AsyncSession
from src.config.settings import settings
from src.core.SeriesApp import SeriesApp
# Security scheme for JWT authentication
security = HTTPBearer()
# Global SeriesApp instance
_series_app: Optional[SeriesApp] = None
def get_series_app() -> SeriesApp:
"""
Dependency to get SeriesApp instance.
Returns:
SeriesApp: The main application instance for anime management
Raises:
HTTPException: If SeriesApp is not initialized or anime directory
is not configured
"""
global _series_app
if not settings.anime_directory:
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail="Anime directory not configured. Please complete setup."
)
if _series_app is None:
try:
_series_app = SeriesApp(settings.anime_directory)
except Exception as e:
raise HTTPException(
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
detail=f"Failed to initialize SeriesApp: {str(e)}"
)
return _series_app
def reset_series_app() -> None:
"""Reset the global SeriesApp instance (for testing or config changes)."""
global _series_app
_series_app = None
async def get_database_session() -> AsyncGenerator[AsyncSession, None]:
"""
Dependency to get database session.
Yields:
AsyncSession: Database session for async operations
"""
# TODO: Implement database session management
# This is a placeholder for future database implementation
raise HTTPException(
status_code=status.HTTP_501_NOT_IMPLEMENTED,
detail="Database functionality not yet implemented"
)
def get_current_user(
credentials: HTTPAuthorizationCredentials = Depends(security)
) -> dict:
"""
Dependency to get current authenticated user.
Args:
credentials: JWT token from Authorization header
Returns:
dict: User information
Raises:
HTTPException: If token is invalid or user is not authenticated
"""
# TODO: Implement JWT token validation
# This is a placeholder for authentication implementation
raise HTTPException(
status_code=status.HTTP_501_NOT_IMPLEMENTED,
detail="Authentication functionality not yet implemented"
)
def require_auth(
current_user: dict = Depends(get_current_user)
) -> dict:
"""
Dependency that requires authentication.
Args:
current_user: Current authenticated user from get_current_user
Returns:
dict: User information
"""
return current_user
def optional_auth(
credentials: Optional[HTTPAuthorizationCredentials] = Depends(
HTTPBearer(auto_error=False)
)
) -> Optional[dict]:
"""
Dependency for optional authentication.
Args:
credentials: Optional JWT token from Authorization header
Returns:
Optional[dict]: User information if authenticated, None otherwise
"""
if credentials is None:
return None
try:
return get_current_user(credentials)
except HTTPException:
return None
class CommonQueryParams:
"""Common query parameters for API endpoints."""
def __init__(self, skip: int = 0, limit: int = 100):
self.skip = skip
self.limit = limit
def common_parameters(
skip: int = 0,
limit: int = 100
) -> CommonQueryParams:
"""
Dependency for common query parameters.
Args:
skip: Number of items to skip (for pagination)
limit: Maximum number of items to return
Returns:
CommonQueryParams: Common query parameters
"""
return CommonQueryParams(skip=skip, limit=limit)
# Dependency for rate limiting (placeholder)
async def rate_limit_dependency():
"""
Dependency for rate limiting API requests.
TODO: Implement rate limiting logic
"""
pass
# Dependency for request logging (placeholder)
async def log_request_dependency():
"""
Dependency for logging API requests.
TODO: Implement request logging logic
"""
pass

12
src/server/utils/templates.py Normal file
View File

@ -0,0 +1,12 @@
"""
Shared templates configuration for FastAPI application.
This module provides centralized Jinja2 template configuration.
"""
from pathlib import Path
from fastapi.templating import Jinja2Templates
# Configure templates - shared across controllers
TEMPLATES_DIR = Path(__file__).parent.parent / "web" / "templates"
templates = Jinja2Templates(directory=str(TEMPLATES_DIR))

42
src/server/web/templates/error.html Normal file
View File

@ -0,0 +1,42 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Error - Aniworld</title>
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
<link href="/static/css/styles.css" rel="stylesheet">
</head>
<body>
<div class="container mt-5">
<div class="row justify-content-center">
<div class="col-md-6">
<div class="card">
<div class="card-header">
<h4 class="card-title mb-0">Error {{ status_code }}</h4>
</div>
<div class="card-body text-center">
<div class="mb-4">
<i class="fas fa-exclamation-triangle text-warning" style="font-size: 4rem;"></i>
</div>
<h5>{{ error }}</h5>
<p class="text-muted">
{% if status_code == 404 %}
The page you're looking for doesn't exist.
{% elif status_code == 500 %}
Something went wrong on our end. Please try again later.
{% else %}
An unexpected error occurred.
{% endif %}
</p>
<a href="/" class="btn btn-primary">Go Home</a>
</div>
</div>
</div>
</div>
</div>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
<script src="https://kit.fontawesome.com/your-kit-id.js" crossorigin="anonymous"></script>
</body>
</html>