How mathisverstrepen/letterboxd-jellyfin-go works
Project Overview and Purpose
• The project is a Go-based script built to import a user's Letterboxd watchlist into their Jellyfin library.
• It performs web scraping (via a custom “gosoup” package) on Letterboxd to obtain the watchlist, then interacts with two separate APIs:
• Radarr API – used to add movies not already in the Jellyfin library.
• Jellyfin API – used to update and manage a dedicated watchlist collection.
• The project is modular, with separate components handling scraping (Letterboxd), movie fetching/publishing (fetch and gosoup), and API interactions (jellyfin and radarr). There is also a configuration module and deployment components (Dockerfile, docker-compose, and crontab).
File Structure Insights
• The top-level directories (config, fetch, gosoup, jellyfin, letterboxd, radarr) indicate that the project is organized by feature/component.
• The config module (config.go, config.json, config_test.go) manages global configuration settings.
• The dedicated modules for letterboxd, jellyfin, and radarr (and their corresponding tests) suggest clear separation of responsibilities.
• The “fetch” and “gosoup” packages hint at custom HTTP fetching and HTML parsing used for scraping Letterboxd.
• Docker-related files indicate that the service is containerized and intended to be deployed (with a scheduled run via cron).
Key Components
a. Main Orchestrator:
• main.go acts as the application’s entry point, coordinating interactions among the modules.
b. Configuration Module:
• Loads settings from config.json; used by all modules.
c. Letterboxd Component:
• Contains the web scraper (likely utilizing “fetch” and “gosoup”) to extract watchlist data.
d. Jellyfin Component:
• Connects to the Jellyfin API to manage the watchlist collection and library updates.
e. Radarr Component:
• Interacts with the Radarr API to add movies missing from the Jellyfin library.
f. Utility Modules:
• “fetch” and “gosoup” work as helper libraries for HTTP requests and HTML parsing needed by the Letterboxd component.
g. Deployment Artifacts:
• Dockerfile, docker-compose.yml, and crontab illustrate containerization and scheduled execution.
Relationships & Interactions
• The workflow starts in main.go, which loads configuration and kicks off the process.
• The Letterboxd module scrapes the watchlist using helper functions from fetch and gosoup.
• Scraped data is then sent in parallel (or sequentially) to both the Radarr and Jellyfin modules:
• The Radarr module performs checks against the current library and adds missing movies.
• The Jellyfin module updates the watchlist collection within Jellyfin.
Architectural Patterns and Design Principles
• Modular Design: Each module (letterboxd, jellyfin, radarr, config) is isolated with a distinct responsibility.
• Clear Separation of Concerns: Scraping logic is separate from API integration logic.
• Containerized Deployment: Use of Docker shows a focus on reliable and isolated execution.
• Testability: Presence of _test.go files for various modules indicates an emphasis on unit testing.
Detailed Elements for Inclusion
• main.go → config → letterboxd scraper.
• Letterboxd scraper → (via fetch/gosoup) → external Letterboxd website.
• Letterboxd scraper → → Radarr API module and Jellyfin API module.
• Provide notes on deployment at the side (deployment/Docker container with a cronjob scheduling symbol).