Domain model

This page is the canonical map of TOVR's domain: the entities and how they relate. Other pages assume this vocabulary. Terms first defined here are summarized in the shared Glossary.

The two sides of the market

TOVR matches demand (freight to move) against supply (trucks that can move it).

Demand: shipments and loads

• Shipment — the atomic unit of demand: a consignment to move from an origin to a destination. A shipment has a source platform (the exchange it came from), a shipper, a price, and a status (for example unmatched, awarded, or expired). Most detail hangs off the shipment as child records: stops (pickups and deliveries, each at a location), contents, attributes, events, and route segments (distance, travel time, and CO₂ per segment).
• Load — the structured cargo view associated with a shipment: line items, handling units, order references, and involved parties. Where a shipment is the lightweight demand root, a load is its normalized cargo detail.
• Shipment cost — the commercial money lines on a shipment (notably the freight rate), each with a data-quality signal: a confidence score, whether it is estimated, and how it was matched. This is distinct from operational cost, which the cost engine computes per leg.

Supply: carriers, vehicles, drivers

• Carrier — the trucking company. Carries fleet size, tax/VAT identity, vetting status, a credit balance, and billing details. The carrier is TOVR's customer.
• Vehicle — a truck, belonging to a carrier: licence plate, type, make/model/year, last known location, and whether it is ADR-certified (hazardous goods). Each vehicle has a vehicle spec — the cost-engine inputs: fuel type, consumption, tank capacity, emission class, axle count, weights and dimensions. Missing specs fall back to type-based defaults.
• Vehicle availability — where and when a truck is free (a location plus a time window). This is what matching runs against.
• Driver — belongs to a carrier: home country, employment status, and licence/ADR/CPC expiry dates. Driver salary records hold effective-dated pay (monthly or hourly) that feeds the driver cost component.

Counterparties: shippers and contacts

• Shipper — the company that posted the load; the demand-side counterparty.
• Shipment contacts — the shipper's people (dispatch, logistics, sales). Winning freight means negotiating with these contacts — the heart of procurement.

The decision unit: freight chains

A freight chain ties supply to demand. It is one vehicle executing an ordered sequence of shipments as a single route, decomposed into legs (alternating deadhead and loaded), with a full cost-and-profit breakdown attached. Chains are the central object the dispatcher acts on — the Freight chains page owns the full model, and the Cost engine owns how their P&L is computed.

The matching layer between the two sides is captured by match records: candidate vehicle↔shipment pairings and shipment↔shipment linkability (how well one shipment chains onto another), each scored with the empty distance and wait time it implies.

Locations

A location is a geocoded place — an origin, a destination, or where a truck is free. It stores a geographic point (there are no separate latitude/longitude fields), plus country, city, postal code, and spatial-index metadata used for fast proximity search. Geocoding is cached, never looked up live during pricing.

Integrations and telematics

• Integration providers — the catalog of external systems TOVR can connect to: telematics and OEM fleet-data sources, freight exchanges, TMS, and assistant apps.
• Company integration — a specific org's connected instance of a provider, with its own status, config, and consent. Encrypted credentials are referenced, never stored in the open.
• Telematics data — ingested vehicle and driver signals: trips, fuel events, driving times (which feed hours-of-service checks), eco-driving scores, and alarms.

Tenancy: the org model

Every entity above is scoped to an org (organization) — the account and billing boundary. Users join orgs through memberships with a role (owner / admin / dispatcher / viewer), can be grouped into teams, and access can be shared at a fine grain. The org is the live tenant anchor across the whole platform.

The older tenancy model keyed on company_vat has been retired — org_id (orgs.id) is the tenant anchor everywhere, and tenant-scoped tables carry the org_ prefix (e.g. org_integrations). "Company" is reserved for external directory entities (carriers, shippers, freight-chain companies).

For field-level tables of these entities, see the (forthcoming) domain-model reference under TOVR › Reference.