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.js implements exact O(n^3) Hungarian matching and emits structured trace entries for all six algorithm phases.
  • src/routing.js implements Clarke-Wright savings merging, 2-opt polishing (recording both accepted swapTrace[] and candidate evaluations[]), naive FCFS baselines, Gini workload equity, and median response latency.
  • src/dispatch.js and src/scenarios.js construct constrained cost matrices and seeded synthetic neighborhood scenarios using a deterministic Mulberry32 PRNG (no Math.random() or wall-clock calls).
  • src/crypto-card.js and src/qr-svg.js implement 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, and sw.js deliver 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 improved 0.650 -> 0.393, median response 2.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, Gini 0.563 -> 0.313, median response 5.634 -> 1.847 min (0 unfulfilled).
    • Winter Freeze Senior Check-In: 33.196% distance saved, Gini 0.756 -> 0.556, median response 2.354 -> 1.284 min (0 unfulfilled).
    • Winter Freeze + Weather Surge (seed 4242, +5 urgent requests): 40.978% distance saved, Gini 0.607 -> 0.444, median response 3.401 -> 1.328 min (0 unfulfilled).
  • 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

Share this project:

Updates

Submission history