GitHub - hackfest-dev/HF26-10: Hackfest26 repository for T10

🏥 Patient Zero: Autonomous Medical Billing Advocate

Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.

✨ Core Features

📥 Autopilot Inbox Scanning: Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
🕵️‍♂️ The Master Scribe (AI Audit Engine): Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
⚔️ Automated Agent Deployment:
- Primary (Web): Uses Playwright to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
- Fallback (Voice): Uses Twilio to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
⚡ Real-Time Dashboard: Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
🛡️ Dynamic Insurance Vault: A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
📁 Manual Override: A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using multer.

🛠️ Tech Stack

Frontend (Client)

React (Vite)
Tailwind CSS (Styling & Responsive UI)
Framer Motion (Fluid animations and micro-interactions)
Lucide React (Modern iconography)
React Router (Navigation)

Backend (Server)

Node.js & Express.js (API Routing & Middleware)
Multer (In-memory multipart/form-data handling for PDF uploads)
Googleapis (Gmail API integration)
Playwright (Headless browser automation for web disputes)
Twilio SDK (Telephony and automated voice calls)
Google Gemini API (Document extraction and Master Scribe RAG pipeline)

Database & Auth

Supabase (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)

🚀 Getting Started

Prerequisites

Node.js (v18 or higher)
A Supabase Project
Google Cloud Console Project (with Gmail API enabled and OAuth 2.0 credentials)
Twilio Account (Account SID, Auth Token, and a Twilio Phone Number)
Google Gemini API Key

Installation

Clone the repository

README.md generated successfully.
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents. """

with open("README.md", "w", encoding="utf-8") as f: f.write(readme_content)

print("README.md generated successfully.")

Your Markdown file is ready
[file-tag: code-generated-file-0-1776554008595075563]
Here is the complete, perfectly formatted `README.md` text for you to easily copy and paste into your project repository. ```markdown
# 🏥 Patient Zero: Autonomous Medical Billing Advocate
Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.
---
## ✨ Core Features
* **📥 Autopilot Inbox Scanning:** Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
* **🕵️‍♂️ The Master Scribe (AI Audit Engine):** Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
* **⚔️ Automated Agent Deployment:**
* **Primary (Web):** Uses **Playwright** to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
* **Fallback (Voice):** Uses **Twilio** to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
* **⚡ Real-Time Dashboard:** Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
* **🛡️ Dynamic Insurance Vault:** A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
* **📁 Manual Override:** A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using `multer`.
---
## 🛠️ Tech Stack
### Frontend (Client)
* **React** (Vite)
* **Tailwind CSS** (Styling & Responsive UI)
* **Framer Motion** (Fluid animations and micro-interactions)
* **Lucide React** (Modern iconography)
* **React Router** (Navigation)
### Backend (Server)
* **Node.js & Express.js** (API Routing & Middleware)
* **Multer** (In-memory `multipart/form-data` handling for PDF uploads)
* **Googleapis** (Gmail API integration)
* **Playwright** (Headless browser automation for web disputes)
* **Twilio SDK** (Telephony and automated voice calls)
* **Google Gemini API** (Document extraction and Master Scribe RAG pipeline)
### Database & Auth
* **Supabase** (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)
---
## 🚀 Getting Started
### Prerequisites
* **Node.js** (v18 or higher)
* A **Supabase** Project
* **Google Cloud Console** Project (with Gmail API enabled and OAuth 2.0 credentials)
* **Twilio** Account (Account SID, Auth Token, and a Twilio Phone Number)
* **Google Gemini** API Key
### Installation
1. **Clone the repository**
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents.

🏥 Patient Zero: Autonomous Medical Billing Advocate

Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.

✨ Core Features

📥 Autopilot Inbox Scanning: Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
🕵️‍♂️ The Master Scribe (AI Audit Engine): Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
⚔️ Automated Agent Deployment:
- Primary (Web): Uses Playwright to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
- Fallback (Voice): Uses Twilio to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
⚡ Real-Time Dashboard: Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
🛡️ Dynamic Insurance Vault: A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
📁 Manual Override: A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using multer.

🛠️ Tech Stack

Frontend (Client)

React (Vite)
Tailwind CSS (Styling & Responsive UI)
Framer Motion (Fluid animations and micro-interactions)
Lucide React (Modern iconography)
React Router (Navigation)

Backend (Server)

Node.js & Express.js (API Routing & Middleware)
Multer (In-memory multipart/form-data handling for PDF uploads)
Googleapis (Gmail API integration)
Playwright (Headless browser automation for web disputes)
Twilio SDK (Telephony and automated voice calls)
Google Gemini API (Document extraction and Master Scribe RAG pipeline)

Database & Auth

Supabase (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)

🚀 Getting Started

Prerequisites

Node.js (v18 or higher)
A Supabase Project
Google Cloud Console Project (with Gmail API enabled and OAuth 2.0 credentials)
Twilio Account (Account SID, Auth Token, and a Twilio Phone Number)
Google Gemini API Key

Installation

Clone the repository

README.md generated successfully.
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents. """

