FLUSSO - Medical Bill Verification Platform 🏥

Verify medical bills against DHA/DoH guidelines instantly using AI-powered compliance checking for Dubai & UAE healthcare providers

---

📋 Table of Contents

• Features
• Tech Stack
• Architecture
• Quick Start
• Installation
• Configuration
• Project Structure
• API Documentation
• Usage Guide
• Contributing
• License
• Support

---

✨ Features

🤖 AI-Powered Medical Bill Analysis

• Instant OCR: Extract patient, provider, doctor, amount, and procedure data from bills
• DHA/DoH Compliance: Verify bills against Dubai Health Authority and Department of Health guidelines
• Compliance Score: Get 0-10 score indicating billing accuracy and guideline compliance
• Issues Detection: Flag potential overbilling, upcoding, or medical necessity violations

💬 Elyza AI Assistant

• Smart Chatbot: Ask questions about your claim and get instant answers
• Context-Aware: Elyza understands your specific bill and compliance score
• Guidance: Get step-by-step help with billing questions, disputes, and appeals
• Voice Support: [Coming Soon] Speak to Elyza and hear responses

📊 Claims Management

• Upload History: View all submitted medical bills
• Detailed Results: See extracted data, compliance findings, and recommendations
• Export Reports: Download audit reports for insurance claims
• Status Tracking: Monitor bill verification status (PASS/FLAGGED)

👤 User Profiles

• Secure Accounts: Sign up with email/password
• Profile Management: Update name, email, and profile picture
• Claim History: Access all past verifications
• Personal Dashboard: See statistics (claims verified, total savings, success rate)

📱 Responsive Design

• Mobile-First: Works perfectly on phones, tablets, desktops
• Modern UI: Clean, intuitive interface built with Tailwind CSS
• Dark Mode: [Coming Soon] Eye-friendly dark theme

---

🏗️ Tech Stack

Frontend

• React 18 - UI framework
• Next.js 14 - Full-stack framework with SSR
• Tailwind CSS - Utility-first CSS framework
• v0.dev - AI-assisted component generation
• Axios - HTTP client
• TypeScript - Type safety

Backend

• Node.js 18+ - Runtime
• Express.js 4 - Web framework
• JWT - Authentication tokens
• bcrypt - Password hashing

AI/ML Services

• Groq API - Fast LLM for OCR, chat, compliance checking
  • llama-3.1-70b-versatile - Vision + Text model
• Comet ML - Experiment tracking & logging

Database & Storage

• Supabase - PostgreSQL database
• Supabase Storage - File storage for images
• PostgREST - Auto-generated REST API

DevOps & Deployment

• Vercel - Frontend hosting
• Docker - Containerization [Optional]
• GitHub - Version control

---

🏛️ Architecture

System Overview

┌─────────────────────────────────────────────────────────────────────┐
│                   FLUSSO FRONTEND (React + Next.js)                 │
│  ┌─────────┬──────────┬──────────┬─────────┬────────────┐           │
│  │ Auth    │Dashboard │ Upload   │History  │Profile     │  Chatbot  │
│  └─────────┴──────────┴──────────┴─────────┴────────────┘           │
└────────────────────────┬─────────────────────────────────────────────┘
                         │ HTTPS REST API
                         ▼
┌─────────────────────────────────────────────────────────────────────┐
│                 BACKEND (Express.js + Node.js)                      │
│  ┌──────────┬────────┬─────────┬─────────┬────────────┐             │
│  │ Auth     │ Upload │ Chat    │ Claims  │ Profile    │             │
│  │ Routes   │ Routes │ Routes  │ Routes  │ Routes     │             │
│  └──────────┴────────┴─────────┴─────────┴────────────┘             │
│                  ↓↓↓                                                │
│  ┌──────────┬───────────────┬────────────────────┐                  │
│  │ Groq API │ Comet ML      │ Supabase           │                  │
│  │ (OCR)    │ (Logging)     │ (Database)         │                  │
│  └──────────┴───────────────┴────────────────────┘                  │
└─────────────────────────────────────────────────────────────────────┘

Data Flow

1. Bill Upload → OCR Extraction → Compliance Check → Results Display
2. Chat → Context Fetch → Groq Response → Database Storage → User Display
3. Profile → Form Edit → Validation → Database Update → Confirmation

Complete Documentation

• 📘 API Documentation
• 📗 User Flow Architecture
• 📙 Code Documentation
• 📕 Implementation Guide

---

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• Git

5-Minute Setup

# 1. Clone repository
git clone https://github.com/yourusername/flusso.git
cd flusso

# 2. Install dependencies
npm install

# 3. Create environment file
cp .env.example .env.local

# 4. Fill environment variables (see Configuration section)

# 5. Start development server
npm run dev

# 6. Open browser
# Frontend: http://localhost:3000
# Backend: http://localhost:5000

---

📦 Installation

Full Installation Guide

