First Mile Configurator
A prototype/POC wizard that captures a client's first-mile return configuration — return service,
return label, first-mile destination, carrier, lane type and contract for each pickup country — and
emits a canonical JSON payload describing every lane.
It is a single-page vanilla HTML/JS/CSS app (no framework, no build step). All frontend code lives
in one file: index.html. Two tiny Vercel serverless functions provide a shared
backend for saving flows and collecting feedback — there is no database or server framework.
The app hosts several UI variants explored during the POC. The two current focal points are
Tabular 2 and Manisha Tabular; Tabular 1 and the earlier versions remain accessible.
Ownership & contact
Maintained by Gaurav Dewani — [email protected].
Reviewing the code or hit an issue? Please reach out to Gaurav directly.
Live URL
Repos
The same code lives in two places (GitHub is primary / auto-deploys; Bitbucket is the company mirror):
A GitHub Action mirrors every push to main on GitHub over to Bitbucket, so both stay in sync
regardless of who pushes (see .github/workflows/mirror-to-bitbucket.yml).
Repo layout
firstmile-configurator/
├─ index.html ← ⭐ ALL frontend code (data, state, every variant, JSON builders)
├─ rebound-icon.png ← Favicon / brand mark
├─ api/ ← Vercel serverless functions (Node)
│ ├─ flows.js ← Save/load "flows" — GET/POST/DELETE over a private GitHub Gist datastore
│ └─ feedback.js ← In-app feedback widget → files a labelled GitHub issue
├─ .claude/launch.json ← Local dev server config (npx serve on :3456)
├─ .github/workflows/ ← GitHub Action: mirror main → Bitbucket
├─ docs/handover.md ← Engineering handover doc
└─ .gitignore ← excludes .vercel/, node_modules/, .DS_Store
Variants
All variants share the same design system and the same startVariant(v) → client-name modal → wizard flow.
They are selected from the landing page. state.variant holds the active one.
| Key | Name | What it is |
|---|
M | MyRebound FM MVP + Routing Decisions | Copy of L without Postal Product / Parcel Type / Legacy Sync, plus a Destination column, editable Warehouse profiles (seeded Local + ERC) and an Add routing decisions wizard: pick DTW (profile) / DTR (client facility) / DTP (partner), tick region → country → lane in a diff view (overrides flagged amber), submit to apply. (Newest.) |
G | Tabular 2 | Single-select return service & label → one row per country; a "+" adds extra configs per country. (Current hero.) |
F | Manisha Tabular | Tabular with a Postal Product column and a Custom Routing Rules section. |
E | Tabular 1 | Multi-select return service & label → one row per country × service×label combo; fine-tune each lane. |
D | Client Preferences (v4) | Guided preference questionnaire that derives every lane. Has its own JSON builder. |
C | Inline Grid (v3) | All lanes in one table with inline dropdowns. |
B | Carrier-First Bulk (v2) | Pick a carrier first, then assign lanes to it. |
A | Lane-by-Lane Stepper (v1) | Configure each country one at a time. |
Variants E / F / G ("tabular") share one code path in renderVariantE() and one state object
(tabState), branching on state.variant. Variant D uses prefState; variants A / B / C use
state.lanes.
Local development
No build step. Any static file server works. From the repo root:
npx serve -l 3456 .
# then open http://localhost:3456
The /api/* serverless functions do not run under a plain static server — locally, "Save flow"
and the feedback widget fall back to graceful empty/offline states. To exercise the backend, use the
deployed site (or vercel dev).
Deployment
Wired to the Vercel project firstmile-myrebound. Two ways deploys happen:
- Auto (preferred): push to
main on GitHub → Vercel's Git integration builds & deploys.
- Manual CLI: from the repo root,
vercel --prod --yes (needs vercel login + the gitignored
.vercel/project.json linking this dir to the project).
The api/ folder is auto-detected by Vercel as serverless functions (Node runtime) — no config needed.
Backend env var
Both functions reuse one Vercel Production env var:
| Variable | What it does |
|---|
FEEDBACK_GH_TOKEN | A GitHub token with gist + repo scope. flows.js uses the gist scope for the saved-flows datastore; feedback.js uses the repo scope to open issues. |
Data stores (no database)
| Feature | Store | Where |
|---|
| Saved flows | A single private GitHub Gist (flows.json), auto-created and found by description marker | api/flows.js |
| Feedback | GitHub issues labelled feedback on the GitHub repo | api/feedback.js |
Both are deliberately lightweight (POC). See docs/handover.md for schemas and how
to migrate to a real backend.
Known caveats
- Prototype, not production. No auth, no versioning/audit, single-file frontend. The "backend" is two
serverless shims over GitHub (gist + issues), chosen for zero infra.
- Local
/api doesn't run under npx serve — test the backend against the deployed site.
- Two active authors push to
main. Always git pull before starting work; the GitHub→Bitbucket
mirror keeps the company copy current automatically.
- Vercel CLI token expires periodically — re-run
vercel login before manual deploys.
More context
See docs/handover.md for the full engineering handover: the variant/state model,
the carrier-service-selector concept, JSON schemas, backend endpoints, deployment, and out-of-scope
callouts.
