BookBounty

BookBounty is a lightweight, container‑ready automation tool that bridges the gap between Readarr and Library Genesis (LibGen). Its primary function is to scan a Readarr library for missing titles, query LibGen for matching files, and download them into the user’s preferred directory structure. The application exposes a REST‑like API through its Flask backend, allowing developers to trigger syncs, adjust search parameters, and monitor progress programmatically.

Technical Stack & Architecture

• Language: Python 3.11, chosen for its rich ecosystem of HTTP clients and data‑handling libraries.
• Framework: Flask (micro‑framework) powers the web service, keeping the footprint small while providing straightforward routing and JSON responses.
• Concurrency: ThreadPoolExecutor controls parallel downloads; the thread_limit environment variable caps CPU usage for predictable scaling.
• Configuration: All runtime settings are injected via environment variables, making the image fully portable across Docker, Kubernetes, or bare‑metal setups.
• Persistence: BookBounty is stateless; it relies on the filesystem for logs and a simple SQLite database (bundled with the image) to track download history and retry logic.
• Networking: The app communicates over HTTP with Readarr’s API (authentication via readarr_api_key) and LibGen’s public endpoints. It uses the requests library with configurable timeouts (request_timeout) and retry back‑off.

Core Capabilities & APIs

• Missing Book Detection: Periodic or on‑demand scans of the Readarr library, filtering by missing status and language preferences.
• Search & Match: Flexible query construction (author name, title, ISBN) with options to use only the last name or shortened titles. Results are scored by minimum_match_ratio.
• Download Pipeline: Supports both file and folder download structures, automatically creating the /author/book/ hierarchy when selected_path_type=folder.
• Post‑Processing Hooks: After download, the tool can trigger a Readarr library scan (library_scan_on_completion) to integrate newly acquired files.
• Extensible Endpoints: A /sync endpoint initiates a full sync, while /status provides real‑time progress metrics. Webhooks can be wired to external services for CI/CD pipelines or monitoring dashboards.

Deployment & Infrastructure

• Containerization: A ready‑to‑run Docker image (thewicklowwolf/bookbounty) exposes port 5000 and mounts two volumes: /bookbounty/config for environment variables and persistent state, and /bookbounty/downloads for the downloaded files.
• Scalability: Although single‑instance, the stateless design allows horizontal scaling behind a load balancer if multiple users or high throughput are required. The thread_limit controls per‑instance concurrency.
• Resource Footprint: Lightweight (≈ 200 MB) with modest CPU/memory usage, making it suitable for home NAS setups or cloud VMs.
• Cross‑Platform: Works on Linux, Windows (via WSL or Docker Desktop), and macOS. The only external dependency is an accessible Readarr instance.

Integration & Extensibility

• Plugin Hooks: While BookBounty itself has no plugin system, its environment‑variable API makes it a drop‑in component in larger media automation stacks (e.g., Radarr, Sonarr). Developers can wrap it with custom scripts to enrich metadata before passing files back to Readarr.
• Webhooks: Exposes a POST /webhook endpoint that can be used to trigger actions on external services (Slack, email, or custom dashboards) whenever a download completes.
• Custom Search Logic: By modifying the search_type or language filters, developers can tailor the tool to niche catalogs (e.g., academic PDFs or translated works).

Developer Experience

• Documentation: The README provides clear instructions for Docker deployment, environment variable defaults, and sync scheduling. Inline comments in the source are sparse but sufficient for quick comprehension.
• Configuration: The reliance on environment variables eliminates the need for complex config files, reducing friction when integrating into CI pipelines.
• Community & Licensing: Open‑source under an MIT license, the project has a minimal but active GitHub community. Issues and pull requests are handled promptly, ensuring rapid iteration.

Use Cases

1. Home Media Libraries: Users running Readarr can automatically fill gaps in their e‑book collections without manual searching.
2. Academic Research: Institutions can deploy BookBounty to bulk‑download PDFs from LibGen, filtering by language and format.
3. Media Automation Stacks: As a microservice in larger ecosystems (Radarr, Sonarr), it enriches the library by fetching missing e‑books on demand.
4. Continuous Integration: Automated test suites can invoke /sync to validate that new books are correctly indexed and downloadable.

Advantages Over Alternatives

• Zero‑Configuration API: Unlike manual download scripts, BookBounty exposes a clean HTTP interface that can be consumed by any language.
• Built‑in Scoring & Filtering: The minimum_match_ratio and extension filters reduce false positives, saving bandwidth.
• Container‑Friendly: A single Docker image with environment‑variable overrides simplifies deployment across heterogeneous environments.
• Open Source & Lightweight: No vendor lock‑in; the small footprint makes it ideal for low‑resource devices.

In summary, BookBounty offers developers a concise, extensible bridge between