Skip to main content

14. Unified Script Architecture

Status: Accepted Date: 2025-07-06

Context​

The media organization process involves multiple steps and tools (e.g., mnamer, GuessIt, cleanup, logging). Exposing all these individual scripts to the user or to an automation system like cron would be confusing and highly error-prone. A user might run the scripts in the wrong sequence, forget a step, or configure a cron job incorrectly, leading to partial or failed processing. A single, reliable interface is needed.

Decision​

We will implement a unified script architecture with a single entry point. A primary shell script, organize_media.sh, will serve as the sole public-facing interface for the entire media organization process. This script is responsible for orchestrating the execution of all helper scripts and internal logic in the correct, predefined order (e.g., Phase 1: mnamer, Phase 2: GuessIt fallback, Phase 3: cleanup).

All other scripts (e.g., rename_with_guessit_uv.py) are considered "private" implementation details and must not be called directly by users or automation. This simplifies the user experience and automation configuration down to a single, idempotent command.

Consequences​

Positive:

  • Simplicity & Reduced Error: Users and automation systems only need to know about one script, which dramatically reduces complexity and the chance of user error.
  • Robustness: The orchestrator script centralizes error handling, logging, and lock management for the entire workflow, ensuring the process runs reliably from start to finish.
  • Maintainability: The internal logic and helper scripts can be refactored or replaced without affecting how the process is called, as long as the entry point script's interface remains stable.

Negative:

  • Reduced Granularity: Users cannot easily run just one specific phase of the process (e.g., only run the GuessIt fallback) through the primary interface. This is an intentional trade-off for simplicity.
  • Single Point of Failure: A bug in the main orchestrator script could prevent the entire process from running.

Mitigation:

  • Debug Flags: For debugging or special cases, the main script can accept hidden flags or arguments to run specific phases (e.g., organize_media.sh --phase=cleanup). This functionality should be reserved for development and not used in production automation.
  • Comprehensive Testing: The main orchestrator script must have a dedicated test script (test_mnamer.sh) to ensure its logic is correct and that it handles failures in sub-scripts gracefully.