Step 1: Clone Repository

git clone https://github.com/yourusername/flusso.git
cd flusso

Step 2: Install Dependencies

# Frontend & Backend dependencies
npm install

# Or with yarn
yarn install

Step 3: Install Specific Packages

# Core dependencies
npm install react@18 next@14 express@4 axios

# AI/ML services
npm install groq-sdk comet-ml

# Database
npm install @supabase/supabase-js

# Security
npm install jsonwebtoken bcrypt

# Environment variables
npm install dotenv

# Development
npm install --save-dev typescript @types/node eslint

Step 4: Create Directories

mkdir -p src/components src/pages src/styles
mkdir -p server/routes server/middleware server/services
mkdir -p docs

Step 5: Initialize Database

# Create Supabase account at https://supabase.com
# Run migrations (see Configuration section)
npm run migrate

---

🔑 Configuration

Environment Variables

Create .env.local file in project root:

# Frontend Config
NEXT_PUBLIC_API_URL=http://localhost:5000
NEXT_PUBLIC_SUPABASE_URL=https://YOUR-PROJECT.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=YOUR-ANON-KEY

# Backend Config
GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
COMET_API_KEY=your_comet_api_key_here
COMET_PROJECT_NAME=flusso-medical-verification
COMET_WORKSPACE=your_workspace_name

# Supabase
SUPABASE_SERVICE_ROLE_KEY=YOUR-SERVICE-ROLE-KEY
SUPABASE_DB_PASSWORD=YOUR-DB-PASSWORD

# JWT Secret
JWT_SECRET=your-super-secret-jwt-key-change-this

# Server
PORT=5000
NODE_ENV=development

Getting API Keys

Groq API:

1. Visit console.groq.com
2. Sign up / Login
3. Generate API key in Settings
4. Copy to GROQ_API_KEY

Comet ML:

1. Visit comet.com
2. Create workspace
3. Get API key from Settings
4. Copy to COMET_API_KEY

Supabase:

1. Visit supabase.com
2. Create new project
3. Copy URL and Anon Key
4. Create tables using SQL migrations

Database Setup

Create Users Table:

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  full_name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  profile_picture TEXT,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Create Claims Table:

CREATE TABLE claims (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id),
  patient_name TEXT NOT NULL,
  provider_name TEXT NOT NULL,
  doctor_name TEXT,
  department TEXT,
  claim_date DATE,
  amount DECIMAL(10, 2),
  services JSONB,
  icd10_codes TEXT[],
  cpt_codes TEXT[],
  compliance_score INTEGER,
  status TEXT CHECK (status IN ('PASS', 'FLAGGED')),
  analysis_details JSONB,
  image_url TEXT,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Create Chat Messages Table:

CREATE TABLE chat_messages (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  claim_id UUID NOT NULL REFERENCES claims(id),
  user_id UUID NOT NULL REFERENCES users(id),
  role TEXT CHECK (role IN ('user', 'assistant')),
  content TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

---

📁 Project Structure

flusso/
├── app/                          # Frontend (Next.js)
│   ├── auth/                     # Authentication pages
│   │   └── page.jsx
│   ├── dashboard/                # Dashboard
│   │   └── page.jsx
│   ├── upload/                   # Bill upload
│   │   └── page.jsx
│   ├── results/[claimId]/        # Results page
│   │   └── page.jsx
│   ├── profile/                  # Profile settings
│   │   └── page.jsx
│   ├── history/                  # Claims history
│   │   └── page.jsx
│   ├── help/                     # Help & FAQs
│   │   └── page.jsx
│   ├── layout.jsx                # Root layout
│   └── page.jsx                  # Home page
│
├── components/                   # Reusable components
│   ├── Chatbot.jsx               # Elyza chatbot
│   ├── Navbar.jsx                # Navigation
│   ├── Upload.jsx                # Upload component
│   ├── Results.jsx               # Results display
│   └── ...
│
├── server/                       # Backend (Express.js)
│   ├── routes/
│   │   ├── auth.js               # Authentication routes
│   │   ├── upload.js             # Upload routes
│   │   ├── chat.js               # Chat routes
│   │   ├── claims.js             # Claims routes
│   │   └── profile.js            # Profile routes
│   │
│   ├── middleware/
│   │   ├── auth.js               # JWT validation
│   │   └── errorHandler.js       # Error handling
│   │
│   ├── services/
│   │   ├── groq-ocr.js           # OCR service
│   │   ├── groq-chat.js          # Chat service
│   │   ├── groq-compliance.js    # Compliance service
│   │   └── comet-logger.js       # Logging service
│   │
│   ├── db/
│   │   └── migrations.sql        # Database schema
│   │
│   └── index.js                  # Express server
│
├── lib/                          # Utility functions
│   ├── supabase.js               # Supabase client
│   ├── jwt.js                    # JWT utilities
│   └── validators.js             # Input validation
│
├── docs/                         # Documentation
│   ├── API_DOCS.md               # API endpoints
│   ├── USER_FLOW_ARCHITECTURE.md # Complete flows
│   ├── FLUSSO_API_DOCS.md        # Code docs
│   └── CLAUDE_FLOW_PROMPTS.md    # Claude prompts
│
├── styles/                       # Tailwind CSS
│   └── globals.css
│
├── public/                       # Static files
│   ├── logo.png
│   └── favicon.ico
│
├── .env.example                  # Example env variables
├── .env.local                    # Local env (gitignored)
├── .gitignore
├── package.json
├── tsconfig.json
├── next.config.js
├── tailwind.config.js
└── README.md                     # This file

---

🔌 API Documentation

Authentication Endpoints

Sign Up

POST /api/auth/signup
Content-Type: application/json

{
  "full_name": "Muaaz Syed",
  "email": "muaaz@example.com",
  "password": "SecurePass123!",
  "profile_picture": "base64_string"
}

Response: { success: true, token: "jwt_token", user: {...} }

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "muaaz@example.com",
  "password": "SecurePass123!"
}

