Cost engine

The cost engine is TOVR's single source of cost truth. Given a freight chain and a specific vehicle, it computes a real, per-leg profit-and-loss: what each leg costs to run, what revenue the loaded legs earn, and the resulting profit and margin. Every number a dispatcher or fOS sees about chain economics comes from here.

The P&L, per leg

For each leg of a chain, the engine sums five cost components, then rolls them up:

leg_cost   = fuel + toll + driver + vignette + border
chain_cost = Σ (all legs)
profit     = Σ revenue(loaded legs) − chain_cost
margin     = profit / revenue

Deadhead legs contribute cost but no revenue — see Freight chains for why that matters.

The five components

Each component is computed from real per-country, per-leg inputs:

• Fuel — distance × the vehicle's consumption × the fuel price along the route, split by country, less any fuel-card discount the carrier has.
• Tolls — distance-based road charges for the vehicle's class (emission class, weight, axle count), by country.
• Driver — driving hours × the driver's rate, plus per-diem (domestic vs international) and overtime; loaded legs add paid loading and unloading time.
• Vignettes — time-based road-use stickers for countries that use them. Charged once per chain and distributed across legs; zeroed for a country the vehicle already holds a valid vignette for.
• Border crossings — a fixed cost and delay per crossing, higher for non-EU borders.

Costs are carrier-specific

The same route has a different P&L for a different carrier, because the engine resolves inputs in a fixed order of specificity:

1. Carrier overrides — the carrier's own effective-dated rate tables (driver rates, fuel prices, vignette rates) and scalar settings (fuel-card discount, load/unload hours, border hours, minimum margin, working days per month). A carrier sets these on Settings › Costs & margins.
2. Global reference tables — market-wide benchmarks where the carrier has no override.
3. Hard defaults — a last-resort fallback.

This is why cost is modeled per vehicle and per carrier, not per lane: two carriers running the identical route legitimately see different profit.

It runs from cached data — no live calls

A critical property: the cost engine makes zero external API calls while building or pricing a chain. Fuel prices, toll rates, route geometry, and distances are all pre-synced into cache tables by background jobs. Pricing a chain is then a pure database read plus math.

This keeps pricing fast and deterministic, and it is why data freshness is a background concern rather than a per-request one. When a required input is missing from the cache, the engine degrades gracefully and lowers the chain's cost confidence rather than blocking.

Cost confidence

Not every chain is priced from complete data. Each chain carries a cost confidence signal — broadly calculated (all inputs present), estimated, or partial (some inputs fell back to defaults or were missing from the cache). Confidence lets the dispatcher and fOS weight how much to trust a P&L, and it recovers automatically as background syncs refill the caches.

Feasibility is separate from cost

Before a chain's economics matter, it must be legal and schedulable. The engine's feasibility checks — driver hours-of-service, cabotage, weekend/holiday truck bans, and pickup/delivery time windows — decide whether a chain can run at all. Those rules are owned by Compliance. Economics are only consulted for chains that pass.

From cost to a bid

The cost engine produces the floor: the minimum a carrier can accept and still hit its target margin. Turning that floor into a recommended bid — by positioning it against the lane's market — is owned by Bid recommendation.