Aniworld/README.md

# AniWorld - Anime Series Management System

A powerful anime series management system that helps you track, organize, and download your favorite anime series. Recently migrated from Flask to FastAPI for improved performance and modern API capabilities.

## 🚀 Features

### Core Functionality

-   **Series Tracking**: Automatically detect missing episodes in your anime collection
-   **Smart Downloads**: Queue-based download system with progress tracking
-   **File Organization**: Automatic file scanning and folder structure management
-   **Search Integration**: Search for anime series across multiple providers
-   **Real-time Updates**: Live progress updates via WebSocket connections

### Web Interface

-   **Modern UI**: Clean, responsive web interface with dark/light theme support
-   **Download Queue**: Visual download queue management
-   **Progress Tracking**: Real-time download and scan progress
-   **Mobile Support**: Fully responsive design for mobile devices

### API & Integration

-   **FastAPI Backend**: High-performance async API with automatic documentation
-   **RESTful API**: Complete REST API for programmatic access
-   **OpenAPI Documentation**: Interactive API documentation at `/docs`
-   **Authentication**: Secure master password authentication with JWT tokens

## 🎯 Recent Migration: Flask → FastAPI

This project has been successfully migrated from Flask to FastAPI, bringing significant improvements:

### Performance Benefits

-   **Async Support**: Native async/await for better concurrency
-   **Faster Response Times**: Up to 2-3x performance improvement
-   **Better Resource Utilization**: More efficient handling of concurrent requests

### Developer Experience

-   **Automatic Documentation**: Built-in OpenAPI/Swagger documentation
-   **Type Safety**: Full request/response validation with Pydantic
-   **Modern Standards**: OpenAPI 3.0 compliance and JSON Schema validation
-   **Better Error Handling**: Structured error responses with detailed information

### API Improvements

-   **Interactive Documentation**: Test API endpoints directly from `/docs`
-   **Schema Validation**: Automatic request/response validation
-   **Better Error Messages**: Detailed validation errors with field-level feedback

## 🛠️ Installation & Setup

### Prerequisites

-   Python 3.11+
-   Conda package manager
-   Windows OS (currently optimized for Windows)

### Quick Start

1. **Clone the Repository**

    ```bash
    git clone <repository-url>
    cd Aniworld
    ```

2. **Create and Activate Conda Environment**

    ```bash
    conda create -n AniWorld python=3.11
    conda activate AniWorld
    ```

3. **Install Dependencies**

    ```bash
    pip install -r requirements.txt
    ```

4. **Set Environment Variables**

    ```bash
    # Set your master password (will be hashed automatically)
    set MASTER_PASSWORD=your_secure_password
    ```

5. **Start the FastAPI Server**

    ```bash
    # Development mode with auto-reload
    uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload

    # Or use the VS Code task: "Run FastAPI Server"
    ```

6. **Access the Application**
    - **Web Interface**: http://localhost:8000
    - **API Documentation**: http://localhost:8000/docs
    - **Alternative API Docs**: http://localhost:8000/redoc

### Alternative: Using VS Code Tasks

If you're using VS Code, you can use the pre-configured tasks:

-   `Ctrl+Shift+P` → "Tasks: Run Task" → "Run FastAPI Server"

## 🔧 Configuration

### Environment Variables

-   `MASTER_PASSWORD` - Your master password (will be hashed automatically)
-   `MASTER_PASSWORD_HASH` - Pre-hashed password (alternative to MASTER_PASSWORD)
-   `JWT_SECRET_KEY` - Secret key for JWT token signing (auto-generated if not set)
-   `LOG_LEVEL` - Logging level (DEBUG, INFO, WARNING, ERROR)

### Directory Structure

```
Aniworld/
├── src/
│   ├── core/                 # Core business logic
│   │   ├── SeriesApp.py     # Main application controller
│   │   ├── entities/        # Data models
│   │   └── providers/       # Content providers
│   ├── server/              # FastAPI server
│   │   ├── fastapi_app.py   # Main FastAPI application
│   │   └── web/             # Web interface and controllers
│   └── infrastructure/      # Infrastructure components
├── data/                    # Application data and databases
├── logs/                    # Application logs
└── requirements.txt         # Python dependencies
```

## 🌐 API Usage

### Authentication

1. **Login to get JWT token**:

    ```bash
    curl -X POST "http://localhost:8000/auth/login" \
         -H "Content-Type: application/json" \
         -d '{"password": "your_master_password"}'
    ```

2. **Use token in requests**:
    ```bash
    curl -X GET "http://localhost:8000/api/anime/search?query=naruto" \
         -H "Authorization: Bearer your_jwt_token_here"
    ```

### Key Endpoints

-   **Authentication**: `/auth/login`, `/auth/verify`, `/auth/logout`
-   **System**: `/health`, `/api/system/config`
-   **Anime**: `/api/anime/search`, `/api/anime/{id}`
-   **Episodes**: `/api/episodes/{id}`, `/api/anime/{id}/episodes`
-   **Downloads**: `/api/download`, `/api/add_series`

For complete API documentation, visit `/docs` when the server is running.

## 🖥️ Web Interface

### Main Features

-   **Dashboard**: Overview of your anime collection and missing episodes
-   **Search**: Find and add new anime series to track
-   **Downloads**: Manage download queue and monitor progress
-   **Settings**: Configure application preferences

### Responsive Design

The web interface is fully responsive and supports:

-   Desktop browsers (Chrome, Firefox, Edge, Safari)
-   Mobile devices (iOS Safari, Android Chrome)
-   Tablet devices
-   Dark and light themes

## 🔍 Troubleshooting

### Common Issues

1. **Server won't start**

    - Check that the AniWorld conda environment is activated
    - Verify all dependencies are installed: `pip install -r requirements.txt`
    - Check for port conflicts (default: 8000)

2. **Authentication errors**

    - Verify the master password is set correctly
    - Check environment variables are properly configured
    - Clear browser cache/cookies

3. **Import errors**
    - Ensure all required packages are installed
    - Check Python path configuration
    - Verify conda environment is activated

### Logs

Application logs are stored in the `logs/` directory:

-   `aniworld.log` - General application logs
-   `errors.log` - Error-specific logs
-   `auth_failures.log` - Authentication failure logs

## 🚦 Development

### Running in Development Mode

```bash
# With auto-reload for development
uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload --log-level debug
```

### Testing

```bash
# Run all tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest tests/ --cov=src --cov-report=html
```

### Code Quality

```bash
# Format code
black src/
isort src/

# Lint code
pylint src/
flake8 src/
```

## 📚 Documentation

-   **API Documentation**: Available at `/docs` (Swagger UI) and `/redoc` (ReDoc)
-   **Migration Guide**: See `API_DOCUMENTATION.md` for detailed migration information
-   **FastAPI Specific**: See `src/server/README_FastAPI.md` for server-specific documentation

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🙏 Acknowledgments

-   FastAPI team for the excellent framework
-   The original Flask implementation that served as the foundation
-   All contributors and users of the AniWorld project

---

**Note**: This application is for personal use only. Please respect copyright laws and terms of service of content providers.