How the Freight Quote Tool is built

A plain-English technical write-up of your one engineering build — what it does, how it's put together, and how it was rolled out. Written so any competent developer (or your own team) could pick it up and keep running.

What it does

Enter a part number, quantity, and destination ZIP and the tool returns live UPS negotiated rates and transit times for every available service level, side by side, in seconds. One link, email-PIN login, nothing installed, no credentials sitting on anyone's desktop. A manual mode lets you enter carton weight and dimensions by hand — for one-offs, or for the small slice of the catalog (crystal) that has no dimensions in the export.

It's built for about five users on the Brightmark Imaging side, a couple dozen quotes on a busy day. It deliberately replaces the two things that defeated the original prototype: a browser extension logged in as one person, and a per-machine installer.

How it's put together

A single Cloudflare Worker serves a small web page plus a behind-the-scenes data service, all sitting behind Cloudflare Access (the email-PIN login). No installs, one URL. The pieces:

• The page — one screen with two modes: item lookup (part #, quantity, ZIP, residential/commercial toggle — it shows the carton specs it found, which you can override) and manual (enter the carton weight and dimensions yourself).
• Product lookup — a small product table loaded from your distributor-catalog export (item number → carton dimensions, weight per carton, units per carton), used to compute how many cartons an order ships in and its billable weight.
• UPS integration — the tool authenticates to UPS and calls the Rating API with the "show time in transit" option, so one request returns all services with negotiated cost and transit time. If negotiated rates ever come back missing, it shows published rates with a visible marker rather than failing silently.
• Catalog refresh — an admin-only "upload new spreadsheet" button. Re-export from the distributor catalog every week or two and upload it; the tool validates the columns before replacing anything (and tells you exactly what's wrong if the format drifted), then shows a "catalog last updated" date so it's obvious when a refresh is due.

Credentials live securely on the server side only — never in the browser, never in the source code. Access is a list of named email addresses with a roughly two-week login session; a tighter policy gates the admin upload. Adding or removing a person is a quick change to that list.

How it was rolled out

Built in a focused one-to-two-day session (Nate + Pete together). The first hour was a live-rate validation gate — confirm a real UPS negotiated-rate call works before building anything else — then the page, the catalog upload, the lookup and carton math, and the end-to-end quote flow with a UI pass. After the team uses it for real, there's one batched round of tweaks — no open-ended redesign loop.

What's deliberately out of scope (v1)

Scope was kept tight on purpose. Left out of the first version, each a deliberate call: a saved quote log / history (at ~30 seconds a quote, re-running beats storing — cheap to add later if it's missed), PO upload and parsing (that's order-entry territory), a PDF rate sheet, pricing/markup (that lives in your order-entry software), and other carriers (UPS only for now). The cut list is the scope — new ideas go to the tweak round or a separate conversation.

The full build documentation

This overview is the short version. The complete, as-delivered documents — the kind any developer would expect to inherit — are here too:

• Mini PRD — what it is, who it's for, and every in/out-of-scope decision with its provenance.
• Mini TAD — the technical architecture: the Worker, D1, Access, and the UPS integration.
• Installation — standing it up from scratch in your own Cloudflare account.
• Maintenance — access, UPS keys, the catalog format, deploys.
• Usage — the day-to-day "how do I quote" guide.
• License — your perpetual right to use and modify it.

Ownership & source

The tool runs on Cloudflare, set up to be client-owned and handed over — the account and the running service move to Keystone's own Cloudflare account whenever you're ready. The source code lives in a private repository that's yours on request: the stack is intentionally standard and boring, so any competent shop — or your own team — can pick it up and keep it running without us. You're never locked in.

For the day-to-day "how do I use it" guide (and the as-deployed access details), see Freight Quote Tool under Your Tools.