Clarity - Navigate Healthcare with Confidence

Inspiration

Healthcare shouldn't require a law degree to navigate. People skip medications because they can't afford them. They show up to out-of-network ERs not knowing it'll cost them thousands. They get medical bills with mysterious line items and no idea if they were overcharged. They don't know if their symptoms need urgent care or a pharmacy trip. The system is designed to be confusing — Clarity is designed to cut through it.

What We Built

Clarity is a full-stack AI health companion that gives everyday people the tools that used to require a healthcare advocate, a benefits specialist, and a pharmacist friend — all in one app. At its core is DoseWise, an AI agent with full context of your health profile, medications, and history.

Find Care — Describe your symptoms and DoseWise triages you instantly: urgent care, hospital, primary care, or pharmacy. The map auto-detects your location and surfaces nearby facilities with real-time hours and distance.
Insurance Analyzer — Get an AI-generated coverage score from \(0\) to \(100\), a plain-English breakdown of what your plan covers, and actionable next steps. No jargon.
Risk Engine — DoseWise calculates a personalized health risk score based on your profile and medications so you know where to focus before a problem becomes a crisis.
Bills Analyzer — Paste a medical bill. Clarity flags suspicious charges, scores fairness, and lets you ask DoseWise follow-up questions in a live Q&A — like having a billing advocate in your pocket.
Savings & Coupons — Scans your medication list against manufacturer coupons, GoodRx-style discounts, and patient assistance programs.
DoseWise Companion — A persistent health chat agent with full context of your medications, risk score, and adherence history. Ask anything. Get real answers.

How We Built It

Clarity is a full-stack TypeScript application built from scratch — no templates, no boilerplate.

Frontend — React 19 with React Router v7, bundled with Vite. Styled with Tailwind CSS using a fully custom design system: custom color palettes, shadow tokens, keyframe animations, and typography all defined in config. No third-party component libraries.

Backend — Express.js on Node.js, written entirely in TypeScript and run with tsx for zero-compile-step development. All data — users, medications, adherence logs, chat history, bills — persisted in SQLite via better-sqlite3. Every API route validated with Zod at the boundary, so malformed input never reaches business logic.

Auth — JWT-based, signed server-side, verified via custom middleware on every protected route. Passwords hashed with bcrypt. Fully stateless.

AI — DoseWise Agent — DoseWise runs on a multi-model fallback chain built with the Groq SDK and Anthropic's official SDK:

Each call is injected with the user's full health context: active medications, dosages, risk score, adherence percentage, and streak data. No single provider failure can take DoseWise down.

Maps & Location — Mapbox Search Box API handles facility discovery by care category. Location is detected automatically on page load via the browser Geolocation API, with a silent fallback to IP geolocation through ipapi.co — making Find Care work on mobile over HTTP where GPS is browser-blocked on non-HTTPS origins.

Type Safety — The entire codebase is TypeScript end-to-end. API response shapes are typed and shared across client and server. Database query results typed with generics. Zero any casts in production paths.

Challenges We Faced

Mobile location on HTTP — GPS is blocked by browsers on non-HTTPS connections. Rather than forcing HTTPS and fighting self-signed certificate warnings on local networks, we built a silent IP geolocation fallback. Clarity auto-locates on load with zero user interaction on any device.

AI reliability — Groq models hit rate limits mid-demo. The multi-model fallback chain handles this automatically — DoseWise never went offline once during the entire weekend.

Mapbox category normalization — Mapbox returns facility categories as space-separated strings ("urgent care") but our filter logic used underscore keys ("urgent_care"). A silent mismatch meant filters appeared to work but returned zero results. Fixed with a normalization function that strips separators before comparison.

Making medical data feel human — The real engineering challenge wasn't the API calls. It was designing UI that makes dense medical output — bills, EOBs, risk scores — feel actionable and trustworthy instead of like a spreadsheet.

What We Learned

Healthcare data is deeply personal — the UX has to earn trust fast. Every friction point breaks the illusion that the app is on your side. The best healthcare tool is one that already knows what you need before you ask. That's what DoseWise is built to be.