How It Works

A walkthrough of the governance logic, data model, and AI layer.

What problem does this solve?

In freight, pricing decisions happen fast — a sales rep quotes a rate, ops confirms a carrier cost, and a deal is live. Without a governance layer, two things go wrong: deals get priced below carrier cost (margin goes negative) and high-risk shippers get extended credit they can't service.

This tool runs a deterministic policy check on every deal and every shipper account in the portfolio. Deals that breach the rate card or margin floor get flagged. Shippers with high AR days or overdue ratios get flagged. The output is an action queue, routed by owner and sorted by priority.

The two-layer architecture

Deterministic policy engine

Runs on every deal and shipper on page load. No API key needed. Covers ~75% of decisions automatically by comparing prices to the rate card and checking account health metrics against thresholds.

AI triage agent (Claude)

Runs only on FLAGGED deals, via POST /api/review. Uses one tool (rate card lookup) and a 3-turn reasoning loop. Returns a structured verdict — approve exception, reject, or escalate — plus a written rationale. Requires a real Anthropic API key.

Deal checks (per deal)

Rule	What it checks	Pass	Fail
Band check	Is the proposed price within the rate card band?	Price ≥ band_lower and ≤ band_upper	Price is outside the approved corridor for this lane / tonnage / vehicle
Margin check	Is the gross margin acceptable?	Margin ≥ 5% and carrier cost > 0	Margin below 5% or negative (price below carrier cost)
Fields check	Are required fields present?	Lane, tonnage tier, vehicle type, carrier cost all populated	One or more required fields is missing

Shipper account checks (per account)

Rule	What it checks	Pass	Fail
Take rate	Is portfolio-level margin healthy?	Take rate ≥ 5% across all active deals	Account-wide margin is too thin — even if individual deals pass
AR days	Is the shipper paying on time?	Average days to pay ≤ 60	Money is sitting in receivables too long — collections risk
Overdue ratio	What share of invoices are overdue?	≤ 20% of invoice value is overdue	Too much of the book is past due — active collections needed

Health lenses

Each shipper gets three independent health scores, derived from the checks above. The portfolio view shows them as traffic lights.

Lens	Logic
Pricing Health	Red if take rate fails or more than 30% of deals are flagged. Yellow if take rate is borderline (5–7%) or some deals are flagged. Green otherwise.
Collection Health	Red if AR days > 60 or overdue ratio > 20%. Yellow if AR days > 45 or overdue ratio > 12%. Green otherwise.
Capacity Health	Red if the shipper has flagged deals and is not strategic. Yellow if strategic with flagged deals (tolerated). Green if no flagged deals.

Shipper archetypes

Each shipper is tagged with an archetype that describes the primary risk pattern. Archetypes are mutually exclusive and exhaustive.

Archetype	Description
Healthy	Passes all deal and account checks. No action required.
Volume-strategic, thin pricing	Large volume share, flagged as strategic, but portfolio take rate is below 5%. Needs Commercial Manager review — exceptions may be justified.
Collection risk, viable pricing	Pricing is fine, but AR days or overdue ratio is breached. Collections Owner action needed.
Dual risk: pricing + collection	Both pricing and collection checks fail. Highest-severity account type.
Lane-specific loss	Most deals pass, but one or more specific lanes are priced below floor. Surgical repricing needed.
Unscored — incomplete data	Missing take rate, AR days, or overdue ratio. Cannot be assessed until data is filled in.

Action queue — what the codes mean

Action	Description
Price Up	Proposed price is below the rate card band. Reprice to at least band_lower.
Take Rate Enhancement	Account-level margin is thin. Negotiate better rates across the shipper's lanes.
Volume Cap	Strategic account with deteriorating terms. Cap new bookings until pricing is fixed.
Collection Sprint	AR days or overdue ratio breached. Ops and finance to clear outstanding invoices.
Reduce Credit Terms	Credit window is too long relative to payment behaviour. Tighten terms on renewal.
Tolerate (Strategic)	Breach exists but the account is flagged strategic. Commercial Manager approved toleration.
Replace / Remove	Account fails multiple checks with no strategic justification. Off-board or replace.

Rate card model

The rate card has 96 cells: 8 lanes × 4 tonnage tiers (1–5 t, 5–10 t, 10–20 t, 20+ t) × 3 vehicle types (flatbed, curtainsider, reefer). Each cell defines:

Field	Definition
`carrier_cost_floor_usd`	Minimum carrier cost — fuel cost (PKR) + fixed costs, converted at 280 PKR/USD. A 45% fuel component means fuel price swings shift only part of the floor.
`band_lower_usd`	floor × 1.05 — minimum viable price with 5% margin
`band_upper_usd`	floor × 1.35 — ceiling above which we are over-priced vs. market

Make automation scenario

The Weekly Report tab shows what a Make scenario would send every Monday. Here is the exact module sequence to wire it up:

Schedule

Set to "Every week" → Monday → 09:00. This is the trigger — no webhook needed.

HTTP › Make a request

Method: GET. URL: https://your-domain.com/api/weekly-report. Parse response: Yes. The module returns the full JSON report object.

Router

Split into three branches — one per escalation owner. Filter condition per branch: {{2.action_queue.by_owner.`Vertical Lead`.length}} > 0 (and same for the other owners).

Gmail › Send an email (Vertical Lead branch)

To: vertical-lead@company.com. Subject: [{{2.period_label}}] Your pricing actions. Body: map {{2.markdown}} or build a custom HTML body using the by_owner array.

Gmail › Send an email (Collections Owner branch)

Same pattern — different recipient, filtered to Collections Owner items from the JSON.

Gmail › Send an email (Commercial Manager branch)

Same pattern for Commercial Manager items.

Gmail › Send summary

Final module (outside the router). Always runs. Sends the full {{2.markdown}} to yourself as the weekly governance digest.

For the demo MVP, stop at module 2 — the HTTP call returning the JSON is enough to show the pattern. Add the Router and Gmail modules when you want to send real emails.