Response: { success: true, token: "jwt_token", user: {...} }

Upload Endpoints

Upload Bill

POST /api/upload
Authorization: Bearer jwt_token
Content-Type: application/json

{
  "image": "base64_string",
  "fileName": "bill.jpg"
}

Response: {
  success: true,
  claimId: "uuid",
  results: {
    patient_name: "...",
    provider_name: "...",
    compliance_score: 9,
    status: "PASS"
  }
}

Chat Endpoints

Send Message

POST /api/chat
Authorization: Bearer jwt_token
Content-Type: application/json

{
  "message": "Is this bill compliant?",
  "claimId": "uuid"
}

Response: {
  success: true,
  response: "Yes! This bill is compliant..."
}

Full API docs: See API_DOCS.md

---

💡 Usage Guide

For Users

1. Sign Up

   • Visit https://flusso.com
   • Click "Create Account"
   • Fill in details and upload profile picture
   • Verify email (if required)

2. Upload Bill

   • Go to "Upload Claim"
   • Select medical bill image
   • System analyzes bill automatically
   • View results with compliance score

3. Chat with Elyza

   • Click floating chatbot button
   • Ask questions about your bill
   • Get instant answers and guidance

4. View History

   • Go to "My Claims"
   • See all uploaded bills
   • Download audit reports
   • Track savings

For Developers

Build the app:

npm run dev          # Start dev server
npm run build        # Build for production
npm run start        # Start production server
npm run test         # Run tests
npm run lint         # Lint code

Deploy to Vercel:

npm install -g vercel
vercel login
vercel deploy

Deploy to Railway:

npm install -g railway
railway init
railway up

---

🤝 Contributing

We love contributions! Here's how to help:

Steps

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

Guidelines

• Follow existing code style
• Write clear commit messages
• Update documentation
• Add tests for new features
• Test before submitting PR

Areas to Contribute

• 🐛 Bug fixes
• ✨ New features
• 📖 Documentation
• 🎨 UI/UX improvements
• 🧪 Tests
• 🚀 Performance optimization

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Support

Frequently Asked Questions

Q: Is FLUSSO available in other countries? A: Currently, FLUSSO is designed for UAE healthcare providers (DHA/DoH guidelines). We're expanding to other regions soon.

Q: What file types are supported? A: JPG, PNG, and PDF files up to 50MB.

Q: How long does bill analysis take? A: Usually 5-8 seconds for OCR + compliance checking.

Q: Is my data secure? A: Yes! We use JWT authentication, encrypted passwords (bcrypt), and secure database connections.

Q: Can I export my results? A: Yes! Download PDF audit reports from the results page.

---

Project Stats

• Frontend: React + Next.js + Tailwind CSS
• Backend: Express.js + Node.js
• Database: Supabase PostgreSQL
• AI: Groq API (Llama 3.1)
• Monitoring: Comet ML
• Lines of Code: ~5000+
• API Endpoints: 15+
• Database Tables: 3
• Components: 20+

---

Roadmap

• Core bill upload & OCR
• Compliance checking (DHA/DoH)
• Elyza AI chatbot
• User authentication
• Profile management
• Voice input/output
• Multi-language support
• Mobile app (iOS/Android)
• Advanced analytics dashboard
• Integration with insurance providers
• Automatic bill dispute filing
• Blockchain verification

---

Team

• Lead Developer: Muaaz Syed
• Team Lead: Koushik
• Strategist Aayan Desai

---

Acknowledgments

• XAi and Comet - For fast, efficient LLM API
• Supabase - For amazing database infrastructure
• Vercel - For seamless deployment
• Tailwind CSS - For beautiful styling
• Perplexity - For AI code generation assistance

Helping you verify medical bills with AI-powered precision for Dubai & UAE healthcare

Status: 🟢 Active Development