One decision per lead: which buyer gets it. Everything's on this page — the full decision map (every branch and layer a lead passes through, below), the live step-through where you watch the queue reorder lead by lead, and the calculator where you drag weights and coverage and watch the distribution respond. Start with the map, then drive the logic yourself.
flowchart TB start(["Lead submitted
(zip + offer type)"]):::start subgraph L["1 · LOCATE"] direction TB county["Derive county from ZIP
(USPS crosswalk)"]:::proc group["Place in that county's GROUP"]:::proc end subgraph F["2 · FILTER — eligibility gate"] direction TB gate[/"Keep only buyers passing ALL:
active · serves zip · buys offer · credits ≥ price
· under caps · in schedule · filters"/]:::gate elig{"Any eligible
buyers?"}:::dec end subgraph R["3 · RANK — pacing deficit (the brain)"] direction TB over{"Manual override
buyer eligible?"}:::dec cap["Cap targets at coverage ceiling
effShare = waterfill(weight, ceiling)"]:::proc calc["Prospective deficit per buyer:
+= effShare each lead · −1 on win
(new buyer starts at par)"]:::proc pin{"Buyer pinned an
offer mix?"}:::dec smin["Offer token-bucket guard:
keep if EV ≤ mix·received + burst"]:::proc sdef["(no offer cap)"]:::proc rank["Pick MAX NORMALIZED deficit
deficit ÷ effShare
ties: longest-wait ↑ · weight ↓ · id"]:::proc win["Winner = #1"]:::proc end house(["House-buyer fallback
(never dropped)"]):::term assign(["Assign + debit
(atomic · fully logged)"]):::assign start --> county --> group --> gate --> elig elig -- "No" --> house elig -- "Yes" --> over over -- "Yes (force)" --> win over -- "No" --> cap --> calc --> pin pin -- "Yes" --> smin --> rank pin -- "No" --> sdef --> rank rank --> win --> assign assign -. "−1 winner · += effShare each lead
(prospective, per-buyer epoch)" .-> calc classDef start fill:#12294a,stroke:#2f81f7,stroke-width:2px,color:#eaf1fb; classDef proc fill:#16233b,stroke:#334867,color:#eaf1fb; classDef dec fill:#2a2416,stroke:#ffb020,stroke-width:2px,color:#ffe6bd; classDef gate fill:#1c2a12,stroke:#c6f24e,stroke-width:2px,color:#eef3d9; classDef assign fill:#123227,stroke:#3ad29f,stroke-width:2px,color:#d6f7ec; classDef term fill:#2c1620,stroke:#ff5c72,stroke-width:2px,color:#ffd7dd;
The queue is the priority. A buyer that can't get leads (small coverage) sees its deficit grow, floating it to the top — so it wins its next eligible lead automatically. No manual "priority spot."
| Check | Passes when… | Notes |
|---|---|---|
| Active | buyer + their routing profile are on, not paused | a paused buyer is invisible |
| Zip (geo) | a coverage row matches the lead's zip (exact / prefix / region) | zero coverage rows = covers nothing |
| Offer | buyer buys this service type & has a price row | missing price = ineligible (not a free lead) |
| Credits | prepaid balance ≥ the lead's price | prepay model, no overdraft |
| Caps | under daily / weekly / monthly limit | buyer-local calendar windows |
| Schedule | now is inside the buyer's hours/days | bad timezone fails closed |
| Filters | every per-buyer rule passes (homeowner-only, etc.) | AND of all rules |
| Buyer | Weight | Zips | Received | Target | Deficit | Eligible? |
|---|
Picks by a fixed weight % every lead, independently. It never notices Voltwell falling behind because its zips are rare — so Voltwell gets ~1–2% instead of its 16%. A "priority spot" is the manual band-aid for this blindness.
Every lead Voltwell can't get grows its deficit, floating it to the top. The next lead in its 18 zips → Voltwell is #1 and wins. It catches up to the ceiling of what's physically available, automatically. The queue is the priority.
Why not just split into two queues?
Because a buyer who accepts both panel and EV would then sit in both and pull double volume vs a single-offer buyer next in line. Keeping one queue with a per-offer cap preserves each buyer's total share while still honoring their mix. The simulator below has an offer-mix toggle so you can see it.
Equal deficit → longest since last lead (round-robin) → bigger weight → id. Fully deterministic; shadow-mode reproduces exactly.
Empty window → everyone deficit 0 → falls back to round-robin by weight. Converges within ~2× the buyer count.
No coverage / all capped / all out of credits → house-buyer fallback. A lead is never dropped.
"Feed buyer X everything it can take until I turn it off." Force-assigns any lead they're eligible for; the rest fall through to the queue.
Set a buyer's weight above their budget share → the deficit naturally over-delivers to them. (Point Loma at 52%.)
A buyer can't win more than their zips produce. If Voltwell's zips carry 10%, 10% is success — 16% is physically impossible.
Two leads racing for the same #1 are serialized by the atomic assign; the loser re-ranks against fresh counts.
Runs beside LeadByte logging what it would do, ≥2 weeks, before any cutover. Zero risk to live routing.
The share a low-coverage buyer can't absorb flows to the all-county catch-all by weight. Nothing is stranded.
deficit ÷ effShare), not equal-per-buyer. Matthew + both reviewers agreed. raw stays only as a config escape hatch.received (the opportunity was consumed; else disputing becomes a queue-jump lever). Confirm.buyer_routing_profiles.weight (already in the schema), county groups
ride the existing region coverage, every decision writes a full trace to routing_decisions.
The only real change is the ranking layer. Algorithm family: Weighted Deficit Round Robin (the fair-share
scheduler that runs internet routers), with a hard eligibility gate. This page's step-through and simulator run
the exact logic from sim.mjs.