Concussion Recovery Clearance Tracker

login page
login page
doctor page
dashboard page

Testing the live demo

This is deployed on Render's free tier, which has limited shell access so instead of running php artisan migrate:fresh --seed from a terminal, we exposed that exact reset as a route: visiting https://concussion-recovery-clearance-tracker.onrender.com/reset-database wipes the database back to its clean seeded state (3 demo patients at different recovery stages). If a previous tester has already advanced/broken the demo data, hit that URL first, then go to https://concussion-recovery-clearance-tracker.onrender.com/login and use one of the "Quick Select Demo Patient" cards to sign in instantly.

Inspiration

The idea started with a simple sentence: a student shouldn't have to carry their recovery paperwork between a doctor, school, and sports team.

The stakes behind that sentence are real. Returning to activity before the brain has fully recovered from a concussion is linked to Second Impact Syndrome a rare but potentially fatal condition where a second head injury occurs before the first has healed. It's part of why evidence-based protocols insist recovery happen in verified stages rather than "feeling ready" alone.

Concussion recovery isn't a single decision it's a sequence of checkpoints spread across people who rarely talk to each other directly. A doctor makes the initial diagnosis. A school has to arrange academic accommodations. A coach or athletic trainer has to clear physical activity in stages. A parent is stuck relaying updates between all three, often on paper or over scattered phone calls. When we looked into the actual clinical guidelines CDC HEADS UP's Returning to School guidance and its 6-Step Return to Play Progression, along with the PedsConcussion Living Guideline for pediatric concussion it became clear this isn't just an inconvenience. Real recovery protocols already require multi-stage, multi-approver sign-off; the paperwork problem is just that no digital system reflects that reality.

We also wanted to avoid the obvious hackathon trap: building "yet another symptom tracker" or mood journal. Recovery coordination not symptom logging was the harder and more valuable problem to solve.

What it does

Concussion Recovery Clearance Tracker is a coordination and clearance platform connecting students/parents, schools, and healthcare providers through a 4-milestone recovery journey grounded in CDC HEADS UP guidance:

Initial Assessment doctor-approved baseline diagnosis and recovery plan.
School Recovery school-approved academic accommodations (Return-to-Learn).
Graduated Physical Activity a doctor/school-approved 6-step sub-progression (CDC's Return-to-Play Progression), where each step requires being symptom-free before advancing.
Final Clearance full sign-off from doctor, school, and parent. This stage is programmatically gated: the approval link for Final Clearance is inaccessible (a hard 403) until the student has actually completed all 6 physical activity steps the rule isn't just a UI suggestion, it's enforced server-side.

Every day, the student/parent logs a free-text symptom report. An AI pipeline extracts a structured severity rating and checks for clinical danger signs but the AI never clears a patient. It only tracks, summarizes, and flags. Every actual clearance decision is made by a human, through a secure one-time approval link (no accounts needed for doctors or school staff). If a red-flag symptom is detected, the patient's progression automatically pauses or steps back, and a fresh approval link is generated for the relevant stage.

The centerpiece is the Recovery Passport a single dashboard showing the student's current milestone, physical activity step, 7-day symptom trend, active restrictions, and pending approvals, so no one has to reconstruct the story from scattered messages.

How we built it

Backend: Laravel, with UUID-keyed models for patients, symptom reports, approval links, and approval records (a full audit trail who approved what, when, and why).
AI architecture: a pluggable AiCompletionProvider interface with a Gemini implementation and a generic OpenAI-compatible implementation, so the model (Gemma, GPT, Groq, OpenRouter, etc.) can be swapped via config without touching business logic. On top of that sits a deterministic, non-AI keyword safety layer that can override an AI false negative for danger signs a guardrail the AI itself doesn't control.
Frontend: server-rendered Blade views styled with Tailwind v4 via Vite, refined for accessibility and visual clarity with the help of an AI design-critique skill. The dark theme itself is a deliberate clinical choice, not just aesthetics concussion patients are commonly sensitive to bright light and glare, so a low-contrast, low-glare interface reduces eye strain for the people actually using it while recovering.
Localization: English by default with a Bahasa Indonesia switcher; clinical status values stay in a fixed vocabulary internally regardless of displayed language, so business logic never depends on locale.
Development workflow: built inside an agentic coding IDE from structured, reviewed implementation plans rather than one-shot prompts each plan was checked against the product's own stated principles (in a living PRODUCT.md) before being approved for execution.

Challenges we ran into

The approval chain silently dead-ended. Early on, once a patient's first milestone was approved, there was no logic generating the next stage's approval links patients got permanently stuck after one approval with no way to continue. We fixed this by deriving required approver roles per milestone from a config map, generating fresh links automatically whenever a milestone advances or downgrades.
Stale approvals reappeared as false positives. After a downgrade-then-reapprove cycle, an old approval record from a previous link was incorrectly matched to a newly generated link for the same role, making the UI falsely show "already approved." The root cause was that approval records were only linked to a patient/stage/role, not to the specific link they were submitted through we added a direct foreign key so each record ties to the exact link it belongs to.
The AI misjudged clearly benign reports. A report that explicitly said "zero headache, dizziness, or visual fatigue" was still classified as "moderate" severity the model was reacting to symptom words even when they were negated. We had to make severity criteria and negation-handling explicit in the prompt instead of assuming the model would infer it.
Balancing safety against usability. It was tempting to add a one-click "approve" shortcut directly on the patient's own dashboard for demo convenience but that would have quietly broken the core safety principle that only a human, through a verified link, can approve a stage. We kept the demo shortcuts visually and structurally separate from the real patient-facing flow.

Accomplishments that we're proud of

A safety-first AI pipeline where the AI is provably incapable of clearing a patient on its own enforced in the data model and controller logic, not just a disclaimer.
A full, tamper-evident audit trail of every recovery decision, tied to the specific approval link it came from.
Clearance logic that mirrors real evidence-based protocols (CDC HEADS UP, PedsConcussion) rather than an invented step count.
A single dashboard that makes the core promise "you shouldn't have to carry your own paperwork" immediately visible rather than just claimed in a slide.

What we learned

Grounding a "clinical-sounding" product in the actual published guidelines (not assumptions) changes real design decisions down to how many recovery steps exist and who signs off on each one.
Testing a multi-role workflow end-to-end, as each role, surfaces architectural gaps that are invisible when you only test as a single user.
AI safety in a health context needs deterministic guardrails in addition to good prompting a keyword safety net caught cases a prompt alone would have missed.

What's next for Concussion Recovery Clearance Tracker

A real patient intake flow for doctors, replacing the current seeded demo data.
Stronger authentication and formal e-signature compliance for a production deployment.
Expanding the AI-provider layer with local/edge inference options for lower-resource school settings.
Deeper Return-to-Learn tooling for schools, alongside the existing Return-to-Play progression.