Docs

Adaptive TMS deployment, and the design that makes it fast.

How Caravan Supply Chain builds transportation management deployments that adapt to a partner’s network instead of asking the network to adapt to the software — the normalization layer underneath it, and the design principle that decides what gets an interface.

This is a design document describing methodology. It is not an API reference. Platform interface documentation is issued to entitled partners through the access-controlled environment described on Technology.

Normalization

Deployment speed comes from the adapter being the only new part.

Logistics data arrives in every shape there is: EDI, partner APIs, flat files, portal exports, spreadsheets, PDFs, and email. Software written directly against those shapes inherits all of them, and every new partner becomes a new application.

Caravan normalizes each source, at the edge, into the canonical objects of its native SDK — shipment, stop, party, equipment, event, document. Modules are written against the SDK and never against a partner’s source system. The per-partner code is the adapter that performs that translation, and nothing beyond it knows or cares where the data came from.

The consequence is the point: scoping a new deployment is scoping an adapter. The application already exists. That is what makes a deployment adaptive rather than bespoke, and it is why a partner’s integration can be reasoned about as a bounded piece of work during discovery.

Normalization is applied as needed, not exhaustively. A field that no workflow reads does not get modeled — carrying a partner’s entire schema into the SDK would recreate exactly the coupling the layer exists to prevent.

Design principle

“Does this need a board?”

Every piece of a TMS deployment gets asked this before it is designed. Most of the answers are no, and the projects that go wrong are usually the ones that never asked.

What a board actually is

A load board is a spreadsheet with a specific workflow attached to it. Rows are the unit of work, columns are the fields, and the workflow is the set of transitions a row is allowed to make. That is the whole abstraction, and stating it plainly is useful: everyone in freight already knows how to use a spreadsheet, and the reason boards are the dominant interface in this industry is that they inherit that fluency.

Board and spreadsheet part company at the workflow. A spreadsheet will let a row go anywhere; a board will not. What a row may become, who may move it, and what has to be true before it moves are the design work.

Reference fields

Every board declares a small set of reference fields, and those fields are prioritized throughout its flow. They are the ones people say out loud — the load number, the PO, the pro number, the appointment, the stop.

Prioritized means they carry the weight: they anchor the sort and the search, they are what a row is deduplicated on, they are the join back to the partner’s system of record, and they are what a dispatcher reads to know which row is theirs. Everything else on the row is payload — present, queryable, but not driving the flow. Choosing the reference fields correctly during discovery is most of what makes a board feel native to the people who work it.

When the answer is yes

There is a queue a person works through, and judgment is applied row by row. Covering loads, working an exception list, reviewing documents that failed extraction, booking appointments against capacity. It becomes a board, with its reference fields established first and its permitted transitions defined explicitly.

When the answer is no

Nobody works it row by row — it translates, validates, reconciles, or notifies. It ships as a job with no interface at all, observable through events and audit. Most of what a TMS deployment does falls here, and building screens for it is where these projects historically get expensive.

Because boards are declared over normalized objects rather than hand-built as screens, a board is closer to configuration than to construction. That is the second half of adaptive: a partner whose process differs gets a different declaration, not a fork.

What a deployment inherits

Standardize infrastructure, liberate the application.

The platform owns the shared operational layer so that modules only ever contain the part that is actually about freight. A new module starts with all of this already true.

Identity and tenancy: Users, organizations, and the boundary between them. A partner deployment is a tenant, not a copy of the application.
Roles and scopes: Permission is expressed per module, so a dispatcher, a planner, and a receiving clerk can share a deployment without sharing a view.
Module registration and entitlements: What a given partner is deployed is a set of entitled modules. Turning capability on is a grant, not a build.
SDK token issuance: Modules and adapters authenticate to the platform through issued tokens rather than through shared credentials.
Jobs and events: The asynchronous spine. Normalization, polling, reconciliation, and notification all run here rather than inside a request.
Artifacts and documents: Files are first-class and attached to the object they belong to, which is what makes a shipment's paper trail retrievable as a unit.
Notifications: Delivery to the channel a party actually uses, governed by the consent rules that apply to that channel.
Audit: Who changed what, when. Assumed by every module rather than reimplemented by each one.

Versioning

A partner deployment is a versioned set of entitled modules plus its adapters and its board declarations. Those three things are what make it that partner’s deployment, and each of them can move independently.

Modules deploy on their own schedule, so a change to document handling does not require redeploying scheduling. A partner whose source system changes needs a new adapter version and nothing else. A process change is usually a change to a board declaration. Keeping those three seams distinct is what allows Caravan to hold development capacity against deployed systems without every change becoming a project.

How this fits into an engagement

Access

The platform these deployments run on is access-controlled and has no public surface. Interface documentation, SDK access, and environment credentials are issued to entitled partner organizations as part of a deployment, not published here.

Technology for Caravan Supply Chain is developed, licensed, and administered by 400x Systems Inc.; see Technology for how responsibility divides between the two companies, and Use cases for what this methodology gets applied to.