# Aniworld Web Application Infrastructure

conda activate AniWorld

## Project Structure

```
/home/lukas/Volume/repo/Aniworld/
├── src/
│   ├── server/                 # FastAPI web application
│   │   ├── fastapi_app.py     # Main FastAPI application (simplified)
│   │   ├── 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
│   │   │   ├── __init__.py
│   │   │   ├── auth.py        # Authentication endpoints
│   │   │   ├── config.py      # Configuration endpoints
│   │   │   ├── anime.py       # Anime management endpoints
│   │   │   ├── download.py    # Download queue endpoints
│   │   │   └── search.py      # Search endpoints
│   │   ├── models/            # Pydantic models
│   │   │   ├── __init__.py
│   │   │   ├── auth.py
│   │   │   ├── config.py
│   │   │   ├── anime.py
│   │   │   └── download.py
│   │   ├── services/          # Business logic services
│   │   │   ├── __init__.py
│   │   │   ├── auth_service.py
│   │   │   ├── config_service.py
│   │   │   ├── anime_service.py
│   │   │   └── download_service.py
│   │   ├── utils/             # Utility functions
│   │   │   ├── __init__.py
│   │   │   ├── security.py
│   │   │   ├── dependencies.py  # Dependency injection
│   │   │   └── templates.py     # Shared Jinja2 template config
│   │   └── web/               # Frontend assets
│   │       ├── templates/     # Jinja2 HTML templates
│   │       │   ├── base.html
│   │       │   ├── login.html
│   │       │   ├── setup.html
│   │       │   ├── config.html
│   │       │   ├── anime.html
│   │       │   ├── download.html
│   │       │   └── search.html
│   │       └── static/        # Static web assets
│   │           ├── css/
│   │           ├── js/
│   │           └── images/
│   ├── core/                  # Existing core functionality
│   └── cli/                   # Existing CLI application
├── data/                      # Application data storage
│   ├── config.json           # Application configuration
│   ├── anime_library.db      # SQLite database for anime library
│   ├── download_queue.json   # Download queue state
│   └── cache/                # Temporary cache files
├── logs/                     # Application logs
│   ├── app.log              # Main application log
│   ├── download.log         # Download-specific logs
│   └── error.log            # Error logs
├── requirements.txt         # Python dependencies
├── docker-compose.yml       # Docker deployment configuration
└── README.md
```

## Technology Stack

### Backend

-   **FastAPI**: Modern Python web framework for building APIs
-   **Uvicorn**: ASGI server for running FastAPI applications
-   **SQLite**: Lightweight database for storing anime library and configuration
-   **Pydantic**: Data validation and serialization
-   **Jinja2**: Template engine for server-side rendering

### Frontend

-   **HTML5/CSS3**: Core web technologies
-   **JavaScript (Vanilla)**: Client-side interactivity
-   **Bootstrap 5**: CSS framework for responsive design
-   **HTMX**: Modern approach for dynamic web applications

### Security

-   **Passlib**: Password hashing and verification
-   **python-jose**: JWT token handling
-   **bcrypt**: Secure password hashing

### Authentication Models & Sessions

-   Authentication request/response Pydantic models live in `src/server/models/auth.py`.
-   Sessions are represented by `SessionModel` and can be backed by an in-memory
    store or a persistent table depending on deployment needs. JWTs are used for
    stateless authentication by default; a persistent session store may be
    configured in production to enable revocation and long-lived sessions.

## Configuration

### Data Storage

-   **Configuration**: JSON files in `data/` directory
-   **Anime Library**: SQLite database with series information
-   **Download Queue**: JSON file with current download status
-   **Logs**: Structured logging to files in `logs/` directory

## API Endpoints

### Authentication

-   `POST /api/auth/login` - Master password authentication
-   `POST /api/auth/logout` - Logout and invalidate session
-   `GET /api/auth/status` - Check authentication status

### Configuration

-   `GET /api/config` - Get current configuration
-   `PUT /api/config` - Update configuration
-   `POST /api/setup` - Initial setup

### Anime Management

-   `GET /api/anime` - List anime with missing episodes
-   `POST /api/anime/{id}/download` - Add episodes to download queue
-   `GET /api/anime/{id}` - Get anime details

### Download Management

-   `GET /api/downloads` - Get download queue status
-   `DELETE /api/downloads/{id}` - Remove from queue
-   `POST /api/downloads/priority` - Change download priority

### Search

-   `GET /api/search?q={query}` - Search for anime
-   `POST /api/search/add` - Add anime to library

## Logging

### Log Levels

-   **INFO**: General application information
-   **WARNING**: Potential issues that don't stop execution
-   **ERROR**: Errors that affect functionality
-   **DEBUG**: Detailed debugging information (development only)

### Log Files

-   `app.log`: General application logs
-   `download.log`: Download-specific operations
-   `error.log`: Error and exception logs

## Security Considerations

-   Master password protection for application access
-   Secure session management with JWT tokens
-   Input validation and sanitization
-   Rate limiting on API endpoints
-   HTTPS enforcement in production
-   Secure file path handling to prevent directory traversal

### Authentication Service

-   A lightweight authentication service is provided by
    `src/server/services/auth_service.py`.
-   Uses bcrypt (passlib) to hash the master password and issues JWTs for
    stateless sessions. Tokens are signed with the `JWT_SECRET_KEY` from
    configuration and expire based on `SESSION_TIMEOUT_HOURS`.
-   Failed login attempts are tracked in-memory and a temporary lockout is
    applied after multiple failures. For multi-process deployments, move
    this state to a shared store (Redis) and persist the master password
    hash in a secure config store.

## 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
```