Skip to main content

System Contracts (APIs / Events / Ports)

This page defines the interfaces that keep the whole architecture stable as you evolve products.

Rule: every integration point must be versioned, logged, and testable.

0) Contract map (high level)​

flowchart LR
  CRM["CRM/PM (System-of-Record)" ]
  REG["Unified Device Registry\n(in CRM)"]
  AUTO["Automation Runner (OpenClaw)"]
  KB["Docusaurus KB"]
  NOTIF["Notifications Engine"]
  MSG["Messaging Channels\nWhatsApp/Email/etc"]
  CS["ChirpStack"]
  RFIDBE["RFID Backend"]

  CRM --> REG
  REG --> AUTO
  AUTO --> KB
  AUTO --> NOTIF --> MSG

  REG --> CS
  REG --> RFIDBE

  RFIDBE --> NOTIF
  CS --> NOTIF

1) CRM/PM → Unified Device Registry (internal)​

  • customer_id (e.g. cus_...)
  • site_id (e.g. site_...)
  • deployment_id (e.g. dep_...)
  • device_id (e.g. dev_...) — single ID used everywhere
  • gateway_id (e.g. gw_...)

Registry fields (minimum)​

  • device_id
  • product_code + product_version
  • role: gateway | sensor | station | controller
  • desired_state: target config (JSON)
  • observed_state: last known status (JSON)
  • external_refs:
    • chirpstack.dev_eui / chirpstack.device_id
    • rfid.station_id / rfid.mac

2) Unified Device Registry → ChirpStack​

Purpose​

  • Ensure ChirpStack device registry aligns with CRM deployments.

Contract styles (pick one)​

A) Push model (CRM is source): automation creates/updates ChirpStack entities. B) Link model (ChirpStack is source): CRM stores refs and reads status.

Recommendation: Push for provisioning, link/read for telemetry.

Key items to standardize​

  • Join keys: dev_eui, join_eui, app_key handling (secret management)
  • Region plan: AS923 params
  • Gateway packet forwarder config templates

3) Unified Device Registry → RFID Backend​

Purpose​

  • Map stations to sites/lines/deployments; keep a single device identity.

Required endpoints (already partially exist)​

  • POST /api/v1/stations/claim → returns station token + config
  • POST /api/v1/events → idempotent ingest
  • GET /api/v1/stations/:id/status
  • POST /api/v1/stations/:id/map (assign to site/line)

4) CRM → Automation (Execution Spec)​

Purpose​

CRM emits a versioned spec describing what should be provisioned/deployed/verified.

Suggested shape (v1)​

  • spec_version: 1
  • deployment_id
  • product_code + product_version
  • targets: gateways/devices/stations
  • actions:
    • provision_vm (Proxmox)
    • deploy_compose_stack (ChirpStack/RFID/CRM)
    • configure_gateway
    • run_health_checks
    • open_ticket_on_failure

Automation must write back​

  • automation_run_id
  • status timeline
  • links to logs/artifacts

5) Automation → KB​

Purpose​

Every run produces durable documentation:

  • runbook execution logs
  • postmortems
  • configuration snapshots (non-secret)

Deliverables​

  • docs/projects/<project>/runs/<date>/...
  • or a structured note template with links.

6) Notifications Engine → Messaging​

Purpose​

Route alerts to the right channel with escalation.

Inputs​

  • events from: automation runs, ChirpStack health, RFID backend health

Output channels​

  • WhatsApp (primary today)
  • Email (optional)
  • Slack/Discord (team optional)

7) Ports (baseline)​

  • ChirpStack gateway bridge: UDP/1700 (site LAN)
  • RFID backend API: HTTP/HTTPS (site LAN)
  • Central ops APIs (SPM/Dashboards): HTTP/HTTPS

8) Deployment mode notes (based on chosen options)​

  • Station→backend: LAN only (do not expose station ingest to internet)
  • ChirpStack: hybrid
    • local per site for resilience (authoritative)
    • central is read-only for fleet visibility/backup/analytics (sync/export contract needed)
  • Dashboards: both
    • Docusaurus: docs/runbooks
    • A2UI: live operational cockpit

Next questions (to finalize contracts)​

  1. Where do you want secrets to live? (1Password / env files / vault)
  2. Preferred event bus? (Postgres outbox only / MQTT / NATS / Redis streams)