Medical Bill Auditor/Analyzer - Project Story

The Inspiration

Medical billing is intentionally confusing. Americans lose over $200 billion annually to billing errors and overcharges. Most people just pay their bills because they don't know how to question them. I wanted to build a tool that gives everyone the power of an expert auditor – making medical billing transparent and fair.

What I Learned

1. AI is Accessible

I didn't need expensive infrastructure. OpenRouter provides free access to powerful models like Mistral 7B and Google Gemini Flash. With just a few lines of code, I could turn complex medical bills into structured, meaningful analysis.

2. Simplicity Wins

HTMX completely changed how I think about frontend development. Without React, webpack, or npm build tools, I built a dynamic, responsive UI that feels modern but stays simple. Server-side rendering with Jinja2 gave me the best of both worlds.

3. PDF Parsing is Tricky

Medical bills come in many formats – some have text, others are scanned images, and many have complex layouts. I learned to implement multiple extraction methods: standard text extraction, layout-aware parsing, and OCR fallback.

4. Prompt Engineering is Magic

The AI's performance depends entirely on how you structure your prompts. Detailed, specific instructions guide the model to return exactly what you need – eliminating complex parsing logic.

How I Built It

Architecture

The project follows a clean separation of concerns:

Backend: FastAPI handles API routes, PDF processing, and AI integration. It accepts uploaded PDFs, extracts text, and calls OpenRouter's AI models for analysis.

Frontend: HTMX + Tailwind CSS provides a beautiful, responsive UI without JavaScript frameworks. HTMX handles dynamic updates, while Tailwind delivers a modern dark theme with glass-morphism effects.

AI Layer: OpenRouter provides access to free AI models (Mistral 7B, Google Gemini Flash, Meta Llama). The AI analyzes CPT codes, identifies errors, calculates savings, and generates dispute letters.

Development Process

Designed the architecture focusing on FastAPI for the backend and HTMX for the frontend.
Built the PDF processing pipeline with PyPDF and OCR fallback.
Integrated OpenRouter AI with structured prompts for consistent JSON responses.
Created a stunning dark-themed UI with glass-morphism and smooth animations.
Added real-time updates with HTMX for seamless user experience.
Tested extensively with various PDF formats and iterated on AI prompts.

Challenges I Faced

Challenge 1: Environment Variables

Problem: .env file wouldn't load due to encoding issues.
Solution: Forced loading with absolute path and proper encoding (utf-8-sig).

Challenge 2: API Authentication

Problem: "Missing Authentication Header" error.
Solution: Fixed .env loading and temporarily hardcoded the key for testing.

Challenge 3: PDF Extraction

Problem: "Could not read Boolean object" error with PyPDF.
Solution: Implemented multiple extraction methods (standard, layout, and OCR).

Challenge 4: Model Availability

Problem: Selected OpenRouter model was deprecated (404 error).
Solution: Switched to openrouter/free which auto-routes to available models.

Challenge 5: Git Push

Problem: GitHub branch protection blocked direct pushes.
Solution: Created a feature branch and used a pull request.

The Result

Medical Bill Auditor is now a fully functional application that:

Accepts PDF uploads via drag-and-drop
Extracts text from medical bills
Analyzes CPT codes for overcharges
Calculates potential savings
Generates professional dispute letters
Copies letters with one click

It's fast, free, and works for everyone.

What's Next

User authentication and audit history
Database integration for logs
Export results as PDF
Multi-payer support
Batch processing
Mobile app development
UI improvent

Final Thoughts

Medical Bill Auditor proves that AI doesn't have to be complicated or expensive. With OpenRouter, FastAPI, and HTMX, you can build powerful applications that solve real problems. The best part? This project helps people save real money on medical bills – making healthcare more accessible and fair for everyone. Also this is our first ever hackathon.