How woahai321/list-sync works
Project Type & Purpose
• ListSync is a media sync tool that periodically fetches watchlists via web scraping (using Selenium) and then interacts with media servers via provided APIs. It automates the process of checking for available content and, if needed, requesting media.
• The README emphasizes two operational modes (Interactive and Automated) and highlights integration with Docker and Docker Compose for deployment.
• The project is implemented primarily in Python, with configuration managed through environment files, and it is containerized, as shown by Dockerfiles and devcontainer settings.
Analyzing the File Structure
• Top-Level Structure:
• Configuration and DevOps: Files like Dockerfile, docker-compose.yml, .env.example, and .devcontainer directories indicate a containerized environment and CI/CD pipelines (.github/workflows).
• Documentation: Folder “docs” contains detailed guides (installation, troubleshooting, roadmap), which provide additional context on how the system should operate.
• Code: The primary executable script appears to be add.py; Python dependency files (requirements.txt, pyproject.toml) indicate a Python project.
• The presence of pre-commit config, GitHub workflows, and Docker-related files suggests a release-ready project with strict code quality and deployment practices.
Key Components
a. Configuration Loader:
• Reads environment variables from the .env (or .env.example) file.
• Loads settings that determine modes (Interactive vs. Automated), media server API credentials, list source URLs/IDs, and sync intervals.
b. Watchlist Fetch Module:
• Uses Selenium to scrape data from IMDb, Trakt, and Letterboxd.
• Responsible for handling input URL or ID, parsing it to extract the list of media items.
c. Media Server Interface:
• Integrates with APIs of Overseerr or Jellyseerr to perform media searches and submit requests.
• Handles differences for movies and TV shows (ex. requesting entire TV seasons).
d. Execution Modes:
• Interactive Mode: Prompts the user for necessary configuration during runtime.
• Automated Mode: Reads preset configuration to perform syncing operations automatically (managed by Docker Compose in production).
e. Containerization & Deployment:
• Dockerfile and docker-compose.yml represent a containerized deployment environment.
• Development tools (such as .devcontainer for VSCode) indicate a well-defined local development environment.
f. External Integrations:
• External services like SeerrBridge (described in the README) which works in tandem with the core functionality.
• Media server applications (Overseerr, Jellyseerr) and possibly styled logging/monitoring components.
Relationships & Interactions
• The Configuration Loader feeds both the Watchlist Fetch Module and Media Server Interface.
• The Watchlist Fetch Module retrieves media items from external watchlist sources, then passes this list to the Media Server Interface.
• The Media Server Interface, after processing and matching, sends media requests if items are missing or not already available.
• Both components can operate in different modes (Interactive vs. Automated) as dictated by the settings.
• Docker and CI/CD pipelines manage deployment and potentially regular syncing intervals.
Elements
• Each Component: Label nodes clearly (e.g., “Configuration Loader”, “Watchlist Fetch Module”, “Media Server API Interface”, “Docker Container/Deployment”).
• Internal application modules (e.g., rounded rectangles for business logic modules)
• Notations: Include annotations on the interactions, like “Fetch Watchlist Data”, “Parse and Validate”, “API Request for Media”.
Additional Notes
• Adding a separate section for deployment details (DevContainer, Docker Compose) to clearly represent the execution environment.