Concepts & glossary

When the validator flags HIGH or MEDIUM issues that won't be fixed before this tender ships, you can bypass them individually with a written reason. The reason is captured in the audit log and the executive PDF. CRITICAL severity cannot be bypassed — fix the data instead.

After mapping columns and resolving validation warnings, you commit the dataset. Commit writes the normalised data file the load/process step will consume. CRITICAL issues block commit; HIGH/MEDIUM issues require a bypass.

When you upload, aclRate computes a fingerprint from your file's column headers (sorted, lower-cased). The fingerprint is matched against saved mapping templates — an exact match triggers a "Matching template found" suggestion chip.

Every historic file has its own column names. The mapping tells aclRate which of your columns means "Total Cost", "Carrier", "Mode", etc. Smart Mapping auto-suggests matches; you confirm or override per row. Saved mappings can be reused across files with matching headers.

Once you've mapped a customer's file once, save the mapping as a template. On the next file with the same header set, the template auto-suggests and you can apply the entire mapping in one click. Templates are shared across your tenant by default.

A tender is a single procurement cycle for a customer. In aclRate it spans the full workflow: uploading historic data, running scenarios, picking an awarded portfolio, and exporting to the TMS. Each tender is identified by its session_uid.

aclRate's shipper-mode workflow runs in five steps: Smart Mapping → Historic data validation → Load & process (scenario engine) → Results & decision (award) → TMS export. You move forward one step at a time; some steps can be revisited without re-running the others.

When one lot has a lane A→B and another lot has the return B→A, awarding both to the same carrier lets them avoid an empty return trip. aclRate flags these return pairs (when each has enough volume); awarding them together typically yields 8-15% backhaul efficiency — confirm the rate with the carrier.

A brief starts in scoping, becomes ready once lots are sliced and materialised, moves to tendered when a run completes, then to PARTIAL AWARD once at least one lot is awarded, and to AWARDED when every in-scope lot is awarded. The brief list shows a coloured pill for each state.

When every in-scope lot reaches the 'awarded' decision the brief is signed off as AWARDED — a compliance/reporting signal that the tender is complete. Reopening clears a lot's decision (dropping the brief back to PARTIAL AWARD) and records an audit reason.

Cost Type describes the unit a carrier prices by. Common values: PER-SHIPMENT (flat fee), PER-KM, PER-KG, PER-PALLET, PER-CONTAINER. Each row gets a CT; carriers must respond with prices in the matching CT. RG × CT produces 16+ possible combinations on a typical tender.

Opportunities and behavioural shifts are tagged with their lot when at least 80% of the affected shipments belong to one lot (e.g. "Lot 3 — Intra-NL: switch carrier"). When a pattern is spread across lots — like a weight-band routing issue that appears in several lots — it has no single lot and stays phrased in its movement / rate-geography terms. Deeper cross-lot synergy detection (volume rebates, backhaul pairing, capacity risk) is planned for a future release.

Most TMS exports don't carry Rate Geography or Cost Type — they're pricing concepts, not shipment fields. When a column is missing (or blank on some rows), aclRate derives it per shipment: for RG it uses whichever location field is populated (postal code first, then city, then zone) on each side; for CT it uses the populated cost driver (equipment/truck type, then weight, then distance, then loading metres; otherwise per shipment). A grey DERIVED chip on a lot card marks an inferred value, and PARTLY DERIVED means only the rows you left blank were filled — values you supplied are never overwritten. You can override any lot's RG/CT from its dropdown.

A lane is the atomic unit of a freight tender: "all shipments from NYC to LAX" is one lane. Lane keys are computed from the Rate Geography fields — for CITY-CITY that's source city + destination city, for ZONE-ZONE it's source zone + destination zone, etc. Carriers bid lane-by-lane.

Lanes vary in importance. Strategic lanes are high-volume or service-critical; spot lanes are one-off or very low volume; standard is everything else. Criticality affects the award builder (strategic-lane overrides require confirmation) and the executive PDF (criticality distribution is shown).

