Skip to content
All work
21Carrier haulage visibility platform2026

CH RTV

Real-time GPS visibility for container haulage — a TCP gateway speaking the COBAN tracker protocol, geofence evaluation, and CMA-CGM integration behind five internal services.

5
Internal services
16
Route modules
11
Service modules
TCP
Device protocol
Role
Lead engineer
Year
2026
Status
Private
Type
Carrier haulage visibility platform

01Overview

CH RTV is a Carrier Haulage Real-Time Visibility platform. Trucks moving containers carry COBAN GPS units; the platform ingests their positions, ties each device to a transport order, evaluates geofences around facilities, and reports movement upstream to CMA-CGM.

The work that matters here is not the dashboard. It is the device gateway: COBAN trackers speak a terse binary-ish protocol over a raw TCP socket, log in with their own identifier, and expect commands back on the same connection. There is no REST API to call and no SDK to install — the connection is the interface.

Five services divide the problem: device-gateway owns the TCP listener, device login and packet parsing; tracking-service ingests and stores positions and evaluates geofences; asset-service owns orders, facilities and assignments; integration-service shapes and delivers CMA-CGM payloads; admin-api handles authentication, aggregation, Swagger and hosting the dashboard.

02The problem

Container haulage visibility fails at the seam between hardware and business process. The tracker knows where it is but not which order it is serving. The order system knows the job but not where the truck is. Joining them is the product.

A tracker's TCP session is long-lived, unreliable and unauthenticated in any modern sense. Devices reconnect, replay, drop mid-packet, and send positions out of order. Treating that stream as if it were an HTTP endpoint produces a system that looks fine in testing and loses trucks in production.

Carrier integration adds a second constraint: CMA-CGM expects a specific payload shape on a specific cadence, and a platform that cannot prove what it sent, and when, has no answer during a dispute.

03Architecture

  1. 01

    device-gateway

    A raw TCP listener handling COBAN device login, packet parsing and outbound command dispatch. Kept deliberately separate from everything else, because the one component that must never block is the one holding thousands of open sockets.

  2. 02

    tracking-service

    Position ingest and storage, geofence evaluation against facility boundaries, and event forwarding when a vehicle enters or leaves one. Geofencing is where a raw position stream becomes an operational signal.

  3. 03

    asset-service

    Transport orders, facilities, device-to-order assignments and the supporting lookups. This is the layer that answers 'which truck is on which job', which is the join the rest of the system exists to make.

  4. 04

    integration-service

    CMA-CGM-facing configuration, payload shaping and delivery paths. Option 1 is implemented; Option 2 is a stub with no S3PWEB integration behind it, and is documented as a stub rather than described as support.

  5. 05

    admin-api and dashboard

    JWT admin authentication with username-or-email login and SMTP-delivered OTP password reset, rate limiting, request validation, internal service isolation, Swagger, and a Tailwind dashboard covering tracking, alerts, reports and integration mode.

04Key decisions

Decision 01

The TCP gateway is its own service

Device ingestion has a completely different failure profile from a CRUD API: thousands of idle sockets, partial frames, reconnect storms. Folding it into the admin API would mean one slow database query stalls packet parsing for every tracker on the network.

Decision 02

Documenting the stub as a stub

Integration Option 2 is a non-functional path. It would have been easy to describe it as supported and quietly return success. The README, the audit report and this case study all say it is a stub, because the cost of discovering that during a carrier onboarding is far higher than the cost of saying so now.

Decision 03

Vanilla dashboard, no framework

The operator console is HTML, Tailwind and plain JavaScript served by admin-api. It is a handful of screens watched on a warehouse monitor; a build pipeline and a component framework would have added dependencies and deployment steps without adding anything a dispatcher can see.

Decision 04

Proprietary, and explicit about it

The repository carries a licence, a notice and a contribution policy stating it is not open source. Ambiguous licensing on client work is a liability, not a neutral default.

05Stack

  • Node.js
  • MySQL
  • TCP sockets
  • COBAN protocol
  • JWT
  • Tailwind CSS
  • Swagger