with open("README.md", "w", encoding="utf-8") as f: f.write(readme_content)

print("README.md generated successfully.")

Your Markdown file is ready
[file-tag: code-generated-file-0-1776554008595075563]
Here is the complete, perfectly formatted `README.md` text for you to easily copy and paste into your project repository. ```markdown
# 🏥 Patient Zero: Autonomous Medical Billing Advocate
Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.
---
## ✨ Core Features
* **📥 Autopilot Inbox Scanning:** Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
* **🕵️‍♂️ The Master Scribe (AI Audit Engine):** Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
* **⚔️ Automated Agent Deployment:**
* **Primary (Web):** Uses **Playwright** to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
* **Fallback (Voice):** Uses **Twilio** to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
* **⚡ Real-Time Dashboard:** Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
* **🛡️ Dynamic Insurance Vault:** A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
* **📁 Manual Override:** A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using `multer`.
---
## 🛠️ Tech Stack
### Frontend (Client)
* **React** (Vite)
* **Tailwind CSS** (Styling & Responsive UI)
* **Framer Motion** (Fluid animations and micro-interactions)
* **Lucide React** (Modern iconography)
* **React Router** (Navigation)
### Backend (Server)
* **Node.js & Express.js** (API Routing & Middleware)
* **Multer** (In-memory `multipart/form-data` handling for PDF uploads)
* **Googleapis** (Gmail API integration)
* **Playwright** (Headless browser automation for web disputes)
* **Twilio SDK** (Telephony and automated voice calls)
* **Google Gemini API** (Document extraction and Master Scribe RAG pipeline)
### Database & Auth
* **Supabase** (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)
---
## 🚀 Getting Started
### Prerequisites
* **Node.js** (v18 or higher)
* A **Supabase** Project
* **Google Cloud Console** Project (with Gmail API enabled and OAuth 2.0 credentials)
* **Twilio** Account (Account SID, Auth Token, and a Twilio Phone Number)
* **Google Gemini** API Key
### Installation
1. **Clone the repository**
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents.

🏥 Patient Zero: Autonomous Medical Billing Advocate

Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.

✨ Core Features

📥 Autopilot Inbox Scanning: Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
🕵️‍♂️ The Master Scribe (AI Audit Engine): Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
⚔️ Automated Agent Deployment:
- Primary (Web): Uses Playwright to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
- Fallback (Voice): Uses Twilio to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
⚡ Real-Time Dashboard: Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
🛡️ Dynamic Insurance Vault: A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
📁 Manual Override: A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using multer.

🛠️ Tech Stack

Frontend (Client)

React (Vite)
Tailwind CSS (Styling & Responsive UI)
Framer Motion (Fluid animations and micro-interactions)
Lucide React (Modern iconography)
React Router (Navigation)

Backend (Server)

Node.js & Express.js (API Routing & Middleware)
Multer (In-memory multipart/form-data handling for PDF uploads)
Googleapis (Gmail API integration)
Playwright (Headless browser automation for web disputes)
Twilio SDK (Telephony and automated voice calls)
Google Gemini API (Document extraction and Master Scribe RAG pipeline)

Database & Auth

Supabase (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)

🚀 Getting Started

Prerequisites

Node.js (v18 or higher)
A Supabase Project
Google Cloud Console Project (with Gmail API enabled and OAuth 2.0 credentials)
Twilio Account (Account SID, Auth Token, and a Twilio Phone Number)
Google Gemini API Key

Installation

Clone the repository

README.md generated successfully.
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents. """

with open("README.md", "w", encoding="utf-8") as f: f.write(readme_content)

print("README.md generated successfully.")

Your Markdown file is ready
[file-tag: code-generated-file-0-1776554008595075563]
Here is the complete, perfectly formatted `README.md` text for you to easily copy and paste into your project repository. ```markdown
# 🏥 Patient Zero: Autonomous Medical Billing Advocate
Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.
---
## ✨ Core Features
* **📥 Autopilot Inbox Scanning:** Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
* **🕵️‍♂️ The Master Scribe (AI Audit Engine):** Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
* **⚔️ Automated Agent Deployment:**
* **Primary (Web):** Uses **Playwright** to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
* **Fallback (Voice):** Uses **Twilio** to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
* **⚡ Real-Time Dashboard:** Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
* **🛡️ Dynamic Insurance Vault:** A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
* **📁 Manual Override:** A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using `multer`.
---
## 🛠️ Tech Stack
### Frontend (Client)
* **React** (Vite)
* **Tailwind CSS** (Styling & Responsive UI)
* **Framer Motion** (Fluid animations and micro-interactions)
* **Lucide React** (Modern iconography)
* **React Router** (Navigation)
### Backend (Server)
* **Node.js & Express.js** (API Routing & Middleware)
* **Multer** (In-memory `multipart/form-data` handling for PDF uploads)
* **Googleapis** (Gmail API integration)
* **Playwright** (Headless browser automation for web disputes)
* **Twilio SDK** (Telephony and automated voice calls)
* **Google Gemini API** (Document extraction and Master Scribe RAG pipeline)
### Database & Auth
* **Supabase** (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)
---
## 🚀 Getting Started
### Prerequisites
* **Node.js** (v18 or higher)
* A **Supabase** Project
* **Google Cloud Console** Project (with Gmail API enabled and OAuth 2.0 credentials)
* **Twilio** Account (Account SID, Auth Token, and a Twilio Phone Number)
* **Google Gemini** API Key
### Installation
1. **Clone the repository**
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents.

