ClearCareAI

Architecture

Inspiration

250 million insurance claims are denied every year in the United States. Behind every denial is a specific policy rule — buried in a 300-page document that no one reads. When a patient gets a denial letter, they receive a code like CO-4 and nothing else.

Patients don't know what it means. Clinicians spend hours they don't have decoding it. And when someone finally writes an appeal, it goes out from a generic email address and gets deprioritized or ignored.

I built ClearCare because the information gap between insurers and patients is enormous — and solvable. The policy rule exists. The explanation exists. It just needs to be surfaced and communicated clearly to the right person, in the right language.

What it does

ClearCare is a healthcare decision intelligence system with two users: clinicians and patients.

For clinicians: Upload an insurance policy PDF once. ClearCare chunks, embeds, and indexes every rule into a vector store. When a patient gets a denial, paste the code — ClearCare retrieves the exact matching rule using semantic search and generates a clinical-language explanation with section citations, confidence score, and recommended next actions.

For patients: Enter the denial code in plain English. ClearCare explains what happened, what your rights are, and what to do next — in plain English, with numbered steps. No medical jargon.

For both: ClearCare drafts an appeal letter. Then, using Auth0 Token Vault, it sends that letter from the patient's own Gmail account — not a generic sender. An appeal from john.smith@gmail.com has real identity and legal standing. That changes whether it gets read.

It also adds the appeal deadline to the patient's Google Calendar so nothing gets missed.

How we built it

Backend: FastAPI on Python 3.11, deployed on Render. No LangChain — the RAG pipeline is built from scratch. Policy PDFs are chunked at 800 words with 100-word overlap, embedded via the Gemini API, and stored in ChromaDB with cosine similarity search.

Dual-audience generation: One Gemini call with a structured JSON schema produces two outputs simultaneously — clinical language for the doctor, plain English for the patient. Not two API calls. One carefully engineered prompt.

Hallucination guard: After Gemini generates an explanation, we extract verifiable claims (section numbers, dollar amounts, day counts) using regex and check each against the source chunks. If less than 70% of claims verify, the response is flagged. The AI is not trusted blindly.

PHI stripping: Before any text reaches an external API, regex patterns strip SSNs, phone numbers, dates of birth, medical record numbers, and names. Clean text goes to Gemini. The original never leaves our server.

Auth0 Token Vault: When a patient connects their Google account once through Auth0 Universal Login, Token Vault stores the token. When ClearCare sends an appeal, it exchanges the user's Auth0 access token for their Google token via the Token Vault grant. The letter goes out from the patient's real Gmail. ClearCare never stores a single Google credential.

Frontend: React 18 + Vite on Netlify. Role-based access enforced at every layer — org code on signup, JWT role claim, FastAPI dependency, and frontend rendering. Patients cannot reach clinical endpoints even with a valid token.

Observability: Langfuse traces every agent call with input, output, confidence score, latency, and token count. Every AI decision is auditable.

Challenges we ran into

Auth0 Token Vault was the hardest piece. The documentation for the Token Vault grant flow is sparse, and getting the custom API client grant type correctly configured — separate from the main web app client — took significant debugging. Once it worked, it replaced what would have been hundreds of lines of OAuth plumbing.

Hallucination guard design was an interesting challenge. LLMs don't fail loudly — they generate confidently wrong answers. We had to decide what "verifiable" means in this context, build the extraction logic, and decide on a threshold (70%) that was strict enough to be useful without rejecting too many valid responses.

PHI stripping with regex has inherent limits. Regex catches structured identifiers (SSNs, MRNs, phone numbers) reliably, but misses contextual identifiers. We documented this as a known limitation rather than pretend it's solved — the production path is Microsoft Presidio.

ChromaDB on Render resets on every redeploy since the free tier has no persistent disk. In production, this would be Pinecone. For the demo, we worked around it by keeping the policy indexed in a stable deployment.

Accomplishments that we're proud of

Built a full RAG pipeline from scratch — no LangChain, no abstraction layers hiding the decisions
The dual-audience generation actually works well: the same denial code produces meaningfully different explanations depending on whether you're a clinician or a patient
The hallucination guard catches real errors — in testing, it flagged responses where Gemini cited section numbers that didn't exist in the uploaded policy
Auth0 Token Vault replaced what would have been an entire OAuth microservice
Role-based separation enforced at every layer, not just the frontend

What we learned

Token Vault is genuinely transformative for applications that need to act on behalf of users with third-party APIs. The mental model shift — from "store and manage tokens yourself" to "exchange at call time" — changes what's feasible to build solo.

I also learned that hallucination guards are more important in healthcare than in most domains, and that "check the AI's work against its sources" is a concrete, implementable pattern, not just a vague principle.

Building dual-audience generation taught me how much prompt structure matters. The same model, same information, same request — but a different JSON schema and role instruction produces dramatically different output quality.

What's next for ClearCare

OCR support for scanned PDFs via Google Vision API — right now only text-extractable PDFs work
Microsoft Presidio for NLP-based PHI stripping instead of regex
Per-organization ChromaDB namespacing so multiple clinics can use the same instance without data bleed
Gemini structured output mode to replace the regex JSON cleanup
Deadline tracking dashboard — right now we add one calendar event, but patients often have multiple active appeals with different deadlines