tiamat

tiamat is the main operations API in the nxt-backend monorepo.

Responsibilities

• Primary REST and WebSocket API consumed by NXT dashboards.
• Meter management workflows (device messages, install sessions, directive batches).
• Grid infrastructure APIs (grids, DCUs, MPPTs).
• Payment workflows (orders, wallets, payouts, Flutterwave integration).
• Organization/user administration for multi-tenant operation.

Ownership boundaries

• Owns synchronous API contracts and request-time orchestration.
• Does not own long-running automation; delegates async workflows to loch.
• Consumes shared modules for auth, cross-cutting guards, and utility behavior.

Interfaces

• Exposes REST and Socket.IO surfaces used by operations dashboards and internal services.
• Handles LoRaWAN webhook ingress (chirpstack module) into device-message pipelines.
• Integrates with Talos/Yeti/Loch via internal APIs for provisioning, telemetry, and async processing handoff.
• Large module surface includes accounts, agents, grids, meters, wallets, orders, payouts, notifications, Jira, Telegram, USSD, and analytics.

Runtime and operations

• Designed for low-latency request/response workflows.
• Runtime health depends on upstream data stores and external integration availability.
• Monitoring focus: API latency/error rates, auth failures, and integration call failure trends.

Failure and edge cases

• External integration outages (Flutterwave, SendGrid, ChirpStack, Make, Flow XO) should degrade gracefully without full API collapse.
• Device-message and meter-interaction flows must handle retry/reconciliation to avoid silent command loss.
• Any auth/session misconfiguration (Supabase URL/keys/JWT secret) has platform-wide impact on dashboard access and machine-to-machine calls.

Source of truth

• App-level architecture and module map: apps/tiamat/README.md
• Build/serve contract: apps/tiamat/project.json
• Runtime configuration contract: apps/tiamat/.env.example