provenance · every claim traceable
Methodology & provenance
Where every number on this site comes from, which shapes conform to Burq’s public documentation, and which mechanisms are invented — with each invention labeled and registered.
01What this is
The Escalation Desk is a demonstration cockpit: the internal console a Customer Success Engineer would work from at a multi-carrier delivery orchestration company. It shows the work directly — an account health board, three incidents triaged end to end from raw evidence (webhook logs, dispatch logs, quote data), and the customer communication each one produces.
It exists to show triage judgment on realistic evidence, not to represent any real company’s data. Everything rendered is simulated; what is real is the shape of that data — which conforms to Burq’s public API documentation — and the published integration-readiness criteria the health rubric is built on. This page is the audit trail for both claims.
02Data generation
Every delivery, webhook attempt, quote, timestamp, and dollar figure on this site is produced by one seeded generator. The PRNG is deterministic, so the same seed always yields the same dataset; the console clock is frozen at a simulated “now” (A15) so the site is a reproducible snapshot, not a live feed.
| parameter | value |
|---|---|
| seed | 20260718 |
| prng | mulberry32 |
| generator | scripts/generate-data.ts |
| generated on (real date) | 2026-07-18 |
| simulated “now” (A15) | Fri, May 8, 2026 2:00 PM ET |
| data window | 2026-02-08 → 2026-05-08 |
| total deliveries | 128,937 |
| accounts | 6 fictional enterprise accounts |
| providers | 5 invented — FleetX, CourierCo, Parcelet, DashNow, Veloway |
| webhook retry ladder (A1) | 6 attempts: +0m, +1m, +5m, +30m, +2h, +6h |
The regeneration property is the honesty mechanism: change the seed and every number on the site — including the ones inside the drafted customer emails — changes coherently. Nothing is hand-typed into the copy; pages read the generated JSON through a single data interface (src/lib/data-source.ts).
How to verify: npm run generate && npm run build — regenerate the dataset from the seed, then rebuild the static site from it.
03Schema conformance
Every API-shaped object in the dataset conforms to Burq’s public documentation: the delivery status lifecycle (all 19 documented statuses), status_history entries, the webhook envelope and its delivery, route, and batch event types, route quotes with costs as integer cents, delivery incidents with the documented status and reason enums, and reroute semantics (original delivery canceled, new delivery created under a new ID). The types in src/types/burq-schema.ts cite the exact page each shape was derived from:
- Get Order (OpenAPI) — Order and Delivery resources, the delivery status enum, status_historyhttps://burq.readme.io/reference/getorderv2
- Webhooks — event envelope, delivery/route/batch event types, signature schemehttps://burq.readme.io/reference/webhooks
- Pick Provider — RouteQuote resource; cost_of_delivery and burq_fee as integer centshttps://burq.readme.io/reference/pick-provider
- Dispatch — dispatch flow and route status progressionhttps://burq.readme.io/reference/dispatch
- Request Quote — async quote job envelopehttps://burq.readme.io/reference/request-quote
- GET Delivery Incident — delivery_incident resource with its status and reason enumshttps://burq.readme.io/v1.3.0/reference/getdeliveryincident
- Terminology and Concepts — order vs delivery vs route definitionshttps://burq.readme.io/reference/terminology-and-concepts-1
- Reroute (guide) — reroute triggers, dashboard states, max allowed price differencehttps://burq.readme.io/docs/delivery-rerouting
- API Conventions — general request/response conventionshttps://burq.readme.io/reference/api-conventions-1
One documented discrepancy (A2): the Get Order OpenAPI schema names the status_history timestamp key time, while the Webhooks guide’s JSON example shows created. Where the two public sources disagree, this project follows the versioned OpenAPI schema.
04Health rubric
The measured dimensions are not invented for this site — they come from Burq’s own published integration-readiness checklist, “Scale Delivery Operations with Smarter API Integration” (Burq blog). Its criteria: webhook retries and monitoring (“retries are configured, failures are logged, and alerts exist”), defined exception paths, provider fallback logic, and reporting readiness — on-time rate, failure rate, reroute rate, and cost by provider/zone.
Whose standard is what: the dimensions above are Burq’s published criteria. The component weights, the letter cutoffs, and the webhook thresholds are this console’s own scoring policy (A9, A10) — reasonable defaults, stated plainly, not Burq policy.
| component | weight | how measured |
|---|---|---|
| On-time rate | 30% | Share of trailing-30-day deliveries arriving within 15 minutes of the dropoff ETA quoted at dispatch (A6). |
| Failure rate | 20% | Share of deliveries ending failed or canceled rather than delivered. |
| Webhook health | 25% | Rolling 24-hour 2xx rate on the account’s endpoint: healthy ≥ 99.5%, degraded ≥ 97.0%, failing below — or immediately after 6 consecutive terminal failures (A9). |
| Reroute rate | 10% | Share of deliveries rerouted to a second provider after dispatch. |
| Cost efficiency | 15% | Cost per delivery relative to the book median of $10.74. |
Each component is scored 0–100 and the composite is the weighted sum, lettered A ≥ 85, B ≥ 75, C ≥ 65, D ≥ 55, else F (A10). The board’s grade column links back to this section.
05Ops warehouse schema
Every SQL pane on the site targets the same illustrative schema (A8): the merchant-side analytics warehouse an operator would build from webhook payloads and dispatch logs. It is not a Burq product surface — Burq does not expose a SQL interface — but it is the store that the checklist’s reporting requirements imply, and all queries against it are valid runnable-shaped Postgres.
| table | columns | captures |
|---|---|---|
| deliveries | delivery_id, order_ref, account_id, provider_id, zip, status, created_at, pickup_window_end, promised_at, delivered_at, cost_cents, basket_cents | one row per delivery: timing, outcome, cost, basket value |
| delivery_status_events | delivery_id, account_id, status, occurred_at | append-only log of every status transition |
| webhook_attempts | event_id, account_id, delivery_id, event_type, attempt, http_status, latency_ms, ts | every webhook POST, including retries, with its HTTP result |
| dispatch_attempts | order_ref, account_id, zip, provider_id, action, reason_code, price_cents, eta_minutes, ts | quote requests, returns, declines, and dispatches per provider |
| quotes | order_ref, account_id, zip, provider_id, price_cents, eta_minutes, trailing_on_time, chosen, ts | every provider quote at decision time, with the chosen one flagged |
06Assumptions register
Every mechanism in this artifact that is not documented in Burq's public docs (burq.readme.io) is listed here, with a one-line rationale. The UI never presents an assumed mechanism as documented Burq behavior; panels that depend on one carry an "illustrative — see ASSUMPTIONS.md" label citing the ID. Everything else on the site traces to a cited doc page (see /methodology).
| id | assumption | rationale |
|---|---|---|
| A1 | Webhook retry schedule: 6 attempts per event at +0s, +1m, +5m, +30m, +2h, +6h after first failure, then the event is dropped. | Burq's blog checklist confirms retries exist ("retries are configured, failures are logged") but no public page specifies counts or intervals; exponential backoff is the standard industry pattern. |
| A2 | `status_history` timestamp key is `time`. | The Get Order OpenAPI schema documents time; the Webhooks guide's JSON example shows created. Where the two public sources disagree we follow the versioned OpenAPI schema. |
| A3 | Provider decline reason codes (no_couriers_available, capacity_limit_reached, zone_not_served, vehicle_unavailable, pickup_window_unserviceable). | The docs document dispatch *error* codes but not per-provider quote-decline reasons; these are invented, modeled on common courier-API vocabulary. |
| A4 | Provider cost curves and zone-level on-time performance for the five fictional providers. | No real provider pricing or performance data is public (or used); curves are invented to make the tradeoffs in Case 3 concrete. |
| A5 | Zone = 5-digit ZIP prefix rollup. Burq quotes per route; grouping metrics by ZIP-code "zone" is an internal analytics convention of this console, not a Burq product feature. | The blog checklist calls for "cost by provider/zone" measurement but doesn't define zones. |
| A6 | On-time definition: delivered ≤ 15 minutes after the dropoff estimated_arrival_at communicated at dispatch time. | The docs expose ETAs but no public SLA definition; 15 minutes is a common last-mile grace window. |
| A7 | Late-delivery economics in Case 3: 40% of late deliveries generate a refund averaging $34; 55% generate a support contact costing $11; a routing change only counts as savings above $250/mo materiality. | Burq documents refund *outcomes* (full / partial / none) but not rates; the arithmetic is illustrative and every input is shown on screen. |
| A8 | Internal events warehouse schema (deliveries, delivery_status_events, webhook_attempts, dispatch_attempts, quotes tables) used by the SQL panes. | This is the merchant-side/ops-side analytics schema an operator would build from webhook data — it is not a Burq API surface. Documented in full on /methodology. |
| A9 | Webhook endpoint-health scoring: rolling 24h 2xx rate with grade cutoffs (healthy ≥ 99.5%, degraded ≥ 97%, failing below; failing immediately if ≥ 6 consecutive terminal failures). | The blog checklist requires webhook monitoring but defines no thresholds; cutoffs chosen so one dropped event doesn't page anyone but a dead endpoint alerts within an hour. |
| A10 | Composite health grade weights: on-time 30%, failure rate 20%, webhook health 25%, reroute rate 10%, cost efficiency 15%; letter cutoffs A ≥ 85, B ≥ 75, C ≥ 65, D ≥ 55, else F. | The four measured dimensions come from Burq's published checklist; the weights and cutoffs are this console's own scoring policy. |
| A11 | Fallback chain configuration per zone (ordered provider list with per-zone opt-outs). | The docs document auto-reroute on cancellation/delayed assignment and manual provider selection, but not a per-zone fallback-chain config; Case 2 needs one to show where the chain ends. |
| A12 | Stuck-order alert threshold: unassigned > 20 min past pickup window = stuck; ≥ 5 stuck orders in one zone within 60 min = page, and at ≥ 10 you stop re-dispatching one-by-one and call the customer. | Operator judgment values, not Burq policy; the reasoning is narrated in Case 2. |
| A13 | Delivery fee levels ($7–$24 per delivery depending on provider, zone, distance) and per-account basket values. | cost_of_delivery/burq_fee are documented as cents but no public price list exists; levels are plausible for US last-mile. |
| A14 | SLA credit exposure framed as a % of monthly delivery spend per contract tier. | Enterprise SLA credit structures are standard but account-specific; figures are illustrative. |
| A15 | Simulated clock: the dataset covers 2026-02-08 → 2026-05-08 and "now" inside the console is Friday 2026-05-08 14:00 ET — the Friday before Mother's Day, chosen so the florist incident (Case 2) is live on the board. | Fixed so the seeded generator is fully deterministic; the site is a snapshot, not a live feed. |
Generation: scripts/generate-data.ts, seed 20260718, mulberry32 PRNG. Change the seed and every number on the site — including the ones inside the drafted customer emails — regenerates coherently.
07Non-affiliation
Stated fully, because the point of this page is defensibility:
- All data on this site is simulated, produced by the seeded generator described above, and conforms to Burq’s publicly documented API schemas.
- It contains no customer data, no production data, and no data obtained from Burq systems.
- It uses no Burq brand assets — no logos, wordmarks, or visual design.
- References to Burq and links to its public documentation are nominative only: they name the documented API this simulation conforms to.
- This is an independent project, not affiliated with, endorsed by, or connected to Burq, Inc.
- All accounts, providers, contacts, and their names are fictional coinages; any resemblance to real businesses or people — in delivery or any other industry — is coincidental and unintentional.