talos

talos handles meter provisioning and hardware registration workflows.

Responsibilities

• Meter onboarding/provisioning flows.
• Hardware registration lifecycle.
• Vendor-specific meter integration behavior.
• Support for CALIN meter APIs (v1 and v2).

Ownership boundaries

• Owns provisioning workflows and hardware enrollment state transitions.
• Does not own broad operator API surfaces beyond provisioning needs.
• Coordinates with tiamat for user-facing orchestration and with shared libraries for reusable validation logic.

Interfaces

• Exposes provisioning endpoints/jobs and reports outcomes back to Tiamat (TIAMAT_API integration path).
• Uses two CALIN integration modes:
  • v1 browser automation (Puppeteer against CALIN web UI),
  • v2 API integration (REST-based).
• Includes metering hardware import processing plus debug screenshot endpoint for Puppeteer troubleshooting.

Runtime and operations

• Typically event-driven or command-driven from operational workflows.
• Operational focus is idempotency, retry behavior, and deterministic provisioning status.
• Monitoring focus: provisioning success rate, vendor API latency/failures, duplicate registration attempts.

Failure and edge cases

• Designed to support additional meter vendors over time.
• CALIN v1 UI automation is brittle by nature (captcha, element timing, EasyUI state); screenshot/debug artifacts are critical for diagnosis.
• Session concurrency limits and retry behavior must prevent overload while avoiding stuck provisioning queues.
• Upstream/downstream API mismatch in Talos-Tiamat callbacks can desynchronize provisioning state from operator-visible records.

Source of truth

• App-level provisioning flow details: apps/talos/README.md
• Build/serve contract: apps/talos/project.json
• Runtime configuration contract: apps/talos/.env.example