🏥 Patient Zero: Autonomous Medical Billing Advocate

Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.

✨ Core Features

📥 Autopilot Inbox Scanning: Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
🕵️‍♂️ The Master Scribe (AI Audit Engine): Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
⚔️ Automated Agent Deployment:
- Primary (Web): Uses Playwright to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
- Fallback (Voice): Uses Twilio to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
⚡ Real-Time Dashboard: Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
🛡️ Dynamic Insurance Vault: A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
📁 Manual Override: A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using multer.

🛠️ Tech Stack

Frontend (Client)

React (Vite)
Tailwind CSS (Styling & Responsive UI)
Framer Motion (Fluid animations and micro-interactions)
Lucide React (Modern iconography)
React Router (Navigation)

Backend (Server)

Node.js & Express.js (API Routing & Middleware)
Multer (In-memory multipart/form-data handling for PDF uploads)
Googleapis (Gmail API integration)
Playwright (Headless browser automation for web disputes)
Twilio SDK (Telephony and automated voice calls)
Google Gemini API (Document extraction and Master Scribe RAG pipeline)

Database & Auth

Supabase (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)

🚀 Getting Started

Prerequisites

Node.js (v18 or higher)
A Supabase Project
Google Cloud Console Project (with Gmail API enabled and OAuth 2.0 credentials)
Twilio Account (Account SID, Auth Token, and a Twilio Phone Number)
Google Gemini API Key

Installation

Clone the repository

