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

From
Nash Turcan and the HHA technical team, HeavyHaul Agent (HHA)
To be answered by
The Synchron CTO, Synchron Permits
Sent
October 6, 2026, 3:51 PM ET
Purpose
Agree on one shared picture of how HeavyHaul Agent, the HeavyHaul Factory and Synchron Permits work together

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

1. HeavyHaul AgentThe workspace customers useNext.js web app + Supabase databaseUsers, trips, documents, permits,alerts, chat, cart and purchases 2. HeavyHaul FactoryHHA's API and AI backendPython service + MongoDBReads permits, route tokens, AI chat,GPX and Hummer files 3. Synchron PermitsThe permit company's operations systemLaravel + MySQL, Stripe accountOrders, permits, routing team,customers, carriers, payments Read permit or rate con, trip sync, AI chat, route-token use Extraction results, route token and links, profile feed Permit request email (today)Import reads full-records (today)Signed route-purchases API (agreed) Signed callbacks to the workspace:order.created, permit.attached (today)purchase.*, route.completed (agreed) permittoken (route token proposals)seperateorders (read order routes) update-order, auto_approval,auto-order, ext-ratecon,equipment updates

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 Factory3. Synchron Permits
Who runs itHHAHHASynchron Permits
What it isThe web workspace customers sign in to: brokers, carrier dispatchers, pilot companies, driversHHA's API and AI backend that the workspace and Synchron both callThe permit company's operations system: orders, permits, routing team, customers, payments
TechnologyNext.js web app, Supabase (Postgres) database, Amazon S3 for filesPython API service with MongoDB (the team also calls it "GPT")Laravel 10, MySQL (permit-v3), Stripe
Where it livesheavyhaulgbt.com today; Nash chose heavyhaulagent.com for the Synchron integrationWe believe heavyhaulagent.com, where Synchron's calls to HHA landpermits.synchrontms.com
What it ownsAccounts, companies, workspace trips, participants, documents, permits as read, alerts, chat, carts and route purchasesPermit and rate confirmation reading, route matching and route tokens, AI chat and voice, a mirror of trips and Synchron orders, GPX and Hummer filesSynchron 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.
Synchron CTO — confirm, correct or add

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 endpointWhat the workspace uses it for
/api/workspace/extract/permitRead a permit: state, number, dates, dimensions, weight, route token, route status and any matched Google Maps links
/api/workspace/extract/rate-confirmationRead a rate confirmation to fill a new trip
/api/workspace/logistics-chatThe AI assistant on each trip
/api/workspace/logistics-voice/tokenVoice conversations with the assistant
/api/workspace/route-token-usageHow many times a route token was used, to price Express or Extended (requested; the Factory does not answer yet)
/api/workspace/permit-profile-observationsCarrier, truck and trailer details learned from permits, to build reusable profiles
Trip syncCopies 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.

DirectionCallWhat it does
Factory → SynchronPOST /ai/v1/permittokenProposes a route token for a state item. Synchron's automatic release check runs here.
Factory → SynchronGET /ai/v1/seperateorders/{token}Reads an order's items with their route links and status
Synchron → FactoryPOST /api/update-orderTells 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 → FactoryPOST /api/auto_approvalSends the route links, route token, item, truck unit, driver and client when a route is approved automatically
Synchron → FactoryPOST /api/auto-orderUnknown to us. Please describe.
Synchron → FactoryPOST /ext-rateconUnknown to us. Please describe.
Synchron → FactoryTruck, trailer and carrier updatesUnknown 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.

Synchron CTO — confirm, correct or add

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-records and /api/v1/orders/full-records with HHA's API key.
Synchron CTO — confirm, correct or add

How work moves between the three today

  1. 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.
  2. 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, then permit.attached for each state. The workspace saves each permit and the Factory reads it. Routes on these permits are included at no charge.
  3. 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.
  4. Synchron releases a route. Staff approval triggers update-order to the Factory, which reads the links and makes GPX and Hummer. An automatic approval sends the links directly in auto_approval.
Synchron CTO — confirm, correct or add

Route purchase, as agreed (to be built)

  1. The customer chooses routes in the workspace. The workspace decides Express or Extended and the price.
  2. 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.
  3. Synchron creates or extends the order, opens a Stripe Checkout on its own account, and the customer pays there and returns to heavyhaulagent.com.
  4. Synchron sends purchase.paid; routing work starts. When the route is released, Synchron sends route.completed with the Google Maps link to the workspace.
  5. The existing update-order and auto_approval calls keep running, so the Factory still makes the GPX file and Hummer link.
Synchron CTO — confirm, correct or add

Identifiers used across the three systems

IdentifierIssued byMeaning
Trip number (HH- + 9 digits)WorkspaceOne workspace trip. Production numbers 200000000–999999999, staging 100000000–100999999.
Order number (9 digits)WorkspaceOne Synchron order per trip and carrier. The first equals the trip number; a new carrier gets a new one.
Order token (8 digits)SynchronOrders created inside Synchron, including those HHA imports
Permit tokenSynchronOne state item on a Synchron order
Route token (numeric)Synchron catalog, as matched by the FactoryA known route; its use count decides Express or Extended
Route token (workspace:…)FactoryA route first seen in a workspace permit
User and carrier tokens (16 characters)SynchronSynchron's people and carriers; HHA stores them for imported records
HHA user, company and driver IDsWorkspacePermanent IDs sent to Synchron so no one is created twice
Purchase and route request tokensWorkspaceOne checkout, and one route item in it
Synchron CTO — confirm, correct or add

What HHA is unsure about

  1. Is the Factory the system at heavyhaulagent.com that receives update-order, auto_approval, auto-order and ext-ratecon? What do auto-order and ext-ratecon do?
  2. Where does the numeric route token and its Frequency live: in Synchron's MySQL (od_item_route_tokens), in the Factory's MongoDB, or both?
  3. Does the Factory write anything into Synchron besides permittoken?
  4. 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?
  5. What is Frontdesk, which has its own token (FRONTDESK_API_TOKEN)? Is it a fourth system?
  6. Are there other systems or scheduled jobs that touch HHA data which this page does not show?
Synchron CTO — answers and additions