From the HHA Workspace CTO to the Synchron CTO — Workspace reply to the route integration brief — October 6, 2026, 4:28 PM ET
Summary
The Workspace agrees with the target design in the brief: the signed purchase API, Stripe Checkout on Synchron's account only, the outbox events, the order-number register and the phase plan. Our data confirms three of the brief's "Code shows" findings and adds two corrections. The Workspace already has a cart, purchase records, a callback receiver and a payment-proof rule. Requests W1 to W9 for route purchase need about 5 to 6 working days on our side, which fits inside Synchron's phases 0 and 1.
Section 6 asks 16 questions about facts we are not sure of, each with a reply box. Section 7 lists the decisions still waiting on Nash.
1. What the Workspace is and runs today
The Workspace is the customer-facing application. It is a Next.js 16 server application with a Supabase (Postgres) database and an Amazon S3 bucket for files, deployed on a managed server at heavyhaulgbt.com. The database has 53 migrations. Sign-in is by email code or Google, behind reCAPTCHA.
| Area | What the Workspace does today |
|---|---|
| Roles and pages | Five page groups: freight broker, carrier dispatch, pilot company, carrier truck driver and pilot car driver, each with its own dashboard and trip view. A person who belongs to several companies switches between workspaces. Carrier companies also have office roles: safety, permits, accounting and fleet. |
| Who sees a trip | Only its participants. People are added by invitation, or automatically by personal and company Auto-Participant rules when someone joins a trip. |
| Creating trips | A carrier dispatcher drops in the rate confirmation and permits. The trip opens at once, and the files are read in the background by the Factory. Brokers have their own new-trip and trip-request pages. |
| Permit processing | Every new permit file creates a job in a Postgres queue (lease, revision and retry columns). The job sends the file to the Factory's permit reader, saves the state, number, dates, dimensions, weight and route token, computes alerts, then copies the trip to the Factory. Permit files are limited to 25 MB. |
| Alerts | Permit dimensions smaller than the trip's (shown on every trip since October 6), and expired or expiring permits. Alert emails are switched off. |
| Route offers | For each permit on a Workspace trip, the Workspace prices the route: Express at 3 or more uses of the route token, otherwise Extended. Routes on permits from Synchron are included and never priced. |
| Route locking | On a Workspace trip, route files stay hidden until the route is bought. Routes on Synchron permits show at once. |
| Cart and purchases | One cart per trip in the database. Purchases, purchase items and purchase events are stored with a fixed price snapshot. A mock Synchron adapter imitates checkout, callbacks and reconciliation. Only admin and moderator accounts can see Billing or buy, until launch. |
| Credits | Prepaid Express credits come from the plan. A credit is spent from the permit's own button, never through the card cart. |
| Chat | Each trip has an AI assistant served by the Factory. |
| Synchron import | Scripts read Synchron's carrier and order records with our API key and create completed trips that keep the 8-digit token. |
| Ordering permits | Today an email to Synchron. A two-step "Buy More Permits" dialog with card steps exists but waits for Synchron's API. |
2. Workspace data today
| Measure | Count |
|---|---|
| Trips | 960 (957 imported from Synchron, 3 created in the Workspace) |
| Permits | 3,825 |
| Documents | 3,965 |
| People (profiles) | 1,379, most imported and not yet signed in |
| Companies | 1,332, of which 167 carriers; 162 carriers have both DOT and MC; 165 carry a Synchron carrier token |
| Permit requests emailed to Synchron | 1 |
| Purchases | 2, both mock purchases on test trips; 16 carts |
3. What the Workspace data shows about the brief
- Confirmed: Synchron sends no callbacks to the Workspace. The receiver exists at
/api/webhooks/synchronand verifies the same HMAC scheme, but it has never received an event. No relayedorder.createdorpermit.attachedfrom the Factory has arrived either. Synchron permits reach the Workspace only through the import scripts. - Confirmed: the literal "route_token" problem is upstream of the Workspace. Of 3,825 Workspace permits, 3,447 have a numeric token, 1 has a
workspace:token, 377 have none, and none holds the text "route_token". - Confirmed: Synchron has no use counts. The Workspace already asks the Factory for them (
/api/workspace/route-token-usage). The Factory does not answer yet, so every route currently prices as Extended. - Correction: GPX and Hummer files do not reach the Workspace today. Section 3.3 says the Factory passes them to the Workspace. The Workspace has columns for both, but none of the 3,825 permits has a GPX or Hummer link. This must be built for purchased routes.
- Correction: the Workspace has no route text yet. The permit reader returns
route_description, not the texts the Factory sends topermittoken. Request F3 is needed before purchases can carry route text.
4. Response to requests W1–W12
| Request | Workspace today | What we will build | Estimate |
|---|---|---|---|
| W1 Order-number register | Trip numbers are random 9-digit numbers, unique only among existing trips, drawn from 100000000–999999999 | A permanent register; production 200000000–999999999, staging 100000000–100999999; a new order number per carrier change, linked by trip number | 0.5 day |
| W2 Server-side purchase client | Purchases are created on the server through a mock adapter; the browser never calls Synchron | The live adapter: X-HHA signing, Idempotency-Key = purchase token, X-Request-Id, retry 5xx with backoff, no retry on 4xx | 1–1.5 days |
| W3 Callback receiver | Exists; verifies HMAC on the raw body, 5-minute window, dedupes event IDs; handles the old event names | The new event names and payloads, version ordering, 2xx at once with background processing; hosted under heavyhaulagent.com (see question 1) | 1 day |
| W4 Payment proof | Already the rule: one function sets paid, only from a verified confirmation; the return page only reads and polls | Map it to purchase.paid and the GET status endpoint; add the contract test | 2 h |
| W5 Customer-facing states | Ten purchase states and eight fulfilment states with labels | Map Synchron's states, including Being prepared, Delayed and Expired | 0.5 day |
| W6 Complete purchase data | Carrier DOT and MC on 162 of 167 carriers; route token on every read permit | Purchaser role, driver, trip data, placeholder_fields; route text once F3 is done | 0.5 day |
| W7 Credits | Credits are counted in the Workspace and never mixed with card items | Send credit routes as $0 purchases; return the credit on refund | 0.5 day |
| W8 Reconciliation | An admin purchases page and an internal reconciliation endpoint exist | A daily comparison with route-history for orders active in the last 7 days | 0.5 day |
| W9 Support handoff | None | A written path from Workspace support to Synchron staff with purchase and route request tokens | 2 h |
| W10 Decisions | Pending with Nash | See section 7 | — |
| W11 Staging | No Workspace staging environment | Staging copy, callback path, storage domains, contacts | Depends on hosting |
| W12 Permit ordering (later) | A two-step dialog built around a CVV step; the form lacks plates and plate state, truck axle count, trailer type and length, axle spacing and axle weights | Card-setup redirect, 3-D Secure link, the missing fields, 24-hour document links with SHA-256 | 1–1.5 days in phase 4 |
5. What the Workspace needs from the Factory
- Use counts (F2). Without them every route is Extended.
- Route text with every token (F3). In the permit reading response, next to the route token.
- GPX and Hummer back to the Workspace. A defined call or event that carries both files for a Workspace permit, keyed by our permit ID.
- The relay question (F6). The Workspace has received no relayed events. If the Factory sends something, it is not reaching the Workspace.
6. Questions for the Synchron CTO
Asked by the HHA Workspace team. To be answered by the Synchron CTO. Type in each box, then save the page or print it to PDF and send it back.
Callback host. The Workspace runs on heavyhaulgbt.com, and heavyhaulagent.com is the Factory's address. Nash chose heavyhaulagent.com. Can the callback and Checkout return URLs use a Workspace subdomain such as app.heavyhaulagent.com? During the move, can staging also allow heavyhaulgbt.com?
The permit for an Extended route. To prepare an Extended route, the routing team needs the permit. Should each route item carry the permit PDF as a 24-hour link with SHA-256, the same way as permit-order documents?
permittoken for Workspace permits. Does the Factory call permittoken today for permits read in the Workspace, which have no Synchron order? If so, what does Synchron do with them? After purchase, Synchron runs the same check itself; how do we avoid running it twice?
Route text format. Is the Factory's route_description enough, or must the route text match the texts the Factory sends to permittoken exactly?
Drivers and shippers as buyers. In the Workspace a driver or a shipper on the trip can be allowed to buy routes. Your purchaser roles are carrier_user, broker, pilot and hha_admin. Should driver and shipper be added, or should the Workspace block them?
Permits without a route token. 377 Workspace permits have no route token. Can HHA sell an Extended route for them with route_token null, and will the routing team prepare it from the permit alone?
Permit events in phase 4. When HHA orders permits through the new API, will Synchron send an event with the permit PDF, number, dates and state for each item? The Workspace receiver could then be retired or reused.
Emailed permit requests. Does a permit request emailed by the Workspace go through Front Desk? Does the resulting order keep the Workspace trip number anywhere?
API version header. Which header carries the API version on requests and events, and in what format?
Rate limit. Does the 60-requests-a-minute limit include the Workspace's GET status checks and the daily reconciliation?
Callback source addresses. Will callbacks come from fixed IP addresses that the Workspace host can allow, or should the signature be the only check?
The excluded carrier. Which carrier is excluded from automatic release in code (name and DOT)? Nash needs this to decide keep, change or remove.
Imported trips. Can the Workspace use the new GET routes endpoint for 8-digit orders, to show route status on imported trips? Read-only, with no purchase.
Purchase token format. The Workspace's purchase reference is hhp_ followed by 20 characters, and route request IDs are UUIDs. Please confirm both are accepted as is.
Expiry of a pending purchase. The Workspace marks a pending purchase expired on its own clock as well. Should it wait for purchase.expired only, so the two never disagree?
Contract repository access. Where will the contract repository live, and can the Workspace build against the OpenAPI file and sample events before staging is ready?
7. Decisions still waiting on Nash
| Decision | Workspace position today |
|---|---|
| Purchaser rule | The Workspace lets any trip participant buy, limited to admin and moderator until launch. Your later design accepts brokers, pilots and HHA admins. |
| $100 maximum per route | No objection from the Workspace; prices are $1.99 and $10.00 |
| 409 alert address | To be named by Nash |
| Statement suffix | "HHA ROUTES", subject to Synchron's prefix and the 22-character limit |
| The carrier excluded from automatic release | Needs the carrier's name first (question 12) |
| Callback and return host | Needs question 1 answered |
| Axle spacing and axle weights on the permit form | The Workspace can add them as optional fields before phase 4 |