README.md generated successfully.
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents. """

with open("README.md", "w", encoding="utf-8") as f: f.write(readme_content)

print("README.md generated successfully.")

Your Markdown file is ready
[file-tag: code-generated-file-0-1776554008595075563]
Here is the complete, perfectly formatted `README.md` text for you to easily copy and paste into your project repository. ```markdown
# 🏥 Patient Zero: Autonomous Medical Billing Advocate
Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.
---
## ✨ Core Features
* **📥 Autopilot Inbox Scanning:** Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
* **🕵️‍♂️ The Master Scribe (AI Audit Engine):** Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
* **⚔️ Automated Agent Deployment:**
* **Primary (Web):** Uses **Playwright** to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
* **Fallback (Voice):** Uses **Twilio** to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
* **⚡ Real-Time Dashboard:** Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
* **🛡️ Dynamic Insurance Vault:** A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
* **📁 Manual Override:** A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using `multer`.
---
## 🛠️ Tech Stack
### Frontend (Client)
* **React** (Vite)
* **Tailwind CSS** (Styling & Responsive UI)
* **Framer Motion** (Fluid animations and micro-interactions)
* **Lucide React** (Modern iconography)
* **React Router** (Navigation)
### Backend (Server)
* **Node.js & Express.js** (API Routing & Middleware)
* **Multer** (In-memory `multipart/form-data` handling for PDF uploads)
* **Googleapis** (Gmail API integration)
* **Playwright** (Headless browser automation for web disputes)
* **Twilio SDK** (Telephony and automated voice calls)
* **Google Gemini API** (Document extraction and Master Scribe RAG pipeline)
### Database & Auth
* **Supabase** (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)
---
## 🚀 Getting Started
### Prerequisites
* **Node.js** (v18 or higher)
* A **Supabase** Project
* **Google Cloud Console** Project (with Gmail API enabled and OAuth 2.0 credentials)
* **Twilio** Account (Account SID, Auth Token, and a Twilio Phone Number)
* **Google Gemini** API Key
### Installation
1. **Clone the repository**
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents.

🏥 Patient Zero: Autonomous Medical Billing Advocate

Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.

✨ Core Features

📥 Autopilot Inbox Scanning: Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
🕵️‍♂️ The Master Scribe (AI Audit Engine): Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
⚔️ Automated Agent Deployment:
- Primary (Web): Uses Playwright to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
- Fallback (Voice): Uses Twilio to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
⚡ Real-Time Dashboard: Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
🛡️ Dynamic Insurance Vault: A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
📁 Manual Override: A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using multer.

🛠️ Tech Stack

Frontend (Client)

React (Vite)
Tailwind CSS (Styling & Responsive UI)
Framer Motion (Fluid animations and micro-interactions)
Lucide React (Modern iconography)
React Router (Navigation)

Backend (Server)

Node.js & Express.js (API Routing & Middleware)
Multer (In-memory multipart/form-data handling for PDF uploads)
Googleapis (Gmail API integration)
Playwright (Headless browser automation for web disputes)
Twilio SDK (Telephony and automated voice calls)
Google Gemini API (Document extraction and Master Scribe RAG pipeline)

Database & Auth

Supabase (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)

🚀 Getting Started

Prerequisites

Node.js (v18 or higher)
A Supabase Project
Google Cloud Console Project (with Gmail API enabled and OAuth 2.0 credentials)
Twilio Account (Account SID, Auth Token, and a Twilio Phone Number)
Google Gemini API Key

Installation

Clone the repository

README.md generated successfully.
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents. """

with open("README.md", "w", encoding="utf-8") as f: f.write(readme_content)

print("README.md generated successfully.")

