docs: add section-by-section comments — __main__.py

ns8_backup_monitor/__main__.py

@@ -1,10 +1,20 @@
 #!/usr/bin/env python3
-"""
-__main__.py - Entry point for ns8-backup-monitor.
+"""Entry point for the ns8-backup-monitor service.
 
-Usage:
-    python3 -m ns8_backup_monitor
-    python3 -m ns8_backup_monitor --config /etc/ns8-backup-monitor/config.yml
+This module is executed when the package is run as:
+    python3 -m ns8_backup_monitor [--config PATH]
+
+Start-up sequence
+-----------------
+1. Parse the single optional CLI argument (--config).
+2. Load and validate the YAML configuration file.
+3. Initialise logging (stdout + optional rotating file).
+4. Hand control to receiver.run_server(), which blocks forever
+   serving the Alertmanager webhook endpoint.
+
+The process is designed to be managed by systemd (see
+deploy/ns8-backup-monitor.service); stdout/stderr are captured
+by journald when StandardOutput=journal is set in the unit.
 """
 
 import argparse
@@ -15,25 +25,47 @@ from .receiver import run_server
 
 
 def main():
+    """Parse arguments, load config, set up logging, start HTTP server."""
+
+    # ---------------------------------------------------------------------------
+    # CLI argument parsing
+    # ---------------------------------------------------------------------------
+    # Only a single argument is needed: the path to the YAML config file.
+    # When omitted, load_config() probes a list of well-known default paths.
     parser = argparse.ArgumentParser(
-        description="NS8 Backup Monitor - Alertmanager webhook receiver and correlator"
+        description="NS8 Backup Monitor — Alertmanager webhook receiver and correlator"
     )
     parser.add_argument(
         "--config", "-c",
         metavar="PATH",
-        help="Path to config.yml (default: auto-detect)",
+        help="Path to config.yml (default: auto-detect from known locations)",
         default=None,
     )
     args = parser.parse_args()
 
+    # ---------------------------------------------------------------------------
+    # Configuration loading
+    # ---------------------------------------------------------------------------
+    # Exit immediately with a clear message if the config file is missing.
+    # This prevents a confusing traceback on first-run misconfiguration.
     try:
         config = load_config(args.config)
     except FileNotFoundError as e:
         print(f"ERROR: {e}", file=sys.stderr)
         sys.exit(1)
 
+    # ---------------------------------------------------------------------------
+    # Logging setup
+    # ---------------------------------------------------------------------------
+    # Must be done before any module-level loggers are used.
+    # When logging.file is empty in config, output goes to stdout only
+    # (journald captures it via StandardOutput=journal in the systemd unit).
     setup_logging(config)
 
+    # ---------------------------------------------------------------------------
+    # Start HTTP server
+    # ---------------------------------------------------------------------------
+    # run_server() blocks indefinitely. Systemd handles restart on failure.
     run_server(config)