Domain model

Field-level reference for TOVR's core entities — shipments, loads, carriers, vehicles, drivers, locations, freight chains, chain legs, matches, and orgs. Representative columns; the source of truth is the Drizzle schema.

Field-level reference for TOVR's core entities. What they mean is in Concepts › Domain model; this page lists representative columns. The authoritative schema is packages/core/src/schema/drizzle/* — these tables highlight the fields you actually work with, not every column.

Shipments — demand

`shipments`

Column	Notes
`id`, `external_id`	Identity; `external_id` is the source-platform reference.
`platform`	Source exchange the shipment came from.
`shipper_id`, `org_id`	Counterparty and owning tenant (`org_id` may be null for market rows).
`owned_by_tovr`	Whether TOVR owns this shipment record.
`purchase_price`, `target_sell_price`	Commercial anchors.
`status`	`UNMATCHED`, `AWARDED`, `EXPIRED`.

Child tables: stops (pickup/delivery → location_id), shipment_cargo → shipment_cargo_items (see below), shipment_attributes, shipment_events, shipment_identifiers, route_segments (distance/travel-time/CO₂), shipment_contacts (the shipper's people).

`shipment_cargo` + `shipment_cargo_items` — what is being moved

`shipment_cargo` (header, one row per source)	`shipment_cargo_items` (line items)
`shipment_id`, `source`, `org_id` (PK is `(shipment_id, source)`)	`shipment_id`, `source` (→ header), `org_id`, `position`
`gross_weight_kg`, `volume_m3`, `loading_metres`	`quantity` + `handling_unit_type`, `handling_unit_label`
`adr`, `adr_class`	`gross_weight_kg`, `description`, `product_category`
`temperature_min_c` / `_max_c` / `_set_point_c`	`temperature_min_c` / `_max_c`
`requires_exchange`, `totals_are_stated`, `confidence`

Two rules govern this tree. Every numeric column carries its unit in its name — there is no (value, unit) pair, because a pair still permits SUM(value) across mixed units, which is the bug the model exists to end. And source is part of the primary key: one row per shipment per source (EXCHANGE, DOCUMENT, HUMAN, …), so a re-ingest rewrites exactly its own rows and cannot clobber a dispatcher's correction.

There is deliberately no shipment-level quantity — a bare cross-unit total is precisely what could not be trusted. Quantity lives on the item next to its handling_unit_type, locked together by CHECK ((quantity IS NULL) = (handling_unit_type IS NULL)).

Read the resolved view, not the raw rows: shipment_cargo_effective collapses the sources per field via cargo_source_rank() (adr resolves by bool_or instead — a hazard asserted by any source is a hazard). Items resolve at row-set level: the highest-ranked source that has any items supplies the whole list.

The old shipment_contents table was dropped in #2108, along with the pallet_count shipment attribute it fed. shipment_contents remains a top-level key on GET /api/v1/shipments/{id} — a published contract does not lose a key for an internal reason — but it is now mapped from shipment_cargo_items.

`shipment_costs`

Column	Notes
`type`	Cost type (e.g. `FREIGHT_RATE`, demurrage).
`amount`, `currency`	The money line.
`confidence_score`, `is_estimated`, `match_level`	Data-quality signals (e.g. an APEX estimate).

Loads — structured cargo

loads → load_items → load_handling_units / load_item_identifiers / load_item_order_references, plus load_involved_parties, load_identifiers. A load references a master_shipment_id.

Carriers, vehicles, drivers — supply

`carriers`

linked_org_id, tax_id, fleet_size, vies_status (pending/verified/unverified/ unavailable, with vies_checked_at), vetted_at, credit_balance_cents, billing_details_confirmed_at.

`vehicles` + `vehicle_specs`

`vehicles`	`vehicle_specs` (cost-engine inputs)
`carrier_id`, `license_plate`, `type`	`fuel_type`, `fuel_consumption` (L/100km)
`make`/`model`/`year`, `adr_certified`	`tank_capacity`, `emission_class`, `co2_class`
`last_known_location` (point), `h3_index`	`axle_count`, weights/dimensions
`last_seen_at`, `driver_id`	resolved via `vehicle_spec_defaults` when missing

`vehicle_availabilities`

vehicle_id, location_id, available_from/available_to, status.

`drivers` + `driver_salary_records`

Driver: carrier_id, home_country, employment_status, licence/ADR/CPC expiry. Salary: effective-dated rate_mode (monthly/hourly), base salary or hourly rate — feeds driver cost.

Locations

locations: point (PostGIS geography), country (not country_code), city, postal_code, h3_index, time_zone. Use extractCoordsFromPoint(point); there are no latitude/longitude columns.

Freight chains — the decision unit

`freight_chains`

Column group	Notes
`origin`, `status`, `vehicle_id`, `org_id`, `awarded_org_id`	Identity & ownership.
`shipment_ids[]`, `countries_traversed[]`	Route composition.
`cabotage_status`, `cabotage_details`, `feasibility_details`, `driver_feasible`	Compliance.
`fuel_/toll_/driver_/vignette_/border_cost_eur`, `cost_confidence`	Cost breakdown.
`profit_eur`, `profit_margin_pct`, `profit_per_km`, `revenue_per_km`, `cost_per_km`	Generated P&L.
`market_position`, `market_median/p25/p75_eur_km`	Market position (from APEX).

`chain_legs`

leg_type (deadhead/loaded), shipment_id (null for deadhead), revenue_eur (null for deadhead), fuel_/toll_/driver_/vignette_/border_cost_eur, generated total_cost_eur, leg_profit_eur.

Matching

vehicle_shipment_matches — candidate vehicle↔shipment pairs (deadhead_km, wait_time_hours, score).
shipment_matches — shipment→shipment linkability. Columns: origin_shipment_id, match_shipment_id, score, deadhead_km, wait_time_hours, match_type.

Tenancy

orgs (id, name, slug, stripe_customer_id) is the tenant anchor; org_members (role: owner/admin/dispatcher/viewer), teams, org_invitations. The legacy company_vat model is superseded by org_id.

Domain model

On this page