# Aniworld Documentation

Complete documentation for the Aniworld Download Manager application.

## Quick Start

-   **New Users**: Start with [User Guide](./user_guide.md)
-   **Developers**: Check [API Reference](./api_reference.md)
-   **System Admins**: See [Deployment Guide](./deployment.md)
-   **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

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

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

```bash
# 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](./user_guide.md) → Getting Started section

**Set up on my computer**
→ Read [User Guide](./user_guide.md) → Installation section

**Deploy to production**
→ Read [Deployment Guide](./deployment.md) → Production Deployment

**Use the API**
→ Read [API Reference](./api_reference.md) → API Endpoints section

**Troubleshoot problems**
→ Read [User Guide](./user_guide.md) → Troubleshooting section

**Set up with Docker**
→ Read [Deployment Guide](./deployment.md) → Docker Deployment

**Configure backup/restore**
→ Read [User Guide](./user_guide.md) → Configuration section

**Debug API issues**
→ Check [API Reference](./api_reference.md) → 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](./user_guide.md)             |
| API Reference      | [api_reference.md](./api_reference.md)       |
| Deployment Guide   | [deployment.md](./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.