Your Markdown file is ready
[file-tag: code-generated-file-0-1776554008595075563]
Here is the complete, perfectly formatted `README.md` text for you to easily copy and paste into your project repository. ```markdown
# 🏥 Patient Zero: Autonomous Medical Billing Advocate
Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.
---
## ✨ Core Features
* **📥 Autopilot Inbox Scanning:** Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
* **🕵️‍♂️ The Master Scribe (AI Audit Engine):** Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
* **⚔️ Automated Agent Deployment:**
* **Primary (Web):** Uses **Playwright** to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
* **Fallback (Voice):** Uses **Twilio** to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
* **⚡ Real-Time Dashboard:** Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
* **🛡️ Dynamic Insurance Vault:** A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
* **📁 Manual Override:** A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using `multer`.
---
## 🛠️ Tech Stack
### Frontend (Client)
* **React** (Vite)
* **Tailwind CSS** (Styling & Responsive UI)
* **Framer Motion** (Fluid animations and micro-interactions)
* **Lucide React** (Modern iconography)
* **React Router** (Navigation)
### Backend (Server)
* **Node.js & Express.js** (API Routing & Middleware)
* **Multer** (In-memory `multipart/form-data` handling for PDF uploads)
* **Googleapis** (Gmail API integration)
* **Playwright** (Headless browser automation for web disputes)
* **Twilio SDK** (Telephony and automated voice calls)
* **Google Gemini API** (Document extraction and Master Scribe RAG pipeline)
### Database & Auth
* **Supabase** (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)
---
## 🚀 Getting Started
### Prerequisites
* **Node.js** (v18 or higher)
* A **Supabase** Project
* **Google Cloud Console** Project (with Gmail API enabled and OAuth 2.0 credentials)
* **Twilio** Account (Account SID, Auth Token, and a Twilio Phone Number)
* **Google Gemini** API Key
### Installation
1. **Clone the repository**
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents.

🏥 Patient Zero: Autonomous Medical Billing Advocate

Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.

✨ Core Features

📥 Autopilot Inbox Scanning: Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
🕵️‍♂️ The Master Scribe (AI Audit Engine): Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
⚔️ Automated Agent Deployment:
- Primary (Web): Uses Playwright to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
- Fallback (Voice): Uses Twilio to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
⚡ Real-Time Dashboard: Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
🛡️ Dynamic Insurance Vault: A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
📁 Manual Override: A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using multer.

🛠️ Tech Stack

Frontend (Client)

React (Vite)
Tailwind CSS (Styling & Responsive UI)
Framer Motion (Fluid animations and micro-interactions)
Lucide React (Modern iconography)
React Router (Navigation)

Backend (Server)

Node.js & Express.js (API Routing & Middleware)
Multer (In-memory multipart/form-data handling for PDF uploads)
Googleapis (Gmail API integration)
Playwright (Headless browser automation for web disputes)
Twilio SDK (Telephony and automated voice calls)
Google Gemini API (Document extraction and Master Scribe RAG pipeline)

Database & Auth

Supabase (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)

🚀 Getting Started

Prerequisites

Node.js (v18 or higher)
A Supabase Project
Google Cloud Console Project (with Gmail API enabled and OAuth 2.0 credentials)
Twilio Account (Account SID, Auth Token, and a Twilio Phone Number)
Google Gemini API Key

Installation

Clone the repository

README.md generated successfully.
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents. """

with open("README.md", "w", encoding="utf-8") as f: f.write(readme_content)

print("README.md generated successfully.")

Your Markdown file is ready
[file-tag: code-generated-file-0-1776554008595075563]
Here is the complete, perfectly formatted `README.md` text for you to easily copy and paste into your project repository. ```markdown
# 🏥 Patient Zero: Autonomous Medical Billing Advocate
Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.
---
## ✨ Core Features
* **📥 Autopilot Inbox Scanning:** Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
* **🕵️‍♂️ The Master Scribe (AI Audit Engine):** Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
* **⚔️ Automated Agent Deployment:**
* **Primary (Web):** Uses **Playwright** to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
* **Fallback (Voice):** Uses **Twilio** to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
* **⚡ Real-Time Dashboard:** Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
* **🛡️ Dynamic Insurance Vault:** A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
* **📁 Manual Override:** A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using `multer`.
---
## 🛠️ Tech Stack
### Frontend (Client)
* **React** (Vite)
* **Tailwind CSS** (Styling & Responsive UI)
* **Framer Motion** (Fluid animations and micro-interactions)
* **Lucide React** (Modern iconography)
* **React Router** (Navigation)
### Backend (Server)
* **Node.js & Express.js** (API Routing & Middleware)
* **Multer** (In-memory `multipart/form-data` handling for PDF uploads)
* **Googleapis** (Gmail API integration)
* **Playwright** (Headless browser automation for web disputes)
* **Twilio SDK** (Telephony and automated voice calls)
* **Google Gemini API** (Document extraction and Master Scribe RAG pipeline)
### Database & Auth
* **Supabase** (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)
---
## 🚀 Getting Started
### Prerequisites
* **Node.js** (v18 or higher)
* A **Supabase** Project
* **Google Cloud Console** Project (with Gmail API enabled and OAuth 2.0 credentials)
* **Twilio** Account (Account SID, Auth Token, and a Twilio Phone Number)
* **Google Gemini** API Key
### Installation
1. **Clone the repository**
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents.