Lane intelligence is the Portfolio view over lanes you have awarded more than once. A lane qualifies once it has appeared in at least three of your AWARDED tenders, so it is built from decided history rather than from anything in flight. For each lane it shows how often it has appeared, how the awarded price has moved across those tenders, and which carriers bid it consistently. Lanes awarded before bid-roster capture began show no bidder data — the tenders are counted, the bidders are not inferred.

Internal identifier used throughout aclRate to match lanes across files: historic data, carrier responses, scenario outputs, and prior tenders. Format is "{source}-{destination}" based on the row's Rate Geography fields.

A lot is how procurement slices a year's freight into commercial packages — "Outbound finished goods", "Inbound raw materials", etc. A single lot can mix Rate Geographies and Cost Types (a real "outbound" lot usually contains both city-pair and postal-pair lanes). The brief produces one carrier price template Excel per lot; you send those to carriers and award them downstream. (Internally the data model still calls these rows "rate groups" — see the developer note on that term.)

When you request a re-bid on a lot, aclRate builds a deterministic email draft (lot summary, your reason, a suggested deadline) and offers it as a mailto: link or copyable text. You review, edit, and send it from your own mail client; aclRate does not transmit email or call carrier systems.

After a General Tender run, the results page shows an "Award by lot" section: one card per lot with its winning carrier, awarded spend, saving (€ and %), lane coverage, and high-confidence lane count. It projects the engine's per-shipment decisions back onto the lots you defined, so you can defend the award lot by lot — not just carrier by carrier. When a lot's best bid is more expensive than the incumbent, the card shows "incumbent retained" instead of a winner.

Rate Geography describes the geographic level at which a carrier's price applies. Common values: CITY-CITY (city pair), POSTAL-POSTAL (postal code pair), ZONE-ZONE, COUNTRY-COUNTRY. Each row in your file is classified by RG; carriers must price at the same RG. Different RGs require different source/destination columns to be populated on each row.

"Rate group" is the original internal name for the `rate_groups` table and the Python objects that store a lot's rows, RG/CT mix, and carrier-template paths. It survives in the schema and code for backward-compatibility, but every user-facing surface now says "Lot". If you are reading code or audit entries, "rate group" and "lot" refer to the same thing.

Lanes with fewer than ~12 shipments per year. These don't justify carrier-specific contract rates; they're typically left to spot procurement. Auto-detected and surfaced in the criticality breakdown.

Auto-detected from volume (top-X% by cost or ≥N shipments per year). The award builder shows a confirmation step when you override the recommended carrier on a strategic lane, since the cost of a wrong call is highest here.

Once carriers send back their filled lot templates, you load their responses on the brief's run page. A Tender Run combines the selected lots' historic data into one input and runs the pricing engine ONCE across all of them (the "General Tender" scope), so the award plan can respect cross-lot data. aclRate auto-detects which carrier each file is and which lots it prices. The result opens on the usual results page, scoped to that run. A per-lot run scope (awarding each lot independently) is planned for a future release.

When a carrier wins several lots, their combined awarded spend may cross a volume threshold they declared in their bid (a 'Volume Rebate' or 'Commitment Discount' column). aclRate's cross-lot patterns surface the resulting € synergy — e.g. 'Award Lots 1+3 together to Eurolog → 4% rebate (€11k)'. It is a commercial finding you act on, not a recomputation of the award plan; confirm the terms (and any minimum commitment) with the carrier.

Truckload (TL) means a shipment fills or rents an entire trailer. Typical for shipments above ~10,000 lb / 4500 kg. Pricing is usually flat per shipment or per mile/km. Contrast with LTL.

Less-than-Truckload (LTL) means a shipment uses only part of a trailer — the carrier consolidates multiple shippers' freight. Typical for pallets between 150 and 10,000 lb / 70 to 4500 kg. Pricing usually combines weight, freight class, and lane.

