Insurance Coverage Project

A unified full-stack application for validating medical study coverage against insurance provider lists using AI/LLM technology. The system helps medical professionals determine if specific medical studies are covered by insurance and provides detailed reasoning for coverage decisions.

✨ Key Features

• Unified Architecture: Single server serves both API and frontend
• AI-Powered Coverage Validation: Uses LLM to determine medical study coverage
• Multiple Model Support: OpenAI and Ollama integration
• Structured Output: Zod schema validation for consistent responses
• Web Interface: Modern HTML/CSS/JS frontend
• REST API: Programmatic access to coverage validation
• Command Line Tool: Testing and development utilities
• Docker Support: Containerized deployment ready

🏗️ Unified Architecture

This project uses a unified architecture where a single Express server handles both the API and serves the frontend files. This simplifies deployment and eliminates CORS issues.

insurance_coverage/
├── src/                    # Server source code
│   ├── index.ts           # Main server (API + static file serving)
│   ├── ic.ts              # Command-line testing script
│   ├── insurance-coverage.ts  # Core coverage logic
│   ├── config.ts          # Environment configuration
│   ├── enums/             # Type definitions
│   └── schemas/           # Zod validation schemas
├── frontend/              # Static frontend files
│   ├── index.html         # Main web interface
│   ├── main.js            # Frontend JavaScript
│   └── style.css          # Styling
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
├── Dockerfile             # Container configuration
├── env.example            # Environment variables template
├── LICENSE                # ISC License
└── README.md

🚀 Quick Start

Prerequisites

• Node.js: Version 18.0.0 or higher
• npm: Version 8.0.0 or higher
• OpenAI API Key (for production) or Ollama (for local development)

Installation

1. Clone the repository

   git clone <repository-url>
   cd insurance_coverage

2. Install dependencies

   npm install

3. Set up environment variables

   cp env.example .env
   # Edit .env with your configuration

4. Start the unified server

   npm run dev

5. Access the application

   • Open http://localhost:3000 in your browser
   • The server automatically serves both API and frontend

🔧 Configuration

Environment Variables

Create a .env file in the root directory with the following variables:

# OpenAI Configuration (for production)
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini

# Ollama Configuration (for local development)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=mistral

Model Selection

The system supports two AI models:

• OpenAI: Production-ready, requires API key
• Ollama: Local development, free to use

📖 Usage

Web Interface

1. Open http://localhost:3000 in your browser
2. Enter a medical study description (e.g., "urotac", "resonancia de cabeza")
3. Click "Check" to get coverage information
4. View the coverage result and reasoning

API Endpoints

• GET /health - Health check
• GET /ping - Simple ping endpoint
• GET /homologate-study/:study - Get coverage for a medical study

Command Line Tool

Use the ic.ts script for command-line testing:

npm run ic

This will test the coverage validation with a predefined study.

🛠️ Development

Available Scripts

npm run dev      # Start unified development server with hot reload
npm run build    # Build TypeScript to JavaScript
npm start        # Start production server
npm run ic       # Run command-line testing script

Unified Development

The project uses a unified architecture where:

• Single Server: One Express server handles both API and frontend
• No CORS Issues: Frontend and API are on the same origin
• Simplified Deployment: One process to manage
• Static File Serving: Express serves frontend files automatically

Frontend Development

The frontend is automatically served by the Express server at http://localhost:3000. No separate frontend server needed.

🐳 Docker Support

The project includes a Dockerfile for containerized deployment:

docker build -t insurance-coverage .
docker run -p 3000:3000 insurance-coverage

📋 Features

• Unified Architecture: Single server for API and frontend
• AI-Powered Coverage Validation: Uses LLM to determine medical study coverage
• Multiple Model Support: OpenAI and Ollama integration
• Structured Output: Zod schema validation for consistent responses
• Modern Web Interface: Clean HTML/CSS/JS frontend
• REST API: Programmatic access to coverage validation
• Command Line Tool: Testing and development utilities
• TypeScript: Full type safety throughout the project
• Docker Ready: Containerized deployment support

🔍 Coverage Types

The system currently validates coverage for:

• Tomografías (CT Scans): Various body parts and types
• Resonancias Magnéticas (MRI): Different anatomical regions
• Other Medical Studies: As defined in the coverage list

📚 Documentation

• Frontend Documentation - Frontend usage and customization guide
• Environment Configuration - Environment variables template
• LICENSE - ISC License file

Architecture Overview

This project uses a unified architecture where a single Express server handles both the API endpoints and serves the frontend files. This approach provides several benefits:

• Simplified Deployment: Only one server process to manage
• No CORS Issues: Frontend and API share the same origin
• Easier Development: Single command to start everything
• Better Performance: No network overhead between frontend and API

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

This project is licensed under the ISC License. See the LICENSE file for details.

🆘 Support

For questions or issues, please check the individual component documentation or create an issue in the repository.