diff --git a/README.md b/README.md new file mode 100644 index 0000000..ef8c609 --- /dev/null +++ b/README.md @@ -0,0 +1,242 @@ +# 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 + 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. \ No newline at end of file diff --git a/web_todo.md b/web_todo.md index d5f463f..bbb1daa 100644 --- a/web_todo.md +++ b/web_todo.md @@ -139,7 +139,7 @@ This document contains tasks for migrating the web application from Flask to Fas - [ ] Update API documentation to reflect FastAPI changes - [x] Add OpenAPI/Swagger documentation (automatic with FastAPI) -- [ ] Update README with new setup instructions +- [x] Update README with new setup instructions - [ ] Document any breaking changes or new patterns ### Code Cleanup