Mode is the high-level transport category. Each row in your historic file has a mode. The v1 engine supports TL and LTL; other modes (parcel, intermodal, air, sea) are flagged as unsupported during validation.

Movement describes whether a shipment is leaving your warehouse (OUTBOUND), arriving at it (INBOUND), moving between two of your sites (CROSS-TRADE / THIRD-PARTY), or being returned (RETURN). The scenario engine can optimise differently per movement.

CRITICAL severity means the scenario engine cannot produce correct results with this row. Examples: missing Total Cost, invalid Rate Geography, unsupported mode. CRITICAL issues cannot be bypassed — you must fix the source data and re-upload.

Derived fields let you compute new columns before validation runs. Example: "AllInCost = [Total Cost] * 1.05 + [Fuel Surcharge]". Whitelisted operators only: IF, AND, OR, NOT, MIN, MAX, ROUND, ABS, +, -, *, /. Formulas appear as columns in the heatmap and in the enhanced file export.

After validation runs, the workspace renders a heatmap of your sampled rows with cells coloured by issue severity. Filter by severity, carrier, mode, or month; sort by any column; export filtered view to CSV. The heatmap is sampled (typically 200 rows) — the full validation result is in the response payload.

HIGH severity means the row is processable but the result is degraded. Examples: zero Total Cost, missing carrier. You can bypass HIGH warnings with a written reason; the reason flows into the audit log and the executive PDF.

INFO severity flags rows that are valid but worth knowing about — e.g. negative fuel surcharge (legitimate credit, but unusual). No bypass needed; commit proceeds normally.

MEDIUM severity covers data-quality issues that affect edge cases. Examples: duplicate Shipment IDs, out-of-range Total Cost. Bypass-with-reason workflow is the same as HIGH.

After a clean validation pass, aclRate generates a spend profile: total cost, row count, unique lane count, currency, mode breakdown, movement breakdown, date range, and Rate-Geography distribution. The profile is the starting point for the scenario engine.

Sometimes a customer's file has dirty values — "LL" instead of "LTL", trailing spaces, inconsistent casing. Value rules let you fix these in bulk before validation: select rows in the mapping table, set a find/replace pair, applied server-side at commit time.

The trucking company, freight forwarder, or logistics provider that physically moves the shipment. aclRate's tender process is fundamentally about deciding which carrier wins which lanes.

CFI is an ADVISORY 'fit' score for encoding non-price preference. It NEVER changes the award: every lane is awarded to the real-cheapest carrier on raw price. CFI only produces a theoretical 'effective' score shown alongside raw as a tiebreaker lens. Range 70-130, default 100 (neutral). Effective Cost = Raw Cost × (200 - CFI) / 100 — CFI 110 reads as 'a 10% better fit', but you still pay, and award on, raw. The scorecard (past awards, OTIF, contract status) and AI can SUGGEST a CFI, but it applies only if you opt in per tender.

Each tenant builds up a scorecard over time as they run tenders. It tracks awards won, TMS exports completed, contract renewals, and OTIF performance. The scorecard can SUGGEST a CFI value per carrier, but the award never uses it automatically — it applies only if you opt in per tender.

For a frequently-tendered lane, consistent bidders are the carriers present in at least 80% of the tenders where that lane appeared (intermittent = 30–80%, one-time = under 30%). It tells you who is reliably competing for a lane versus who shows up occasionally. Measured at tender (run) level.

Across all the lanes a carrier responded to, the decline rate is the fraction they priced as DECLINE instead of quoting. A high decline rate signals a carrier that's selective about where it wants freight.

Auto-detected from your historic data: for each lane, the carrier that handled the most shipments in the relevant time window is the incumbent. Moving volume off the incumbent has transition risk — the system surfaces this in the award builder.

Standard logistics KPI: percentage of shipments delivered to the customer on the promised date with the full quantity. Below 95% is generally considered poor; a low OTIF can lower a carrier's SUGGESTED CFI (advisory only — it never changes the award).