🏥 Patient Zero: Autonomous Medical Billing Advocate

Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.

✨ Core Features

📥 Autopilot Inbox Scanning: Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
🕵️‍♂️ The Master Scribe (AI Audit Engine): Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
⚔️ Automated Agent Deployment:
- Primary (Web): Uses Playwright to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
- Fallback (Voice): Uses Twilio to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
⚡ Real-Time Dashboard: Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
🛡️ Dynamic Insurance Vault: A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
📁 Manual Override: A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using multer.

🛠️ Tech Stack

Frontend (Client)

React (Vite)
Tailwind CSS (Styling & Responsive UI)
Framer Motion (Fluid animations and micro-interactions)
Lucide React (Modern iconography)
React Router (Navigation)

Backend (Server)

Node.js & Express.js (API Routing & Middleware)
Multer (In-memory multipart/form-data handling for PDF uploads)
Googleapis (Gmail API integration)
Playwright (Headless browser automation for web disputes)
Twilio SDK (Telephony and automated voice calls)
Google Gemini API (Document extraction and Master Scribe RAG pipeline)

Database & Auth

Supabase (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)

🚀 Getting Started

Prerequisites

Node.js (v18 or higher)
A Supabase Project
Google Cloud Console Project (with Gmail API enabled and OAuth 2.0 credentials)
Twilio Account (Account SID, Auth Token, and a Twilio Phone Number)
Google Gemini API Key

Installation

Clone the repository

README.md generated successfully.
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents. """

with open("README.md", "w", encoding="utf-8") as f: f.write(readme_content)

print("README.md generated successfully.")

Your Markdown file is ready
[file-tag: code-generated-file-0-1776554008595075563]
Here is the complete, perfectly formatted `README.md` text for you to easily copy and paste into your project repository. ```markdown
# 🏥 Patient Zero: Autonomous Medical Billing Advocate
Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.
---
## ✨ Core Features
* **📥 Autopilot Inbox Scanning:** Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
* **🕵️‍♂️ The Master Scribe (AI Audit Engine):** Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
* **⚔️ Automated Agent Deployment:**
* **Primary (Web):** Uses **Playwright** to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
* **Fallback (Voice):** Uses **Twilio** to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
* **⚡ Real-Time Dashboard:** Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
* **🛡️ Dynamic Insurance Vault:** A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
* **📁 Manual Override:** A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using `multer`.
---
## 🛠️ Tech Stack
### Frontend (Client)
* **React** (Vite)
* **Tailwind CSS** (Styling & Responsive UI)
* **Framer Motion** (Fluid animations and micro-interactions)
* **Lucide React** (Modern iconography)
* **React Router** (Navigation)
### Backend (Server)
* **Node.js & Express.js** (API Routing & Middleware)
* **Multer** (In-memory `multipart/form-data` handling for PDF uploads)
* **Googleapis** (Gmail API integration)
* **Playwright** (Headless browser automation for web disputes)
* **Twilio SDK** (Telephony and automated voice calls)
* **Google Gemini API** (Document extraction and Master Scribe RAG pipeline)
### Database & Auth
* **Supabase** (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)
---
## 🚀 Getting Started
### Prerequisites
* **Node.js** (v18 or higher)
* A **Supabase** Project
* **Google Cloud Console** Project (with Gmail API enabled and OAuth 2.0 credentials)
* **Twilio** Account (Account SID, Auth Token, and a Twilio Phone Number)
* **Google Gemini** API Key
### Installation
1. **Clone the repository**
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents.

🏥 Patient Zero: Autonomous Medical Billing Advocate

Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.

✨ Core Features

📥 Autopilot Inbox Scanning: Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
🕵️‍♂️ The Master Scribe (AI Audit Engine): Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
⚔️ Automated Agent Deployment:
- Primary (Web): Uses Playwright to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
- Fallback (Voice): Uses Twilio to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
⚡ Real-Time Dashboard: Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
🛡️ Dynamic Insurance Vault: A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
📁 Manual Override: A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using multer.

🛠️ Tech Stack

Frontend (Client)

React (Vite)
Tailwind CSS (Styling & Responsive UI)
Framer Motion (Fluid animations and micro-interactions)
Lucide React (Modern iconography)
React Router (Navigation)

Backend (Server)

Node.js & Express.js (API Routing & Middleware)
Multer (In-memory multipart/form-data handling for PDF uploads)
Googleapis (Gmail API integration)
Playwright (Headless browser automation for web disputes)
Twilio SDK (Telephony and automated voice calls)
Google Gemini API (Document extraction and Master Scribe RAG pipeline)

Database & Auth

Supabase (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)

🚀 Getting Started

Prerequisites

Node.js (v18 or higher)
A Supabase Project
Google Cloud Console Project (with Gmail API enabled and OAuth 2.0 credentials)
Twilio Account (Account SID, Auth Token, and a Twilio Phone Number)
Google Gemini API Key

Installation

Clone the repository

README.md generated successfully.
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents. """

