Skip to main content

ADR 0001: Separate telematics gateway process

Status​

Accepted

Context​

Teltonika devices open long-lived TCP connections and exchange binary frames (IMEI handshake, Codec 8 AVL batches, acknowledgments). The main OmniTrack server is an Express HTTP application with Socket.IO, sessions, and JSON APIs.

Decision​

Run binary TCP protocol handling in a dedicated Node process (services/telematics-gateway), not inside the same process as server.ts.

Consequences​

Positive​

  • Isolation: a malformed packet or parser bug cannot take down the HTTP API used by users.
  • Scaling: TCP gateways can be scaled horizontally behind a load balancer (with sticky sessions — see scaling.md); HTTP API scales independently.
  • Resource control: different memory/CPU limits and restart policies for gateway vs API.

Negative​

  • Deployment complexity: one more service to run (Docker Compose service, systemd unit, or K8s Deployment).
  • Shared database: both processes use DATABASE_URL; migrations/schema live in one place (ensureSchema in server.ts).

Alternatives considered​

  1. Single process: TCP + Express in one Node — rejected due to shared event loop and blast radius.
  2. Separate language (Rust/Go) — deferred; TypeScript keeps one stack; can revisit for hot paths.