LumaLoad — Recovery Load OS

LumaLoad maps the cognitive, sensory, physical and emotional demand hidden inside a concussion recovery day, behind deterministic clinical safety guardrails and verified CDC evidence.

Comment

Inspiration

Concussion guidance has moved on from "sit in a dark room". Current CDC and Amsterdam-consensus advice is relative rest, then a gradual, symptom-limited return to ordinary life. Concussion Alliance is blunter still: do not lie in a darkened room for extended periods, even in the first 24–48 hours.

But "pace yourself" is not a plan. A real day stacks demand that nobody can see: a lecture, a 90-minute laptop block, a loud cafeteria, a crowded shop. Those are different kinds of load, and a person recovering from a concussion feels them differently. Nothing tells you which hour of your Tuesday is going to cost you.

We also kept running into a second gap. The CDC lists anxiety, irritability, sadness and sleep disruption as symptoms of concussion — not side-effects, symptoms. Yet recovery tools treat mood as an afterthought. So a bad night's sleep and a low mood don't just feel worse; they lower the ceiling on everything else you do that day.

What it does

LumaLoad turns a day into a Recovery Load Canvas.

  1. Check-in — eight symptom sliders (headache, dizziness, light/noise, fogginess, fatigue, mood, anxiety, sleep quality), a clinician-contact question, and a deterministic CDC danger-sign screen. No account, no sign-up, nothing stored on a server.
  2. Canvas — build your day from 17 activity types with 7 environment modifiers (screen, crowded, loud, bright, travel, outdoors, quiet). Add, edit and delete events; the visualisation redraws live.
  3. The Load Ribbon — three independent strands (cognitive, sensory, physical), each with its own centreline and thickness, drawn across the day over a Capacity Baseline computed from sleep, mood, anxiety and fatigue. Where demand breaks through that floor, a cross-hatched pressure point appears. Maya, our synthetic day-5 student, has a capacity of 0.74 and four pressure points.
  4. The Plan — at most five changes, only ever to low-risk activities, each carrying a citation, a confidence level, the demand type it relieves, and "what we inferred / what we do not know".
  5. The Glass Box — the full seven-stage execution trace with real millisecond timings: what ran deterministically, what a model touched, what the verifier deleted and why.

What it refuses to do is the point. It does not diagnose, score severity, estimate a recovery date, or clear anyone for sport or driving. Contact sport and driving render as locked cards citing CDC Returning to Sports, and no recommendation may target them — enforced by a test, not a promise.

How we built it

A single Next.js 15 app (App Router, TypeScript strict) on Vercel. Zod contracts at every boundary. Hand-written CSS on design tokens — no Tailwind, no component library — and the Load Ribbon is custom SVG with Catmull-Rom smoothing at 5-minute resolution, not a charting library.

The pipeline has seven stages: sanitize → safety_check → retrieve_evidence → structure_activities → compose_plan → verify_plan → build_trace. Retrieval and structuring run in parallel. The Gemini provider cascades 3.8-flash → 3.5-flash → 2.5-flash → 3.5-flash-lite → 2.5-flash-lite and falls back to a deterministic rules engine.

The evidence registry is 24 curated chunks across six sources, every URL verified live. The model can only emit evidence ids — never URLs — and the server resolves them. An id outside the registry means the recommendation is deleted.

Responsible AI

We separated medical safety from generative AI completely.

  • Danger signs are deterministic and run first. A test spies on the model provider and asserts it is never invoked when the gate halts.
  • Citations are mandatory. No registry evidence id, no recommendation. The verifier also checks the evidence's allowedUses actually covers the claim.
  • Banned clinical language is enforced in code — "you are safe", "cleared to", "return to sport", "diagnos…", "prescri…" — and any recommendation containing one is deleted.
  • Restricted activities are untouchable. A test asserts no recommendation ever targets one.
  • PII is stripped before any model call, and logs carry no symptoms, labels, prompts or responses.
  • Nothing is persisted server-side. Session state lives in the browser.
  • Prompt injection: retrieved evidence is fenced as data, and the registry check means injected text cannot introduce a citation.

And the part we are most willing to be judged on: our free-tier model quota ran out during the build window. All five models in the cascade failed — three returned 429, one timed out, and gemini-2.5-flash-lite is deprecated and 404s for new users. So the app says exactly that, on screen:

"Pre-computed with LumaLoad's deterministic rules engine · 4 Sep 2026. Free-tier model quota was exhausted during the build window. The pipeline, evidence grounding, verification and safety gates are unchanged — none of them depend on a model."

We had a version that labelled that output as Gemini. We caught it and removed it, and added a guard test that fails the build if a fixture claims a model that did not run. An honest fallback is a feature; a fabricated model attribution is a defect.

Research foundation

  • CDC — Symptoms of Mild TBI and Concussion
  • CDC — Recovering From a Mild TBI or Concussion
  • CDC HEADS UP — Returning to School After a Concussion
  • CDC HEADS UP — Returning to Sports After a Concussion
  • BJSM — Amsterdam 2022 consensus statement on concussion in sport
  • Concussion Alliance — Recovery Guide

Challenges we ran into

Free-tier quota is 20 requests per day, per model — and it resets at midnight Pacific, which fell after our deadline. That forced a real architectural decision rather than a workaround: cut model calls per analysis, cascade across models, pre-compute the demo days, and label provenance honestly.

The signature visual took three attempts. Version one was a stacked area chart with hard step edges — three colours fused into one mass, which defeats the entire "not a single number" thesis. It only worked once each strand got its own centreline, its own thickness, multiply blending, and spline smoothing.

Being wrong in public. Our own status reports twice claimed things were live that were not — including the mislabelled model provenance. Every claim in this submission was verified against the deployed URL and the raw repo files, not against a summary.

Accomplishments

Accessibility 100/100 on all five routes. 41 tests passing, including ones that assert the model is never called behind a halted safety gate and that no recommendation can target a restricted activity. Zero horizontal overflow at 390 / 768 / 1024 / 1440. And a visualisation that reads in greyscale, because colour alone should never carry clinical meaning.

What we learned

That the honest version of a system is usually the more defensible one. When the model quota died, the temptation was to hide it. Saying it plainly turned out to be the strongest thing on the Responsible AI screen — because it proves the safety, evidence and boundary layers were never depending on a model in the first place.

What's next

Everything beyond this point needs clinical collaboration before anyone should treat a LumaLoad number as decision support: clinician-reviewed accommodation templates, validated outcome measures, optional encrypted longitudinal tracking, school and workplace sharing, and formal usability studies with people actually in recovery.

Built With

Share this project:

Updates

Submission history