with open("README.md", "w", encoding="utf-8") as f: f.write(readme_content)

print("README.md generated successfully.")

Your Markdown file is ready
[file-tag: code-generated-file-0-1776554008595075563]
Here is the complete, perfectly formatted `README.md` text for you to easily copy and paste into your project repository. ```markdown
# 🏥 Patient Zero: Autonomous Medical Billing Advocate
Patient Zero is an AI-powered, fully autonomous medical billing advocate. It protects patients from hospital overcharges, upcoding, unbundling, and fraudulent billing practices by automatically auditing medical bills against clinical notes and insurance policies, drafting legal dispute letters, and deploying digital agents to fight the hospital on the patient's behalf.
---
## ✨ Core Features
* **📥 Autopilot Inbox Scanning:** Integrates with the Gmail API to securely scan for incoming medical bills (PDFs) with strict, bulletproof domain verification to block spoofed/phishing emails.
* **🕵️‍♂️ The Master Scribe (AI Audit Engine):** Utilizes Google Gemini in a RAG (Retrieval-Augmented Generation) pipeline to extract line items, cross-reference clinical notes against the user's uploaded insurance policy, and detect billing discrepancies.
* **⚔️ Automated Agent Deployment:**
* **Primary (Web):** Uses **Playwright** to autonomously log into the hospital's billing portal and submit the AI-generated dispute letter.
* **Fallback (Voice):** Uses **Twilio** to initiate an automated Text-to-Speech phone call to the hospital's billing department if the web portal is inaccessible.
* **⚡ Real-Time Dashboard:** Built with React and Supabase Realtime. The UI updates instantly via WebSockets when the AI finishes drafting a dispute letter—no page refreshes required.
* **🛡️ Dynamic Insurance Vault:** A multi-step wizard to manage multiple health insurance policies, storing encrypted portal credentials securely.
* **📁 Manual Override:** A modern, floating drag-and-drop UI to manually upload PDF bills directly into the AI extraction pipeline using `multer`.
---
## 🛠️ Tech Stack
### Frontend (Client)
* **React** (Vite)
* **Tailwind CSS** (Styling & Responsive UI)
* **Framer Motion** (Fluid animations and micro-interactions)
* **Lucide React** (Modern iconography)
* **React Router** (Navigation)
### Backend (Server)
* **Node.js & Express.js** (API Routing & Middleware)
* **Multer** (In-memory `multipart/form-data` handling for PDF uploads)
* **Googleapis** (Gmail API integration)
* **Playwright** (Headless browser automation for web disputes)
* **Twilio SDK** (Telephony and automated voice calls)
* **Google Gemini API** (Document extraction and Master Scribe RAG pipeline)
### Database & Auth
* **Supabase** (PostgreSQL, Row Level Security, Realtime WebSocket subscriptions)
---
## 🚀 Getting Started
### Prerequisites
* **Node.js** (v18 or higher)
* A **Supabase** Project
* **Google Cloud Console** Project (with Gmail API enabled and OAuth 2.0 credentials)
* **Twilio** Account (Account SID, Auth Token, and a Twilio Phone Number)
* **Google Gemini** API Key
### Installation
1. **Clone the repository**
```bash
git clone [https://github.com/yourusername/patient-zero.git](https://github.com/yourusername/patient-zero.git)
cd patient-zero

Install Backend Dependencies
```
cd server
npm install
```
Install Frontend Dependencies
```
cd ../client
npm install
```

Environment Variables

Create a .env file in your server directory and add the following keys:

# Supabase ConfigurationSUPABASE_URL=your_supabase_project_urlSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key# Google / Gmail API CredentialsGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretGOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback# AI EngineGEMINI_API_KEY=your_gemini_api_key# Twilio Fallback ConfigurationTWILIO_SID=your_twilio_account_sidTWILIO_AUTH_TOKEN=your_twilio_auth_tokenTWILIO_PHONE_NUMBER=+1234567890FALLBACK_PHONE=+0987654321# Your personal phone number for testing the voice agent

Running the Application

1. Start the Backend Server

cd server
npm run dev
# Server runs on http://localhost:3000

2. Start the Frontend Client

cd client
npm run dev
# Client runs on http://localhost:5173

📂 Project Architecture & Key Files

server/src/api/bills.js: Express router handling manual PDF uploads (/upload), triggering the Gmail scanner (/scan), deploying agents (/:id/deploy), and fetching compiled arena data.
server/src/services/gmailService.js: The Autopilot scanner. Features strict sender domain verification to prevent processing spoofed emails.
server/src/services/agentService.js: Houses runDisputeAgent(). Attempts Playwright web automation first, and automatically falls back to a Twilio voice call if it fails.
server/rag/unifiedAudit.js: The brains of the operation. Fetches the bill, fetches the user's insurance policy from Supabase, and prompts Gemini to act as a Master Scribe to find discrepancies and draft the dispute letter. Includes graceful fallbacks for missing policy data.
client/src/views/ActionArena.jsx: The main dispute dashboard. Displays the itemized bill, the AI Detective Notes, the drafted letter, and the "Deploy AI Agent" trigger button.
client/src/components/dashboard/FloatingUploadBar.jsx: The modern, Gemini-style floating action bar for manual PDF uploads.

⚠️ Disclaimer

Patient Zero is a conceptual tool designed to assist with medical billing disputes. It does not provide certified legal advice. Users should review all AI-generated dispute letters before deploying the autonomous agents.

Name		Name	Last commit message	Last commit date
frontend		frontend
rag		rag
server		server
readme.md		readme.md

Name		Name	Last commit message	Last commit date
frontend		frontend
rag		rag
server		server
readme.md		readme.md

Name		Name	Last commit message	Last commit date
frontend		frontend
rag		rag
server		server
readme.md		readme.md

Name		Name	Last commit message	Last commit date
frontend		frontend
rag		rag
server		server
readme.md		readme.md

Name		Name	Last commit message	Last commit date
frontend		frontend
rag		rag
server		server
readme.md		readme.md

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

✨ Core Features

🛠️ Tech Stack

Frontend (Client)

Backend (Server)

Database & Auth

🚀 Getting Started

Prerequisites

Installation

Environment Variables

Running the Application

📂 Project Architecture & Key Files

⚠️ Disclaimer

Environment Variables

Running the Application

📂 Project Architecture & Key Files

⚠️ Disclaimer

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

✨ Core Features

🛠️ Tech Stack

Frontend (Client)

Backend (Server)

Database & Auth

🚀 Getting Started

Prerequisites

Installation

Environment Variables

Running the Application

📂 Project Architecture & Key Files

⚠️ Disclaimer

Environment Variables

Running the Application

📂 Project Architecture & Key Files

⚠️ Disclaimer

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

✨ Core Features

🛠️ Tech Stack

Frontend (Client)

Backend (Server)

Database & Auth

🚀 Getting Started

Prerequisites

Installation

Environment Variables

Running the Application

📂 Project Architecture & Key Files

⚠️ Disclaimer

Environment Variables

Running the Application

📂 Project Architecture & Key Files