Bazinga - Comic Book Management System

A comprehensive comic book management application that automates downloading, cataloging, and quality management for your comic collection. Built with FastAPI and SQLAlchemy, it integrates with multiple metadata providers and AirDC++ for seamless automated workflows.

Features

• Multi-Provider Metadata: Search and fetch metadata from ComicVine, Metron, and GCD (Grand Comics Database)
• Intelligent Quality Scoring: Automatic quality evaluation (0-100 scale) based on format, file size, release group, and scan type
• Library Scanning: Recursive directory scanning with automatic issue matching and verification
• Download Integration: AirDC++ webhook support for automated post-processing of downloaded files
• Smart Metadata Generation: Auto-generate ComicInfo.xml (ComicRack) and MetronInfo.xml (Metron) formats
• Upgrade Detection: Identifies files eligible for quality upgrades
• Archive Support: Handle CBZ, CB7, CBR, and PDF formats with automatic conversion where possible
• TTH Verification: Tiger Tree Hash calculation for file verification and integrity checking

Getting Started

Prerequisites

• Python: 3.8 or higher
• Database: SQLite (default, no setup needed) or PostgreSQL
• System Tools: For archive handling (CBR/RAR support)
  • Linux: sudo apt-get install unrar
  • macOS: brew install unrar
  • Windows: Download from https://www.rarlab.com/rar_add.htm and add to PATH
• Disk Space: Adequate space for comic library and metadata cache

Step-by-Step Setup

1. Clone and Navigate to Backend

# Navigate to the project directory
cd Bazinga
cd backend

2. Create Python Virtual Environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate

# On Windows (Command Prompt):
venv\Scripts\activate

# On Windows (PowerShell):
venv\Scripts\Activate.ps1

3. Install System Dependencies

Linux:

sudo apt-get update
sudo apt-get install unrar python3-dev

macOS:

brew install unrar

Windows:

• Download UnRAR from https://www.rarlab.com/rar_add.htm
• Extract and add the installation directory to your system PATH
• Verify: Open Command Prompt and type unrar - should show help

4. Install Python Dependencies

# Upgrade pip
pip install --upgrade pip

# Install project dependencies
pip install -r requirements.txt

This installs:

• FastAPI and Uvicorn for the web framework
• SQLAlchemy for database ORM
• Pydantic for configuration and validation
• Metadata provider wrappers (Simyan, Mokkari, Grayven)
• Archive handling (rarfile, py7zr)
• And other required dependencies

5. Configure Environment

# Copy example configuration
cp .env.example .env

# Edit the configuration file with your details
# See Configuration section below for all available options

Minimal Configuration (.env):

At minimum, configure these required settings:

# Secret key for authentication - REQUIRED
# Generate a strong random string (e.g., python -c "import secrets; print(secrets.token_urlsafe(32))")
SECRET_KEY=your_secure_random_key_here

# Database
DATABASE_URL=sqlite:///./bazinga.db

# Directories (create these first)
SHARE_DIRECTORY=/path/to/comics/share
TAGGED_DIRECTORY=/path/to/comics/tagged

# At least one metadata provider API key
n# Processing Mode (optional, default is 'full')
# Options: 'full', 'tagged_only', 'share_only'
PROCESSING_MODE=full
COMICVINE_API_KEY=your_api_key

Full Configuration Options:

See CLAUDE.md Configuration Section for all available environment variables.

# Database
DATABASE_URL=sqlite:///./bazinga.db
# Or for PostgreSQL:
# DATABASE_URL=postgresql://user:password@localhost/bazinga

# Authentication
SECRET_KEY=your_secure_random_key_here
ENABLE_AUTH=true

# AirDC++ Integration (optional)
AIRDCPP_URL=http://localhost:5600
AIRDCPP_USERNAME=your_username
AIRDCPP_PASSWORD=your_password

# Metadata Providers (use at least one)
COMICVINE_API_KEY=your_api_key
METRON_USERNAME=your_metron_username
METRON_PASSWORD=your_metron_password
GCD_SQLITE_PATH=/path/to/gcd_database.sqlite

