loch

loch runs background jobs and asynchronous integrations for the backend platform.

Responsibilities

• Scheduled and queue-driven jobs.
• Automation tasks (lifeline credit top-ups, revenue updates, autopilot triggers).
• Notification dispatch across email, SMS, and Telegram.
• Third-party integration tasks (Make.com, weather feeds, sunrise/sunset schedules, EpiCollect processing).
• MQTT subscriptions for Victron telemetry streams.

Ownership boundaries

• Owns asynchronous execution, retries, and schedule-based workflows.
• Does not own primary synchronous API contracts (owned by tiamat).
• Coordinates with yeti when async workflows depend on telemetry-derived state.

Interfaces

• Exposes selective operational endpoints (for example EpiCollect ingestion, notification routes, autopilot/test, PD Hero trigger).
• Pulls/patches against Tiamat APIs for payout/revenue/automation workflows.
• Pushes side effects into comms channels and external workflow engines (Make.com, Flow XO, SendGrid, Africa's Talking, Telegram).

Runtime and operations

• Worker runtime prioritizes reliability over request latency.
• Schedules, queue depth, and retry policies are core operational controls.
• Monitoring focus: job lag, retry counts, dead-letter rates, and notification delivery outcomes.

Failure and edge cases

• Cron-driven flows are mostly production-gated by NXT_ENV; misconfigured environment can silently disable critical automation.
• Multi-provider notification and automation paths require bounded retries and duplicate-protection for financial/operational side effects.
• MQTT/Victron connectivity issues can degrade downstream automation quality; fallback behavior must avoid cascading failures.

Source of truth

• App-level job/module inventory: apps/loch/README.md
• Build/serve contract: apps/loch/project.json
• Runtime configuration contract: apps/loch/.env.example