nefarious

nefarious is a full‑stack, self‑hosted media acquisition platform that orchestrates torrent discovery and downloading for movies and TV shows. From a developer’s perspective, the application acts as an orchestrator layer that plugs into two mature open‑source services: Jackett for multi‑tracker torrent searching and Transmission for BitTorrent client operations. The web UI exposes a rich set of APIs that let external services or custom plugins trigger searches, apply quality filters, and monitor download status—all while handling authentication, user roles, and notification routing.

• Backend: The core is written in Go, leveraging the standard library’s net/http and html/template packages for a lightweight, statically‑compiled binary. Business logic is split into domain services (search, download, media management) and a thin RESTful API layer that the Vue‑based frontend consumes.
• Frontend: A modern SPA built with Vue.js 3 and Vite, using component‑driven design for responsive layouts. The UI communicates with the backend via JSON over HTTPS, and WebSocket streams are used for real‑time Transmission status updates.
• Database: A lightweight SQLite file stores user accounts, preferences, blacklists, and media metadata. The schema is defined via Go structs annotated with sql tags, allowing easy migration through embedded tooling.
• External Services:
  • Jackett is invoked over its HTTP API to perform tracker‑agnostic searches.
  • Transmission is controlled through its RPC interface, enabling programmatic torrent addition, removal, and progress polling.
  • Apprise (via its Python library) is wrapped in a Go executor to push notifications to Slack, Telegram, email, and more.
  • OpenSubtitles is accessed through its REST API to fetch subtitles automatically.
• Containerization: The project ships a Docker image (lardbit/nefarious) that bundles the Go binary, Node dependencies for the frontend build, and a Docker‑Compose file to spin up Jackett, Transmission, and nefarious in a single orchestrated stack.

• Automated Search & Download: Users can define quality profiles (e.g., 1080p movies, 720p TV) and keyword filters; the system queries Jackett, parses results, applies filters, and hands off selected torrents to Transmission.
• Blacklisting & Spam Detection: The app maintains a persistent blacklist of torrent hashes or seeders, and implements heuristic checks (e.g., “stuck” torrents exceeding a threshold) to prune unwanted downloads.
• Media Renaming & Organization: Upon completion, the app renames files to a canonical format ({Title} ({Year}) [{Quality}].mkv) and moves them into a user‑defined library folder, optionally downloading subtitles.
• Discovery APIs: Exposes endpoints to fetch recommendations from TMDB and Rotten Tomatoes, enabling integration with external discovery tools or custom recommendation engines.
• Webhooks & Extensibility: Developers can hook into events (download started, completed, failed) via a simple webhook payload system, allowing custom automation pipelines or CI/CD triggers.

The application is designed for self‑hosting on any Linux host with Docker support. It requires a few volumes: one for the SQLite database, another for media storage, and optional VPN configuration. Scaling horizontally is straightforward—run multiple nefarious instances behind a load balancer, sharing the same database and media volumes via NFS or cloud object storage. Because the core is a single binary, resource usage stays low (≈200 MB RAM) even under heavy search loads.

• Plugin System: Although currently minimal, the architecture allows adding Go plugins that register new search providers or media processors.
• API First: All internal actions are exposed over a versioned REST API (/api/v1/...), making it trivial to build custom clients or integrate with existing media servers (e.g., Plex, Jellyfin).
• Webhooks: Events can be sent to arbitrary endpoints; the payload includes metadata such as media title, quality, and file path.
• Customization: Themes can be swapped by editing Vue components; the configuration file (.env) exposes ports, authentication secrets, and feature flags.

The repository follows clean Go conventions with unit tests covering core logic. Documentation is split into README, detailed docs/ folders, and inline code comments. The community is active on GitHub Issues and Discord, providing quick support for integration questions. Continuous Integration via GitHub Actions ensures that every pull request passes linting, tests, and a build step before merging.

1. Home Media Automation – A developer can deploy nefarious on a NAS, integrate it with Plex, and let the system auto‑download new episodes as soon as they are released.
2. Custom Recommendation Engine – By consuming the TMDB/Rotten Tomatoes APIs exposed by nefarious, a developer can build a personalized recommendation service that pushes titles to users via Discord.
3. Enterprise Media Library – Organizations needing a controlled media ingestion pipeline (e.g., educational institutions) can use the blacklisting and quality profile features to enforce compliance while keeping automation.
4. Hybrid Cloud Deployment – With Docker Compose, nefarious can be deployed on a Kubernetes cluster