# Comic Directories
SHARE_DIRECTORY=/data/media/comics/share
TAGGED_DIRECTORY=/data/media/comics/tagged

# Quality Settings (optional - uses defaults if not set)
PREFERRED_FORMAT=cbz
QUALITY_UPGRADE_CHECK_THRESHOLD=70
QUALITY_MIN_UPGRADE_THRESHOLD=15

# Post-processing Settings (optional)
GENERATE_COMICINFO=true
GENERATE_METRONINFO=false
VERIFICATION_FILELISTS=/path/to/filelist1.xml

# Timeouts (optional - in seconds)
TTH_CALCULATION_TIMEOUT=300
PAGE_COUNT_EXTRACTION_TIMEOUT=60
POST_PROCESSING_TIMEOUT=300
AIRDCPP_SEARCH_TIMEOUT=30
AIRDCPP_REQUEST_TIMEOUT=30

6. Create Required Directories

# Create directories for comics (update paths based on your .env)
mkdir -p /path/to/comics/share
mkdir -p /path/to/comics/tagged

7. Initialize Database

# Option 1: Using the database management script (recommended)
python manage_db.py init

# Option 2: Using Alembic migrations
alembic upgrade head

Expected output:

INFO: Alembic version table created
INFO: Running upgrade script...
INFO: Database initialized successfully

8. Verify Installation

# Test that all imports work
python -c "from app.core.config import settings; print('Configuration loaded successfully')"

9. Start the Application

# Development mode with auto-reload
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Production mode (without reload)
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

Expected output:

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete

10. Verify Application is Running

1. Check API Health: Open in browser: http://localhost:8000/docs
2. Test Metadata Search: http://localhost:8000/api/series/search?query=Batman
3. Check API Key Authentication: Submit test request with API key

Quick Test

Once running, test that everything is working:

# Search for a comic series
curl "http://localhost:8000/api/series/search?query=Batman"

# Test library scan
curl -X POST http://localhost:8000/api/library/scan \
  -H "Content-Type: application/json" \
  -d '{"directory": "/path/to/your/comics", "recursive": true}'

Common Issues During Setup

Issue: ModuleNotFoundError: No module named 'app'

• Make sure you're in the backend/ directory
• Verify virtual environment is activated
• Reinstall dependencies: pip install -r requirements.txt

Issue: UnRAR not found

• Windows: Add UnRAR installation directory to system PATH environment variable
• Linux/macOS: Reinstall unrar (brew install unrar or apt-get install unrar)
• Application will work but CBR files won't be converted to CBZ

Issue: sqlite3.OperationalError: unable to open database file

• Verify SHARE_DIRECTORY and TAGGED_DIRECTORY exist
• Check disk space availability
• Ensure the application has write permissions to these directories

Issue: SECRET_KEY not configured

• Generate a key: python -c "import secrets; print(secrets.token_urlsafe(32))"
• Add to .env: SECRET_KEY=<generated_key>

Issue: Port 8000 already in use

• Use a different port: uvicorn main:app --port 8001
• Or kill process using port 8000

For more troubleshooting, see the Troubleshooting section below.

Getting API Access

ComicVine (via Simyan)

1. Sign up at https://comicvine.gamespot.com/
2. Get API key at https://comicvine.gamespot.com/api/
3. Free tier available

Metron (via Mokkari)

1. Create account at https://metron.cloud/
2. Use your login credentials
3. Free access for all users

GCD - Grand Comics Database (via Grayven)

Option 1: Database (Recommended)

1. Download SQLite database from https://www.comics.org/download/
2. Extract and use local file
3. No account needed - instant lookups

Option 2: API

1. Sign up at https://www.comics.org/
2. Request API access
3. May require approval

API Usage

Search for Comic Series

curl "http://localhost:8000/api/series/search?query=Batman"

Scan Library

curl -X POST http://localhost:8000/api/library/scan \
  -H "Content-Type: application/json" \
  -d '{"directory": "/comics", "recursive": true}'

Get Upgrade Candidates

