HHA Workspace · Route integration
From the HHA Workspace CTO to the Synchron CTO — Inside the HHA Workspace: how it runs today and what it brings to route purchase — October 6, 2026, 4:33 PM ET
Your brief described the HHA Workspace from what HHA had told you. This article fills in the Workspace from the inside: what it runs today, what it already built for buying routes, what its own data says about your findings, and what we will build next. It ends with the questions we could not answer ourselves.
What the Workspace is
The Workspace is the application our customers sign in to. It is a Next.js 16 server application backed by a Supabase Postgres database and an Amazon S3 bucket, running on a managed server at heavyhaulgbt.com. People sign in with an email code or with Google, behind reCAPTCHA. The database has grown through 53 migrations.
It serves five kinds of user, each with its own dashboard and trip view: freight brokers, carrier dispatchers, pilot companies, carrier truck drivers and pilot car drivers. Someone who works for several companies switches between workspaces, and carrier companies can also give office staff safety, permit, accounting or fleet roles. A trip is visible only to its participants. People join by invitation or automatically, through personal and company rules that add a person's team whenever they join a trip.
Today the Workspace holds 960 trips. 957 were imported from Synchron and 3 were created in the Workspace. Those trips hold 3,825 permits and 3,965 documents. There are 1,379 people, most of them imported and not yet signed in, and 1,332 companies, 167 of them carriers. 162 of those carriers have both a DOT and an MC number, and 165 already carry their Synchron carrier token.
The life of a permit
A carrier dispatcher starts a trip by dropping in the rate confirmation and the permits. The trip opens at once, and the reading happens in the background. Every permit file becomes a job in a Postgres queue that carries a lease, a revision number and a retry schedule. The job sends the file to the Factory's permit reader, which returns the state, permit number, dates, dimensions, weight and route token. The Workspace saves those, checks the permit against the trip and copies the whole trip to the Factory, where the AI assistant uses it.
That check produces the Workspace's alerts. A permit whose width, height, length or weight is smaller than the trip's is flagged on every trip, a change the Factory team made today. Expired and expiring permits are flagged too. Alert emails are switched off for now. Synchron permits reach the Workspace only through our import scripts, which read your carrier and order records with our API key.
How the Workspace prices and protects routes
For every permit on a trip created in the Workspace, the Workspace prices the route. If the route token has been used 3 or more times, the route is Express at $1.99. Otherwise it is Extended at $10.00. Routes on permits that came from Synchron are included and never priced. On a Workspace trip, the route files stay hidden until the route is bought.
The Workspace asks the Factory how many times each token was used. The Factory does not answer yet, so today every route prices as Extended. That is the first thing we need from the Factory.
What is already built for buying
Much of the buying side exists. Each trip has one cart, stored in the database. Purchases, their items and an event trail are stored with a fixed price snapshot. Only one function in the Workspace can mark a purchase paid, and it accepts only a verified confirmation. The page a customer returns to after checkout only reads and waits, which is exactly the rule your brief asks for.
A callback receiver already listens at /api/webhooks/synchron and checks the same HMAC signature you specified: the timestamp, a dot and the raw body, within five minutes. A mock adapter imitates your checkout, callbacks and reconciliation, so the whole flow can be rehearsed. Prepaid credits come from the customer's plan and are spent from the permit's own button, never through the card cart. Until launch, only admin and moderator accounts can see Billing or buy anything.
What our data says about your brief
We checked your "Code shows" findings against the Workspace's own records. You are right that Synchron sends no callbacks to the Workspace. Our receiver has never received an event, relayed or direct. You are also right that the literal "route_token" problem lies upstream. Of our 3,825 permits, 3,447 carry a numeric token, one carries a workspace token, 377 carry none, and not one holds the field name as text.
Two statements in the brief need correcting. GPX and Hummer files do not reach the Workspace today. We have a place for both on every permit, but none of the 3,825 has ever received one, so delivering them for purchased routes is new work. The Workspace also has no route text. The permit reader returns a route description, not the texts the Factory sends to permittoken, so purchases cannot carry route text until the Factory adds it.
What we will build, and when
For route purchase, our side needs about five to six working days, which fits inside your phases 0 and 1. The order-number register comes first. Today our trip numbers are random 9-digit numbers drawn from the whole 100 million to 999 million range and checked only against trips that still exist. We will keep a permanent register, draw production numbers from 200 million up and staging numbers from your staging range, and issue a new order number whenever the carrier changes. That takes half a day.
Next comes the live connection to your purchase API, replacing the mock: signed requests, the purchase token as the idempotency key, a request ID, retries on server errors and none on rejected requests. That takes one to one and a half days. The callback receiver needs a day to take your new event names and version numbers, answer at once and work in the background.
Smaller pieces follow. Mapping your states to what customers see, including "Being prepared", "Delayed" and "Expired", takes half a day. Sending the purchaser's role, the driver, trip data and placeholder fields takes another half day. Sending credit routes as separate $0 purchases takes half a day, and so does a daily comparison with your route history. A written refund path for support takes two hours. Permit ordering comes later, in your phase 4. Our two-step dialog was built around a CVV step that you have replaced with 3-D Secure. Our form also still lacks license plates, plate states, the truck's axle count, the trailer's type and length, and axle spacing and weights. That is one to one and a half days when the time comes.
What the Workspace needs from the Factory
Four things, all owned by the Factory team. We need use counts, so routes stop defaulting to Extended. We need route text next to every token, so purchases can carry it to you. We need the GPX file and Hummer link sent back to the Workspace for each permit, keyed by our permit ID. And we need the Factory to confirm whether it relays anything to the Workspace, because nothing has arrived.
Questions for you
These are facts we could not settle from our side. Please type your answer in the box under each one, then save the page or print it to PDF and send it back.
Which web address receives your callbacks? The Workspace runs on heavyhaulgbt.com, while heavyhaulagent.com is the Factory's address. Nash chose heavyhaulagent.com for this integration. Could the callback and the Checkout return pages live on a Workspace subdomain such as app.heavyhaulagent.com, and could staging also accept heavyhaulgbt.com while we move?
Does the routing team need the permit to prepare an Extended route? If so, should each route item carry the permit PDF as a 24-hour link with its SHA-256, the same way documents travel for permit orders?
Does the Factory already call permittoken for Workspace permits? Those permits have no Synchron order. If it does, what does Synchron do with the call today, and how do we stop the same check running twice once Synchron runs it itself after a purchase?
Is the Factory's route description enough as route text? Or must it match, word for word, the texts the Factory sends to permittoken?
Can drivers and shippers buy? In the Workspace, a driver or a shipper on the trip may be allowed to buy a route. Your purchaser roles are carrier user, broker, pilot and HHA admin. Should those two be added, or should the Workspace block them?
Can a permit with no route token be sold as Extended? 377 Workspace permits have none. Would the routing team prepare those routes from the permit alone?
Will permit orders send permit events? When HHA orders permits through the new API, will Synchron send an event for each state item with the permit PDF, number, dates and state?
What happens to the permit requests we email today? Do they go through Front Desk, and does the resulting order keep the Workspace trip number anywhere?
Which header carries the API version? And in what format?
Does the rate limit count our status checks? Do the Workspace's GET status calls and its daily reconciliation count toward 60 requests a minute?
Will callbacks come from fixed addresses? Or should the signature be the only check on our side?
Which carrier is excluded from automatic release? Its name and DOT number, so Nash can decide whether to keep, change or remove the exclusion.
Can we read routes on imported trips? Could the Workspace call the new GET routes endpoint for 8-digit orders, read-only, to show route status on trips imported from Synchron?
Are our token formats accepted as they are? Our purchase reference is hhp_ followed by 20 characters, and our route request IDs are UUIDs.
Who decides that a pending purchase has expired? The Workspace also expires pending purchases on its own clock. Should it wait for your purchase.expired event so the two systems never disagree?
Can we build against the contract before staging exists? Where will the contract repository live, and can we start from the OpenAPI file and sample events?
Decisions still with Nash
A few choices belong to Nash rather than to either engineering team. The first is who may buy. The Workspace lets any participant buy, limited to admins and moderators until launch, and your design already accepts brokers, pilots and HHA admins. He also needs to confirm the $100 ceiling per route and name the address that receives conflict alerts. He must settle the "HHA ROUTES" statement suffix within Stripe's 22 characters, and decide what to do about the carrier excluded from automatic release once he knows which it is. Finally, he must decide whether axle spacing and weights join the permit form before phase 4. The web address for callbacks waits on the first question above.