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

   git clone <repository-url>
   cd Aniworld
   

2. Create and Activate Conda Environment

   conda create -n AniWorld python=3.11
   conda activate AniWorld
   

3. Install Dependencies

   pip install -r requirements.txt
   

4. Set Environment Variables

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

5. Start the FastAPI Server

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

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

2. Use token in requests:

   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

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

Testing

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

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

Code Quality

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