curl "http://localhost:8000/api/library/upgrade-candidates"

Process Downloaded File

curl -X POST http://localhost:8000/api/process/ \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/downloads/Batman.cbz"}'

See the interactive API docs at http://localhost:8000/docs for all endpoints.

Quality Scoring Algorithm

Quality scores are calculated on a 0-100 scale based on:

• Format (configurable): CBZ (100) > CB7 (90) > CBR (80) > PDF (50)
• File Size (configurable): 10-150 MB optimal (100pts), below 5MB or above 500MB penalized
• Release Group (configurable): Whitelist/blacklist settings
• Scan Type (configurable): Digital-HD (+15) > Digital (+10) > C2C (+5) > Web (-10)
• Verification Bonus (+20): TTH verified files
• Release Group Bonus (+20): Premium groups (Empire, DCP, Minutemen)

Files scoring below the upgrade threshold (default: 70) are automatically marked as upgrade candidates.

Project Structure

backend/
├── app/
│   ├── api/              # API endpoints
│   ├── clients/          # External API clients
│   ├── core/             # Configuration and auth
│   ├── jobs/             # Background jobs
│   ├── models/           # Database models
│   ├── providers/        # Metadata providers
│   ├── schemas/          # Pydantic schemas
│   ├── services/         # Business logic
│   └── utils/            # Utilities (TTH, etc.)
├── migrations/           # Database migrations
├── main.py              # Application entry point
└── requirements.txt     # Dependencies

Workflow

1. Initial Setup

• Configure API credentials in .env
• Run database migration
• Scan existing comic library

2. Add Series

• Search across multiple metadata providers
• Add series to your library
• Background job searches for wanted issues

3. Download & Auto-Process

• AirDC++ downloads file
• Webhook triggers post-processing pipeline:
  1. TTH hash calculated and verified
  2. Quality scored
  3. Metadata generated (ComicInfo.xml/MetronInfo.xml)
  4. Page count detected
  5. Cover image extracted
  6. File moved to tagged directory
  7. Database updated with file path

4. Manage Quality

• Review upgrade candidates
• Delete outdated/low-quality files
• Maintain optimal file format and size

Security

The application implements several security measures:

• ✅ Credentials stored in environment variables (never hardcoded)
• ✅ SQL injection prevention via SQLAlchemy ORM
• ✅ Input validation and path sanitization
• ✅ JWT and API key authentication
• ✅ Rate limiting on endpoints
• ✅ Secure password hashing for stored credentials

See CLAUDE.md for detailed security assessment.

Documentation

• CLAUDE.md - Complete technical documentation, architecture, and code quality assessment
• API Docs - Available at /docs endpoint when application is running (Swagger UI)
• Configuration - Full environment variable reference in CLAUDE.md

Troubleshooting

CBR Files Not Converting

• Ensure UnRAR is installed and in your system PATH
• Windows: Download from https://www.rarlab.com/rar_add.htm
• Linux: sudo apt-get install unrar
• macOS: brew install unrar
• Note: Without UnRAR, CBR files are stored as-is without metadata

Database Migration Issues

# Reset database (development only)
rm bazinga.db
alembic upgrade head

TTH Calculation Timeout

• Increase TTH_CALCULATION_TIMEOUT in .env (default: 300 seconds)
• Check system resources - may indicate slow disk I/O

Performance

The application is optimized for performance:

• Async/Await: Non-blocking operations throughout
• Parallel API Calls: Query multiple providers simultaneously
• Database Fallback: GCD SQLite for instant metadata lookups
• Connection Pooling: Reuse HTTP connections
• Batch Operations: Optimized library scanning

Support

• Metron Discord: https://discord.gg/metron
• ComicVine Forums: https://comicvine.gamespot.com/forums/
• GCD Mailing List: https://www.comics.org/contact/
• Issues: Report bugs at the project repository

License

[License information to be added]

Contributing

Contributions are welcome! Please see the project repository for guidelines.

---

Version: 0.1.1 Last Updated: 2025-12-27 Status: Development

For detailed technical information, architecture, and security assessment, see CLAUDE.md.