Inspiration
What it does
How we built it
Challenges we ran into
Accomplishments that we're proud of
What we learned
What's next for KindRoute
Inspiration
During severe weather freezes, neighborhood food drives, or after-school tutoring crunches, community mutual-aid organizers often assign volunteers from ad-hoc spreadsheets or group chats. First-come-first-served (FCFS) assignment sends volunteers criss-crossing neighborhoods unevenly, overloads a few helpers, and leaves resident addresses exposed in plaintext chats or third-party cloud forms. I built KindRoute as an offline civic-dispatch instrument that optimizes volunteer matching and routes deterministically, teaches how the algorithms work step by step, and seals volunteer route sheets into encrypted QR links with zero backend servers.
What it does
KindRoute is a zero-dependency, offline-capable browser web app and pure algorithmic engine:
- Exact Hungarian Matching + Capacitated Routing: Matches volunteers to resident requests using an exact
O(n^3)Hungarian assignment solver (respecting skills, urgency, travel mode, and capacity slots), merges stops with Clarke-Wright savings, and polishes every route with strictly distance-improving 2-opt edge reversals. - Interactive Offline Vector Map: Canvas-rendered neighborhood street grid displaying depots, urgency-coded resident pins, solid color-coded optimized routes, and an optional dashed FCFS baseline overlay. Hover or click any pin, depot, or route for stop-by-stop ETAs, distance, skill match, and load.
- Live Baseline Comparison Card: Displays distance saved (%), total distance, median arrival response time, workload Gini coefficient (equity), unfulfilled requests, and measured compute time (under 15 ms in browser) live on every dispatch run.
- Three Synthetic Neighborhood Presets + Deterministic Surge: Includes Oakwood Mutual Aid Groceries, Student After-School Tutoring Pod, and Winter Freeze Senior Check-In, plus a deterministic emergency surge toggle (5 urgent requests, Mulberry32 seed
4242), live request composer, and capacity sliders. - Under-the-Hood Educational Steppers: Steps visually through all six phases of the Hungarian algorithm (row reduction, column reduction, star zeros, cover columns, augmenting path, final assignment) on a cost-matrix heatmap, and steps through accepted 2-opt swaps showing exact distance shaved per reversal.
- AES-256-GCM Encrypted QR Volunteer Cards: Clicking any volunteer seals their route JSON locally using Web Crypto AES-256-GCM with a fresh 256-bit key and random 96-bit IV, renders a zero-dependency ISO/IEC 18004 QR SVG encoding
#card=...&k=..., and decrypts locally into a mobile volunteer checklist or printable route sheet with zero server storage.
How we built it
KindRoute has zero npm dependencies, zero build step, and zero runtime network requests:
src/hungarian.jsimplements exactO(n^3)Hungarian matching and emits structured trace entries for all six algorithm phases.src/routing.jsimplements Clarke-Wright savings merging, 2-opt polishing (recording both acceptedswapTrace[]and candidateevaluations[]), naive FCFS baselines, Gini workload equity, and median response latency.src/dispatch.jsandsrc/scenarios.jsconstruct constrained cost matrices and seeded synthetic neighborhood scenarios using a deterministic Mulberry32 PRNG (noMath.random()or wall-clock calls).src/crypto-card.jsandsrc/qr-svg.jsimplement pure Web Crypto AES-256-GCM encryption/decryption and a zero-dependency ISO/IEC 18004 QR matrix encoder and SVG renderer.src/map-viz.js,src/app.js, andsw.jsdeliver the interactive Canvas street map, algorithm steppers, mobile volunteer card preview, printable route sheet, and scope-limited offline service worker cache.
Challenges we ran into
Making the Hungarian and 2-opt steppers both mathematically exact and genuinely understandable meant emitting clean intermediate state at every phase without slowing down live re-solves when a coordinator drags a capacity slider. Implementing an ISO/IEC 18004 QR encoder from scratch with zero dependencies required careful Galois-field Reed-Solomon error-correction verification. Finally, handling encrypted share fragments safely meant ensuring malformed or tampered #card= links fail cleanly with clear messages and never inject HTML markup.
Accomplishments that we're proud of
- 57 automated tests pass with 0 failures (
npm test), covering 42 engine/crypto/QR tests and 15 UI-contract, offline-hygiene, security, and video-cue tests. - 100% deterministic, live-verified benchmark gains vs. FCFS (synthetic neighborhood models; 1 grid unit = 50 m):
- Oakwood Mutual Aid Groceries:
49.35%distance saved, workload Gini improved0.650 -> 0.393, median response2.757 -> 1.451 min(honestly noting 1 of 8 requests unfulfilled under capacity vs. 0 in FCFS, so distance savings compares routed distance on served requests). - Student After-School Tutoring Pod:
21.342%distance saved, Gini0.563 -> 0.313, median response5.634 -> 1.847 min(0unfulfilled). - Winter Freeze Senior Check-In:
33.196%distance saved, Gini0.756 -> 0.556, median response2.354 -> 1.284 min(0unfulfilled). - Winter Freeze + Weather Surge (seed 4242, +5 urgent requests):
40.978%distance saved, Gini0.607 -> 0.444, median response3.401 -> 1.328 min(0unfulfilled).
- Oakwood Mutual Aid Groceries:
- Zero-server privacy model: No analytics, no external map tiles, no CDN fonts, and encrypted volunteer cards whose decryption keys stay solely in the URL fragment (
#card=...&k=...).
What we learned
Equity metrics like the workload Gini coefficient matter just as much as total distance in community mutual aid, because burning out one volunteer breaks the next week's response. Pairing a real optimization engine with a step-by-step visual trace also turns an abstract O(n^3) algorithm into an interactive learning tool for students and coordinators.
What's next for KindRoute
Add optional street-network distance tables from local OpenStreetMap exports, passphrase-wrapped keys (PBKDF2 + AES-GCM) so a shared URL fragment requires a second factor if forwarded over untrusted chat, multi-shift time windows, and community-partner feedback sessions before any real-world deployment.
Honest AI Disclosure
An AI coding assistant helped implement the matching and routing algorithms, QR encoder, browser UI, tests, and documentation. I designed the mutual-aid privacy model and algorithmic verification criteria, reviewed every change, re-ran all 57 tests and benchmark numbers locally, and can explain all of the code. No AI model runs at runtime.
Built With
- css
- es-modules
- html
- html5
- javascript
- node.js
- service-worker
- svg
- web-crypto-api