From HeavyHaul Agent to the Synchron CTO — How HeavyHaul Agent, the HeavyHaul Factory and Synchron Permits work together — October 6, 2026, 3:51 PM ET
Why this document
HeavyHaul Agent is built from three systems that work together. Each side knows its own part well, but no single document describes the whole. This page writes down what the HHA team understands today, so the Synchron CTO can confirm it, correct it and add what we do not know. The goal is one shared picture before route purchase is built.
How to reply: each section ends with a box for the Synchron CTO. Click a box to type, then save the page (File → Save Page As) or print it to PDF and send it back. Please also add anything we missed, including other systems we have not named.
The three systems at a glance
Grey lines run today. The dashed line from the workspace to Synchron carries today's email and import, and the agreed route-purchase API. Every name on a line is a call described in the sections below.
| 1. HeavyHaul Agent (workspace) | 2. HeavyHaul Factory | 3. Synchron Permits | |
|---|---|---|---|
| Who runs it | HHA | HHA | Synchron Permits |
| What it is | The web workspace customers sign in to: brokers, carrier dispatchers, pilot companies, drivers | HHA's API and AI backend that the workspace and Synchron both call | The permit company's operations system: orders, permits, routing team, customers, payments |
| Technology | Next.js web app, Supabase (Postgres) database, Amazon S3 for files | Python API service with MongoDB (the team also calls it "GPT") | Laravel 10, MySQL (permit-v3), Stripe |
| Where it lives | heavyhaulgbt.com today; Nash chose heavyhaulagent.com for the Synchron integration | We believe heavyhaulagent.com, where Synchron's calls to HHA land | permits.synchrontms.com |
| What it owns | Accounts, companies, workspace trips, participants, documents, permits as read, alerts, chat, carts and route purchases | Permit and rate confirmation reading, route matching and route tokens, AI chat and voice, a mirror of trips and Synchron orders, GPX and Hummer files | Synchron orders (8-digit tokens), state items, permits, routes approved by the routing team, Stripe payments, cards on file |
1. HeavyHaul Agent — the workspace
- Who uses it. Five page groups: freight broker, carrier dispatch, pilot company, carrier truck driver and pilot car driver. Each person sees only the trips they are a participant on.
- Trips. A trip created in HHA gets a number like HH-512048337 (9 digits). Trips imported from Synchron keep Synchron's 8-digit order token, for example HH-38879104.
- Permits. A permit can arrive three ways: a customer uploads it, Synchron sends it through the signed callback, or the import copies it from Synchron's order data. Every permit is stored first, then sent to the Factory to be read.
- What it calculates itself. Alerts (permit smaller than the load, expired, expiring), the price of a route (Express or Extended, from how often its route token was used), carts and route purchases, and who is added to a trip automatically (Auto-Participants).
- Source of truth. The workspace database is the master record for workspace trips. The Factory keeps a copy for AI and reporting.
2. HeavyHaul Factory — HHA's API and AI backend
The workspace calls the Factory with its own client credentials. These are the calls the workspace makes today:
| Factory endpoint | What the workspace uses it for |
|---|---|
/api/workspace/extract/permit | Read a permit: state, number, dates, dimensions, weight, route token, route status and any matched Google Maps links |
/api/workspace/extract/rate-confirmation | Read a rate confirmation to fill a new trip |
/api/workspace/logistics-chat | The AI assistant on each trip |
/api/workspace/logistics-voice/token | Voice conversations with the assistant |
/api/workspace/route-token-usage | How many times a route token was used, to price Express or Extended (requested; the Factory does not answer yet) |
/api/workspace/permit-profile-observations | Carrier, truck and trailer details learned from permits, to build reusable profiles |
| Trip sync | Copies each workspace trip, its documents and requests into the Factory's MongoDB so the AI can use them |
Route tokens as we understand them. When the Factory reads a permit, it matches the route against a catalog. A route found in the Synchron catalog keeps its numeric token, and the Factory does not increase that route's Frequency. A new route gets a workspace:<code> token, and each use is recorded once per permit.
Calls between the Factory and Synchron, from your earlier answers.
| Direction | Call | What it does |
|---|---|---|
| Factory → Synchron | POST /ai/v1/permittoken | Proposes a route token for a state item. Synchron's automatic release check runs here. |
| Factory → Synchron | GET /ai/v1/seperateorders/{token} | Reads an order's items with their route links and status |
| Synchron → Factory | POST /api/update-order | Tells HHA an order changed: a route added or approved, or a permit attached. Carries the order token, plus the permit link and number when attached. |
| Synchron → Factory | POST /api/auto_approval | Sends the route links, route token, item, truck unit, driver and client when a route is approved automatically |
| Synchron → Factory | POST /api/auto-order | Unknown to us. Please describe. |
| Synchron → Factory | POST /ext-ratecon | Unknown to us. Please describe. |
| Synchron → Factory | Truck, trailer and carrier updates | Unknown in detail. Please list the calls and what they carry. |
GPX and Hummer. The Factory takes the Google Maps route Synchron approved and produces the GPX file and the Hummer GPS link. Today it learns about approved routes through update-order and then reads the links with seperateorders, or receives them directly in auto_approval.
3. Synchron Permits — the permit company's system
- Orders. One order per customer job, with an 8-digit token. One item per state; each item has its own token, price and status. Routes are stored as Google Maps links on the item.
- People. Clients, carriers, drivers, trucks and trailers. Carriers and users have 16-character tokens, and HHA already holds those tokens for the carriers and users it imported.
- Routing team. Prepares and approves routes. A route is released automatically only when the same route was approved 3 times in that state.
- Payments. Synchron's own Stripe account: cards on file, permit pre-authorizations, refunds.
- API used by HHA today. The import scripts read
/api/v1/carriers/relations,/api/v1/carriers/{id}/full-recordsand/api/v1/orders/full-recordswith HHA's API key.
How work moves between the three today
- A carrier uploads its own permits. The workspace stores the file, the Factory reads it and returns the route token and any matched links, and the workspace saves the result, checks alerts and syncs the trip to the Factory. Synchron is not involved.
- A customer orders permits from Synchron. The workspace sends Synchron an order request by email. Synchron creates its order and sends signed callbacks to the workspace:
order.created, thenpermit.attachedfor each state. The workspace saves each permit and the Factory reads it. Routes on these permits are included at no charge. - Synchron's own orders are imported. HHA's import scripts read Synchron's full records (January to March 2026 so far: 957 orders, 3,806 permits) and create completed trips in the workspace.
- Synchron releases a route. Staff approval triggers
update-orderto the Factory, which reads the links and makes GPX and Hummer. An automatic approval sends the links directly inauto_approval.
Route purchase, as agreed (to be built)
- The customer chooses routes in the workspace. The workspace decides Express or Extended and the price.
- The workspace server sends one signed request to Synchron's new
/api/v1/hha/route-purchases, with the order number, trip number, carrier, purchaser, driver when known, trip data and route items. - Synchron creates or extends the order, opens a Stripe Checkout on its own account, and the customer pays there and returns to heavyhaulagent.com.
- Synchron sends
purchase.paid; routing work starts. When the route is released, Synchron sendsroute.completedwith the Google Maps link to the workspace. - The existing
update-orderandauto_approvalcalls keep running, so the Factory still makes the GPX file and Hummer link.
Identifiers used across the three systems
| Identifier | Issued by | Meaning |
|---|---|---|
| Trip number (HH- + 9 digits) | Workspace | One workspace trip. Production numbers 200000000–999999999, staging 100000000–100999999. |
| Order number (9 digits) | Workspace | One Synchron order per trip and carrier. The first equals the trip number; a new carrier gets a new one. |
| Order token (8 digits) | Synchron | Orders created inside Synchron, including those HHA imports |
| Permit token | Synchron | One state item on a Synchron order |
| Route token (numeric) | Synchron catalog, as matched by the Factory | A known route; its use count decides Express or Extended |
| Route token (workspace:…) | Factory | A route first seen in a workspace permit |
| User and carrier tokens (16 characters) | Synchron | Synchron's people and carriers; HHA stores them for imported records |
| HHA user, company and driver IDs | Workspace | Permanent IDs sent to Synchron so no one is created twice |
| Purchase and route request tokens | Workspace | One checkout, and one route item in it |
What HHA is unsure about
- Is the Factory the system at heavyhaulagent.com that receives
update-order,auto_approval,auto-orderandext-ratecon? What doauto-orderandext-ratecondo? - Where does the numeric route token and its
Frequencylive: in Synchron's MySQL (od_item_route_tokens), in the Factory's MongoDB, or both? - Does the Factory write anything into Synchron besides
permittoken? - When the workspace emails a permit order, does Synchron staff create the order by hand? Does Synchron store the workspace trip number on that order?
- What is Frontdesk, which has its own token (
FRONTDESK_API_TOKEN)? Is it a fourth system? - Are there other systems or scheduled jobs that touch HHA data which this page does not show?