Raw cost is what the carrier quoted AND what the award ranks on — the real-cheapest carrier wins every lane. Effective cost is the CFI-weighted version shown as a THEORETICAL fit lens only; it never changes the awarded carrier or €. The scoreboard shows both — raw for what you pay and award on, effective as an advisory tiebreaker. When all CFIs equal 100, raw equals effective.

A carrier's response rate is the number of your tenders they bid divided by the tenders run since their first appearance in your roster. It's a proxy denominator — precise invitation tracking is planned — so it answers "how engaged is this carrier?" rather than an exact invited-vs-responded ratio.

The buyer of freight services. In aclRate's shipper mode, the workflow is built around the shipper: uploading historic spend, evaluating carrier bids, awarding lanes. Carrier mode is a separate workflow for carriers responding to RFPs.

When you upload carrier files for a brief run, aclRate now remembers the full roster — every carrier's per-lot coverage (lanes priced and declined) and, after the award, who won. This powers carrier response/decline rates and lane consistent-bidders. It's captured only from real uploads — never guessed.

Awarding is the irreversible step of saying "this is the contract". It writes the awarded portfolio to workflow state, advances the workflow to TMS Export, and auto-snapshots the tender into the version history. The audit log records who awarded what.

Confidence comes from the price gap between the winner and the runner-up. High = winner beats runner-up by ≥8%. Medium = 3-8%. Low = <3%. Low confidence means the lane is price-tight and the carrier choice is more judgement than math.

Examples: "shipments under 100 kg should be parcel, not LTL", "Friday afternoon dispatches pay a 12% premium". Behavioural shifts are surfaced from the historic data alongside the carrier-choice opportunities; they're things to change in how you ship, not who you ship with.

If one carrier wins more than 60% of awarded spend, that's high concentration risk — a single carrier failure would disrupt most of your network. 40-60% is medium. Under 40% is low. The scoreboard flags this so you can balance cost against resilience.

On the award builder you can override the recommended carrier per lane — useful when you know things the data doesn't (a strategic relationship, a quality concern, an upcoming contract change). Each override is captured in the modified portfolio and the audit log.

After the scenario engine runs, the Opportunity Ledger lists every lane where switching carriers would save money, ranked by absolute savings. Each entry has a reason ("incumbent over-priced", "new carrier undercuts by 15%") and a confidence score (high / medium / low). The ledger is your action list.

A portfolio is the full mapping of lanes to carriers — what each carrier will haul. The three preset portfolios (recommended / single-carrier / geo-optimised) come straight from the scenario engine; the modified portfolio is your overrides on top of one of the presets.

The scenario engine generates six standard scenarios from your bids: cheapest per lane, single-carrier-wins-all, geo-optimised, etc. Each scenario allocates every lane to one carrier; you compare their savings, concentration, and coverage on the scoreboard.

Comparing a baseline tender to a current one shows, lane by lane, whether the same carrier won both, the real price movement when they did, and — when the winner changed — whether the prior winner still bid and whether the new winner is an improving bidder or a fresh entrant. It does not estimate what a losing carrier would have charged (that price isn't recorded).

Generated on demand from the Results page. Six sections: cover, baseline, scenarios compared, awarded portfolio, lane-level highlights, risk & assumptions. Designed for the CFO conversation, not the audit. Plan-gated: Basic+ only.

Inside every TMS export ZIP, a _rationale.md captures: tender summary, awarded scenario, per-carrier CFI with reasons, raw vs effective totals, lane override count, and any AI flags. This is the procurement manager's audit handout for the contract review.

After awarding, the TMS Export step packages the awarded portfolio into a ZIP your downstream TMS can ingest: per-carrier rank-1 details, contract-ready spreadsheets, and a rationale markdown doc explaining the decision (CFI map, override list, AI flags).

Exporting to your TMS from a brief run sends only the shipments in AWARDED lots. Deferred, re-bid-requested, and undecided lots are excluded (with an on-page note), so your TMS receives exactly what you committed. A legacy (non-brief) export is unchanged.