Inspiration

Every community kitchen, shelter and weekend event runs into the same question: who covers which shift? The hard part is rarely just filling seats. It is explaining the outcome: why is this seat still open, and what would actually fix it? Tools that can answer that usually want an account, a subscription and your volunteers' personal data on someone else's server. FairFlow is my answer: a workbench that solves the roster and shows its reasoning, entirely in the browser.

What it does

  • Describe volunteers (names, roles, personal shift limits), shifts (role, seats) and an availability matrix (off / available / preferred).
  • The solver maximises filled seats within that model. Coverage is never traded away for any other goal.
  • When a seat stays open, FairFlow says why in plain language: who is qualified, who is already at their limit, and which change would fix it (raise a named person's limit by one, or add one more qualified volunteer).
  • Compare modes puts preference optimization and fairness optimization side by side: the same maximised coverage on the shipped scenarios, a different distribution of load, with the Gini coefficient reported so the effect is observed, not assumed.
  • A flow view draws the actual assignment graph and highlights the binding bottleneck: the minimum cut of the network.
  • Pick up where you left off: the working roster autosaves in the browser, and the exported scenario JSON imports back through a validating importer. A rejected file changes nothing, and a successful import keeps your previous work as a recovery roster.
  • Reuse last week's plan: save the current roster, edits included, as a named copy and re-solve it next week instead of rebuilding.
  • Time-conflict warnings: a heuristic layer parses recognisable slot labels (overnight ranges included) and warns when one volunteer is assigned to overlapping shifts. Pairs it cannot parse are listed as unchecked, so no warning never reads as "no clash". It never blocks an assignment.
  • Exports: roster CSV, a full audit report with a method note, scenario JSON, and a print-ready roster handout for the coordinator.

Everything runs locally. No account, no server, no tracking; volunteer data never leaves the device. Export and import keep work moving between devices.

How I built it

Plain HTML, CSS and JavaScript with zero runtime dependencies and no build step. The engine is a min-cost max-flow solver written from scratch: successive shortest paths with Johnson potentials over a hand-written binary heap. Fairness is modeled by splitting each volunteer's source arc into parallel unit arcs with increasing costs (w, 2w, 3w...), so the cost model encourages spreading work instead of stacking it, while max flow keeps coverage maximal. Unfilled-slot explanations are read off the minimum cut in the residual graph. A separate planner module owns slot-label parsing, overlap warnings, import validation and roster duplication, so every non-solver rule is unit-tested outside the page.

Correctness is tested, not assumed: a brute-force oracle exhaustively solves 400 small random instances and the engine must match its optimum on every one, in both modes (800/800 agreements). The engine and planner suites hold 209 checks, and a Playwright suite of 57 checks covers the UI, including persistence, import and the conflict warnings; it was run against the deployed site as well.

Challenges

Getting honest explanations out of the graph: "seat unfilled" has several structurally different causes, and the wording had to be precise enough to act on without overclaiming. The min-cut analysis gives the binding constraints; turning those into a specific, correct suggestion (raise X's limit vs add a qualified volunteer) took the most iteration.

Accomplishments

A solver that is verified against a brute-force oracle, explanations a non-technical coordinator can read, and a comparison view that makes a real trade-off (preference vs fairness) tangible instead of rhetorical.

What I learned

How much of scheduling is explanation. Also: convex fairness costs map cleanly onto classic linear-cost flow via unit arcs, which kept the algorithm standard and testable.

Honest limits

The solver validates the supported model, not every real-world scheduling rule: shift times remain labels, overlapping times are warned about but never enforced, labels the parser cannot read are reported as unchecked rather than assumed safe, and there are no rest rules or legal limits. Fairness here means this particular cost model; the app says so. Data lives in the browser by design, with JSON export/import as the backup path. All example data is synthetic.

AI assistance disclosure

Built with AI assistance: the author asked for this project and its upgrades and set the honesty rules for how the work is described. Within that request, an AI assistant (Instinct) selected the technical scope, implemented the application source, ran the test suites, and prepared the supporting material during the hackathon build and edit window. The demo narration uses an AI text-to-speech voice. The app itself ships zero runtime libraries and makes no network calls. Tooling: Node.js test suites, Playwright + Chrome for UI tests and screen capture, ffmpeg for video composition. Every algorithmic claim in the video and this page was verified against the oracle and UI test suites.

What's next

A mobile-first layout. Time-overlap warnings and reusable rosters shipped during the edit window and are live now.

Share this project:

Updates

Submission history