Skip to main content

Architecture: web app vs telematics gateway

High-level diagram​

flowchart LR
  subgraph devices [Trackers]
    T[Teltonika_TCP]
  end
  subgraph gw [telematics-gateway]
    TCP[TCP_listener]
    P[Codec8_parser]
    M[Metrics_HTTP]
  end
  subgraph data [PostgreSQL]
    DP[device_positions]
    DO[device_online]
    DV[devices]
    DC[device_commands]
  end
  subgraph api [OmniTrack server.ts]
    HTTP[Express_API]
    UI[React_UI]
  end
  T --> TCP --> P --> DP
  P --> DO
  P --> DV
  HTTP --> DC
  TCP --> M
  DP --> HTTP
  DO --> HTTP
  DV --> HTTP
  HTTP --> UI

Responsibilities​

server.ts (Express)​

  • HTTPS session auth, REST JSON APIs, Socket.IO for real-time UI.
  • Does not accept raw Teltonika TCP (by design: isolate binary protocol from HTTP attack surface and avoid blocking the event loop with long-lived sockets).

services/telematics-gateway​

  • Raw TCP server on configurable port (default 5027 — common Teltonika server port; override via env).
  • Codec 8 AVL decode, 4-byte big-endian acknowledgment (number of accepted records).
  • IMEI handshake: 2-byte length + ASCII IMEI → server responds 0x01 accept only if devices row exists (configurable).
  • Writes to device_positions, device_online, updates devices.last_ping.
  • Optional HTTP on METRICS_PORT for Prometheus-style counters (see scaling.md).

PostgreSQL​

  • devices remains the inventory master for IMEI.
  • New tables: device_positions (history), device_online (last fix), device_commands (queue), optional device_ingest_raw (debug).

Security notes​

  • Expose the TCP port only inside a VPN, site-to-site tunnel, or firewall allowlist for known SIM IP ranges. A public open tracker port will be probed and abused.
  • TLS is not typically terminated on Teltonika TCP binary streams; edge security is network segmentation, not HTTPS on port 5027.
  • Secrets: DATABASE_URL only on gateway host; never commit.

Phase 2+ (future)​

  • Codec 8 Extended / Codec 16: extend parser behind feature flags per device_model.
  • Codec 12 binary encode for outbound commands and parse for device responses on the live socket (see commands.md).
  • TimescaleDB or partitioned device_positions for very large volume.