Aniworld/docs/README.md

Aniworld Documentation

Complete documentation for the Aniworld Download Manager application.

Quick Start

• New Users: Start with User Guide
• Developers: Check API Reference
• System Admins: See Deployment Guide
• Interactive Docs: Visit http://localhost:8000/api/docs

Documentation Structure

📖 User Guide (user_guide.md)

Complete guide for end users covering:

• Installation instructions
• Initial setup and configuration
• User interface walkthrough
• Managing anime library
• Download queue management
• Configuration and settings
• Troubleshooting common issues
• Keyboard shortcuts
• Frequently asked questions (FAQ)

Best for: Anyone using the Aniworld application

🔌 API Reference (api_reference.md)

Detailed API documentation including:

• Authentication and authorization
• Error handling and status codes
• All REST endpoints with examples
• WebSocket real-time updates
• Request/response formats
• Rate limiting and pagination
• Complete workflow examples
• API changelog

Best for: Developers integrating with the API

🚀 Deployment Guide (deployment.md)

Production deployment instructions covering:

• System requirements
• Pre-deployment checklist
• Local development setup
• Production deployment steps
• Docker and Docker Compose setup
• Nginx reverse proxy configuration
• SSL/TLS certificate setup
• Database configuration (SQLite and PostgreSQL)
• Security best practices
• Monitoring and maintenance
• Troubleshooting deployment issues

Best for: System administrators and DevOps engineers

Key Features Documented

Authentication

• Master password setup and login
• JWT token management
• Session handling
• Security best practices

Configuration Management

• Application settings
• Directory configuration
• Backup and restore functionality
• Environment variables

Anime Management

• Browsing anime library
• Adding new anime
• Managing episodes
• Search functionality

Download Management

• Queue operations
• Priority management
• Progress tracking
• Error recovery

Real-time Features

• WebSocket connections
• Live download updates
• Status notifications
• Error alerts

Series Identifier Convention

Understanding Series Identifiers

The application uses two identifiers for anime series:

Identifier	Purpose	Example	Used For
key	Primary identifier	"attack-on-titan"	All API lookups
folder	Filesystem metadata only	"Attack on Titan (2013)"	Display purposes

Key Format

• Lowercase letters and numbers only
• Words separated by hyphens (-)
• No spaces, underscores, or uppercase letters
• Examples: "one-piece", "86-eighty-six", "re-zero"

Usage Guidelines

# ✅ Correct: Use 'key' for API operations
GET /api/anime/attack-on-titan
POST /api/queue/add {"serie_id": "attack-on-titan", ...}

# ❌ Deprecated: Folder-based lookups (backward compatibility only)
GET /api/anime/Attack%20on%20Titan%20(2013)  # Will work but deprecated

Backward Compatibility

For existing integrations, folder-based lookups are still supported but deprecated:

• API endpoints check key first, then fall back to folder
• New code should always use key as the identifier
• Deprecation warnings will be added in future versions

Documentation Examples

API Usage Example

# Setup
curl -X POST http://localhost:8000/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"master_password": "secure_pass"}'

# Login
TOKEN=$(curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password": "secure_pass"}' | jq -r '.token')

# List anime
curl http://localhost:8000/api/v1/anime \
  -H "Authorization: Bearer $TOKEN"

Deployment Example

# Clone and setup
git clone https://github.com/your-repo/aniworld.git
cd aniworld
python3.10 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run application
python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000

Interactive Documentation

Access interactive API documentation at:

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

These provide:

• Interactive API explorer
• Try-it-out functionality
• Request/response examples
• Schema validation

Common Tasks

I want to...

Use the application → Read User Guide → Getting Started section

Set up on my computer → Read User Guide → Installation section

Deploy to production → Read Deployment Guide → Production Deployment

Use the API → Read API Reference → API Endpoints section

Troubleshoot problems → Read User Guide → Troubleshooting section

Set up with Docker → Read Deployment Guide → Docker Deployment

Configure backup/restore → Read User Guide → Configuration section

Debug API issues → Check API Reference → Error Handling section

Documentation Standards

All documentation follows these standards:

Structure

• Clear table of contents
• Logical section ordering
• Cross-references to related topics
• Code examples where appropriate

Style

• Plain, accessible language
• Step-by-step instructions
• Visual formatting (code blocks, tables, lists)
• Examples for common scenarios

Completeness

• All major features covered
• Edge cases documented
• Troubleshooting guidance
• FAQ section included

Maintenance

• Version number tracking
• Last updated timestamp
• Changelog for updates
• Broken link checking

Help & Support

Getting Help

1. Check Documentation First

   • Search in relevant guide
   • Check FAQ section
   • Look for similar examples

2. Check Logs

   • Application logs in /logs/
   • Browser console (F12)
   • System logs

3. Try Troubleshooting

   • Follow troubleshooting steps in user guide
   • Check known issues section
   • Verify system requirements

4. Get Community Help

   • GitHub Issues
   • Discussion Forums
   • Community Discord

5. Report Issues

   • File GitHub issue
   • Include logs and error messages
   • Describe reproduction steps
   • Specify system details

Feedback

We welcome feedback on documentation:

• Unclear sections
• Missing information
• Incorrect instructions
• Outdated content
• Suggest improvements

File documentation issues on GitHub with label documentation.

Contributing to Documentation

Documentation improvements are welcome! To contribute:

1. Fork the repository
2. Edit documentation files
3. Test changes locally
4. Submit pull request
5. Include summary of changes

See CONTRIBUTING.md for guidelines.

Documentation Map

docs/
├── README.md               # This file
├── user_guide.md          # End-user documentation
├── api_reference.md       # API documentation
├── deployment.md          # Deployment instructions
└── CONTRIBUTING.md        # Contribution guidelines

Related Resources

• Source Code: GitHub repository
• Interactive API: http://localhost:8000/api/docs
• Issue Tracker: GitHub Issues
• Releases: GitHub Releases
• License: See LICENSE file

Document Info

• Last Updated: November 28, 2025
• Version: 2.0.0
• Status: Production Ready
• Maintainers: Development Team

---

Quick Links

Resource	Link
User Guide	user_guide.md
API Reference	api_reference.md
Deployment Guide	deployment.md
Swagger UI	http://localhost:8000/api/docs
GitHub Issues	https://github.com/your-repo/aniworld/issues
Project Repository	https://github.com/your-repo/aniworld

---

For Questions: Check relevant guide first, then file GitHub issue with details.