HHA Workspace · Reply to "One route, three platforms"
From the HHA Workspace CTO to the Synchron CTO — One route, three platforms: the Workspace's view, what we add, and what we still need to know — October 6, 2026, 4:43 PM ET
Your brief sets out a mission we share: one place where a heavy-haul customer plans a trip and buys what it needs to run it legally, with each company doing what it does best. This article is the Workspace's answer. It shows the flow as our customers will live it, the tools the Workspace already brings, the limitations we know about, nine proposals that would make the design stronger, and the questions we still need you to answer.
1. Mission, vision and goals: where we stand
We agree with the mission, the vision and all eight principles. Two of them matter most to the Workspace. "One owner per fact" means the Workspace owns the customer, the trip, the product choice and the price, and never keeps a rival copy of your orders or payments. "Server to server" matches how the Workspace is built: the browser never talks to Synchron, and a return from Checkout is only a waiting page.
Your goals measure the integration from Synchron's side. We propose four measures from the customer's side, so all three teams see the same picture.
| Goal we propose | Measure |
|---|---|
| Every Workspace permit gets a route offer | Share of read permits with a route token, now 90% (3,447 of 3,825); target 98% |
| Express means fast | Share of Express purchases released automatically, read from the release field each week |
| The customer always knows where a route is | No route item without a visible state for more than 1 minute after any event |
| Files arrive with the route | GPX and Hummer files on 100% of delivered purchased routes; today on 0% of Workspace permits |
2. The Workspace in one minute
The Workspace is a Next.js 16 server application with a Supabase Postgres database and an Amazon S3 bucket, running on a managed server at heavyhaulgbt.com. Brokers, carrier dispatchers, pilot companies, truck drivers and pilot car drivers each have their own dashboard and trip view, and a trip is visible only to its participants. It holds 960 trips, 957 of them imported from Synchron, along with 3,825 permits, 3,965 documents, 1,379 people and 1,332 companies. Of the 167 carriers, 162 have both a DOT and an MC number, and 165 already carry their Synchron carrier token.
3. The route journey, as the customer will see it
Route purchase in nine steps. The Workspace starts and ends the journey; Synchron owns the order, the payment check and the release; Stripe takes the money; the Factory produces the files.
The journey starts when a dispatcher drops permits into a trip. The Factory reads each one, and the Workspace prices its route: Express at $1.99 when the route token has been used 3 or more times, Extended at $10.00 otherwise. On the permit the customer sees "Express Route available · not purchased" and a "Purchase route" button. A customer with a prepaid credit sees "Use 1 credit" instead, and that route goes through as its own $0 purchase.
Card routes collect in the trip's cart. The cart's review names the trip number, the cities and states it runs between, the truck and the carrier, so nobody pays for the wrong trip. From there the Workspace server sends the purchase to you, the customer pays on your Stripe page, and the Workspace shows a waiting page until your purchase.paid arrives. The permit then reads "Route purchased · being prepared". When route.completed arrives, the route's links appear, and the GPX and Hummer files follow once the Factory has made them.
Customers see Workspace wording, not system states. We propose this mapping, so both support teams use the same words.
| Synchron item status | What the Workspace customer sees |
|---|---|
| pending | Awaiting payment |
| paid | Route purchased · being prepared |
| in_progress | Being prepared by the routing team |
| completed | Route ready (files following until GPX and Hummer arrive) |
| fulfillment_failed | Delayed — our team has been alerted |
| expired | Checkout expired — buy again |
| refunded | Refunded |
4. Tools and abilities the Workspace brings
- Durable permit processing. Every permit file becomes a job in a Postgres queue with a lease, a revision and a retry schedule. A replaced file can never overwrite a newer result.
- A purchase ledger. Carts, purchases, items and an event trail, each with a fixed price snapshot. One function alone may mark a purchase paid, and only from a verified confirmation.
- A signed receiver. Already verifies your scheme: the timestamp, a dot and the raw body, within five minutes, with event deduplication.
- A full rehearsal. A mock of your API imitates checkout, callbacks, failures and reconciliation, so the buying screens can be tested before your staging exists.
- Admin reconciliation. A purchases page and an internal reconciliation endpoint, ready to compare against your route history.
- Route protection. Unpaid routes on Workspace trips stay hidden; routes on your permits are always included and never priced.
- Profiles built from permits. Carrier, truck and trailer details learned from every permit, matched by Synchron token, MC, DOT or VIN. These can fill purchase data with real values instead of placeholders.
- People on every trip. Invitations and automatic team rules, so the right dispatcher, driver and office staff see each purchased route.
- An AI assistant on every trip, served by the Factory, that answers questions about the permits.
5. Limitations, stated plainly
These are the gaps on our side that touch this integration. Each has a fix and an estimate.
| Limitation today | Effect on the integration | Fix and estimate |
|---|---|---|
| Trip numbers are random across 100–999 million and checked only against trips that still exist | A number could be reused, and about 1 in 9 would fall outside your production range | Permanent register, correct ranges, new number per carrier: 0.5 day |
| No use counts from the Factory | Every route prices as Extended | Factory request F2 |
| No route text, only a route description | Purchases cannot carry route text | Factory request F3 |
| GPX and Hummer never reach the Workspace | Purchased routes would arrive without files | Proposal P4 below |
| The Workspace lives at heavyhaulgbt.com | Your callbacks and return pages are set for heavyhaulagent.com | Question 1 |
| No Workspace staging environment | Your staging has nothing to call | Needs a hosting decision |
| The permit retry job is not scheduled | A permit whose first reading fails waits until someone retries it, delaying its route offer | Schedule the job: 1–2 hours |
| Purchasing is limited to admins and moderators | Customers cannot buy until launch, by design | Switch it on at launch |
6. Nine proposals that would make the design stronger
- A release-eligibility check before purchase. Your automatic release and our Express rule use different data, so a customer can pay for Express and still wait for staff. If your API could answer, per item, "would this release automatically?", the Workspace could sell Express only when it will be fast. Both rules could then converge on real behavior.
- The permit travels with Extended items. Your routing team needs the permit to prepare a new route. The Workspace can attach it as a 24-hour link with its SHA-256, exactly as permit orders will.
- Our permit ID in every item event. Purchases already send hha_permit_id. Echoing it in item.in_progress and route.completed lets the Workspace place the route without a lookup.
- A signed files-ready message from the Factory. GPX and Hummer files are the last step of the journey and today have no path to the Workspace. We propose the Factory send the Workspace a signed message, using the same scheme as yours, carrying the permit ID and both file links.
- Send Synchron's own tokens when we have them. The Workspace holds Synchron tokens for 165 carriers and for imported people. Sending them would let you match existing records instead of creating duplicates.
- Fewer placeholders from real profiles. The Workspace's permit-derived profiles already hold many trucks, trailers and VINs. We will fill purchase data from them first, so 1111 and XXXXX appear only when nothing is known.
- Six more test scenarios. Two buyers buy the same route at once. A carrier with a DOT but no MC. An Extended route for a permit with no token. A credit route refunded. A purchase attempted on an 8-digit imported order, which should be refused. The Workspace answers 500, then recovers.
- A weekly release report for all three teams. The share of Express routes released automatically, from the release field. It tells us when to change the Express threshold.
- One wording list for support. The status mapping in section 3, agreed by both support teams, so a customer hears the same words from HHA and from Synchron.
7. What the Workspace will build, and when
Our share of route purchase is about five to six working days, inside your phases 0 and 1. That covers the order-number register (half a day), the live purchase client with signing and retries (one to one and a half days), and the callback receiver with versions and background processing (one day). It also covers customer states (half a day), complete purchase data (half a day), credit purchases (half a day), daily reconciliation (half a day) and the refund path for support (two hours). Permit ordering follows in your phase 4 and takes one to one and a half days. It replaces our CVV step with your 3-D Secure link, and adds plates, plate states, truck axle count, trailer type and length, and axle spacing and weights.
8. Questions for you
Please type each answer in its box, then save the page or print it to PDF and send it back.
Addresses and access
Which web address receives your callbacks? The Workspace runs on heavyhaulgbt.com and heavyhaulagent.com is the Factory's. Could callbacks and Checkout return pages use a Workspace subdomain such as app.heavyhaulagent.com, with heavyhaulgbt.com also allowed in staging while we move?
Will callbacks come from fixed addresses? Or should the signature be the only check on our side?
Does the rate limit count status checks? Do our GET status calls and daily reconciliation count toward 60 requests a minute?
Can we build against the contract early? Where will the contract repository live, and can we start from the OpenAPI file and sample events before staging?
Route data
Would you offer a release-eligibility check? Proposal 1: per item, would this route release automatically if bought now?
Should Extended items carry the permit? Proposal 2: a 24-hour link with SHA-256 on each item.
Does the Factory call permittoken for Workspace permits today? Those permits have no Synchron order. If it does, what happens, and how do we avoid the check running twice after a purchase?
Is the route description enough as route text? Or must it match the texts the Factory sends to permittoken exactly?
What are the route_urls in your sample request? Do you mean the Google Maps links the Factory matched from the token, and in what format?
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 item events carry our permit ID? Proposal 3: hha_permit_id in item.in_progress and route.completed.
Buyers, carriers and records
Can drivers and shippers buy? The Workspace can allow them. Your purchaser roles are carrier user, broker, pilot and HHA admin. Add the two, or should we block them?
Can a carrier with a DOT but no MC buy? MC can never be a placeholder. Intrastate and private carriers may have none.
Should we send Synchron tokens for carriers and people? Proposal 5: 165 carriers already carry yours.
Are our token formats accepted? Our purchase reference is hhp_ followed by 20 characters; route request IDs are UUIDs.
Who decides that a pending purchase expired? Should the Workspace wait for purchase.expired rather than expire on its own clock?
Permits and Front Desk
Will permit orders send permit events? In phase 4, an event per 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 order keep the Workspace trip number?
Can we read route status on imported trips? Read-only use of GET routes for 8-digit orders, with no purchase.
Which carrier is excluded from automatic release? Its name and DOT, so Nash can decide what to do.
Which header carries the API version? And in what format?
9. Decisions still with Nash
Some choices belong to Nash, not 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 accepts brokers, pilots and HHA admins. He also needs to confirm the $100 ceiling per route and name the address for conflict alerts. He must settle the "HHA ROUTES" statement suffix within Stripe's 22 characters, and decide on the excluded carrier once question 20 is answered. Finally, he must decide whether axle spacing and weights join the permit form before phase 4. The callback address follows from question 1.