Skip to content
Case 05 · 8 min read

Case 05 · Logistics · AWS · React Native

TIRGPT — freight across borders, through 24 enforced states.

Role
Led the Order service · wrote most of the mobile app · worked across Auth, Driver and Provider
Stack
Node.js · Express · DynamoDB · EventBridge · SQS · AWS CDK · React Native (Expo) · AWS IoT Core
Scale
Per-country pricing · 7 roles and 41 permissions · iOS and Android
Result
24 / order states, no skipping

A cross-border trucking marketplace where every order moves through 24 enforced states and every driver's phone keeps reporting, even when a border drops the signal.

241
states in the order lifecycle
74%2
of the Order service's surviving code
413
permissions across 7 roles
1,0004
GPS points buffered offline

01 — The problem

Freight coordinated by phone

International TIR trucking runs on phone calls and brokers. Shippers can't see where their cargo is, trucks often drive home empty, and every border adds paperwork and delay.

TIRGPT is a two-sided marketplace for that work. Shippers post cargo orders. Drivers get batched offers, negotiate, accept, and then run the load through pickup, documents, loading, customs and delivery while their phone streams GPS. There is no AI in the product; the "GPT" in the name is branding.

02 — What I built

The order engine, the app, and the services between

The platform is a set of Node.js microservices — Auth, Order, Driver, Provider, Geo and Notification — that talk over authenticated REST and a shared EventBridge bus feeding SQS queues. The client's lead engineer wrote the shared service template, with its container hosting, logging and metrics. I deployed my services onto it and extended their CDK resource stacks.

I led the Order service: about 100 of its 197 commits and roughly 74% of the surviving code. I wrote most of the mobile app, one React Native app for both shippers and drivers: 44 of 51 commits and about 82% of the code. I also worked across the other services.

  1. Auth: moved roles from hardcoded checks to the database (7 roles, 41 permissions) and added four indexes to its single-table design, one per deploy
  2. Provider: provider ratings now update from the order-completed event
  3. Driver: a new truck class and face-photo identity documents
  4. Tooling: a local API gateway and a WebSocket harness that opens up to 1,000 connections

03 — The hard part

24 states, and no skipping

I modelled the order as an explicit state machine with 24 states, from verification through matching, offers, pickup, loading, customs and delivery. Each state lists the states allowed to precede it, so no client can jump a step. Customs is optional, because not every route crosses a border. Completion is only reachable through an endpoint where both sides confirm, never through a plain status update.

Creating an order returns at once in a pending state. The Geo service measures the route distance in each country and emits an event. The Order service then prices it — kilometres × base rate × country coefficient, per country, then truck, cargo and urgency coefficients — and the order becomes live, scheduled or failed with a reason the app can show. Rates live in configuration, so operations can re-price without a deploy.

Editing an order raises a problem: drivers may hold offers on the old terms. Every order carries a version timestamp and every offer records the version it was made against. An edit moves the version forward, expires the older offers with a reason and restarts matching, including drivers who turned down the old terms. I wrote up sequential and timestamp versioning before choosing timestamps.

04 — Time as an input

Offers that expire on time, without a scan

Offers expire in two windows: a short one for the driver to respond and a decision window for the shipper to approve. Scanning the offers table to find them would get slower as it grew. Instead, each live offer is indexed under a three-minute time bucket. A scheduled Lambda reads only the buckets around "now" and puts each expiring offer on SQS with a per-message delay, capped at 900 seconds, so it fires close to the exact time.

Matching goes out in batches whose size lives in configuration. The cursor and contact count are stored on the order itself, so any stateless instance can pick matching up where another left off. If nobody accepts before a global timeout, the order ends as no drivers available or expired.

Orders booked more than 24 hours ahead wait in a scheduled state. A one-time EventBridge Scheduler trigger wakes each one, the service re-checks the shipper, resets the version timestamp and flips the status with a conditional write. A 15-minute backup sweep catches any order whose trigger failed to create, and bookings are capped 30 days out by default.

05 — From the road

GPS that survives a border crossing

GPS tracking began as a teammate's prototype. I integrated it into the main app and finished it. The driver's phone streams location in the background over MQTT with TLS to AWS IoT Core: every 30 seconds on an order, every 2 minutes when idle, and not at all when the driver goes offline. Points under 10 metres of movement are dropped, but one is always sent after 3 minutes, and a lock stops two sends from overlapping.

Signal drops out at border crossings, so every point is buffered on the phone first, up to 1,000 per driver and order, compacted to 500 when full. When the network returns, the buffer flushes in 100-point chunks and retries every 30 seconds.

Live screens run on one authenticated WebSocket. It fetches a fresh token on every connect, reconnects with capped exponential backoff and a cool-off, and treats a normal close differently from a dropped one. Push notifications share its redirect logic. Cargo and truck names arrive from the server translated into five languages.

06 — What I'd change

Next

The unified order queue I built has no dead-letter queue. The Driver, Provider and Notification queues do. I would add one, so a message that keeps failing is parked and visible instead of retried quietly.

Version checks happen in application code, and conditional writes guard only a few transitions, such as scheduled activation. Double-processing during expiry and matching is held off by a per-instance guard with a 30-second cleanup. I would move every state transition onto conditional writes, so correctness doesn't depend on one instance's memory.

Notes

  1. Each state has a whitelist of allowed predecessors.
  2. Line attribution in the Order service repository; about 100 of its 197 commits.
  3. Database-driven access control in the Auth service: 7 roles, 41 permissions, 111 role-to-permission mappings.
  4. Per driver and order; compacted to 500 when full and flushed in 100-point chunks when the phone reconnects.

Ask my portfolio