Pharmacy Claims Processing System

A scalable, production-grade pharmacy claims processing system built with Node.js, TypeScript, PostgreSQL, and Redis. This system demonstrates modern software engineering practices and is designed to run on Kubernetes.

🎯 Features

Core Functionality

• Claim Processing: Accept and process pharmacy claims with patient, prescription, and insurance information
• Queue Management: Asynchronous processing using Redis queues with Bull
• Business Rules Engine: Configurable rules using json-rules-engine for claim validation and processing
• Error Handling: Comprehensive error handling with retry mechanisms and exponential backoff
• Database Storage: Relational database storage with PostgreSQL
• Audit Logging: Complete audit trail for all claim operations

Bonus Features

• Daily Reports: Automated daily reports showing claims statistics
• Invoice Reports: Pharmacy invoice generation with processing fees
• Health Monitoring: Comprehensive health checks and system status monitoring
• API Documentation: RESTful API with comprehensive endpoints

🏗️ Architecture

Technology Stack

• Backend: Node.js with TypeScript
• Database: PostgreSQL with connection pooling
• Queue System: Redis with Bull for job processing
• Business Rules: json-rules-engine for configurable business logic
• API: Express.js with comprehensive middleware
• Containerization: Docker with multi-stage builds
• Orchestration: Docker Compose for local development

System Components

1. Claim Processing Service: Core business logic for claim validation and processing
2. Queue Service: Manages asynchronous job processing with retry logic
3. Rules Engine Service: Applies configurable business rules to claims
4. Report Service: Generates daily and invoice reports
5. Database Layer: PostgreSQL with optimized schema and indexes
6. API Layer: RESTful endpoints with validation and error handling

🚀 Quick Start

Prerequisites

• Node.js 18+
• Docker and Docker Compose
• PostgreSQL 15+
• Redis 7+

Local Development Setup

1. Clone the repository

   git clone <repository-url>
   cd pharmacy-claims-processor

2. Install dependencies

   npm install

3. Set up environment variables

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

4. Start services with Docker Compose

   npm run docker:run

5. Run database migrations

   npm run migrate

6. Start the application

   npm run dev

The application will be available at http://localhost:3000

Production Deployment

1. Build the Docker image

   npm run docker:build

2. Deploy to Kubernetes

   kubectl apply -f k8s/

📊 API Documentation

Base URL

http://localhost:3000/api/v1

Claims Endpoints

Submit a New Claim

POST /claims
Content-Type: application/json

{
  "patientId": "uuid",
  "pharmacyId": "uuid",
  "insurancePolicyId": "uuid",
  "prescriptionDetails": {
    "drugName": "Lisinopril",
    "ndc": "00071015523",
    "quantity": 30,
    "daysSupply": 30,
    "prescriberNpi": "1234567890",
    "prescriptionDate": "2024-01-15",
    "refillNumber": 0,
    "isGeneric": true,
    "strength": "10mg",
    "dosageForm": "tablet"
  },
  "claimAmount": 25.50
}

Get Claim by ID

GET /claims/{claimId}

Get Claims by Status

GET /claims/status/{status}?limit=100

Retry Failed Claim

POST /claims/{claimId}/retry

Get Queue Statistics

GET /claims/queue/stats

Reports Endpoints

Generate Daily Report

POST /reports/daily
Content-Type: application/json

{
  "date": "2024-01-15"
}

Get Daily Report

GET /reports/daily/{date}

Generate Invoice Report

POST /reports/invoice
Content-Type: application/json

{
  "date": "2024-01-15"
}

Get Invoice Report

GET /reports/invoice/{date}

Health Check Endpoints

Basic Health Check

GET /health

Detailed Health Check

GET /health/detailed

System Status

GET /health/status

🗄️ Database Schema

Core Tables

• patients: Patient information and demographics
• pharmacies: Pharmacy details and NPI numbers
• insurance_policies: Insurance coverage information
• claims: Main claims table with processing status
• error_claims: Failed claims with error details
• business_rules: Configurable business rules
• daily_reports: Daily processing statistics
• invoice_reports: Pharmacy invoice data
• audit_logs: Complete audit trail

Key Features

• UUID primary keys for scalability
• Comprehensive indexing for performance
• Audit triggers for data integrity
• JSONB fields for flexible data storage

🔧 Business Rules Engine

The system includes a configurable business rules engine that can:

• Validate Claims: Check for invalid data, missing information
• Apply Coverage Rules: Calculate copays, deductibles, coverage percentages
• Flag Suspicious Claims: Identify potential fraud or errors
• Route Claims: Direct claims to different processing paths
• Apply Modifications: Adjust claim amounts based on rules

Example Business Rules

• Generic drug preference
• High-cost drug review
• Invalid NPI rejection
• Quantity limit checks

📈 Monitoring and Observability

Health Checks

• Database connectivity
• Redis queue status
• Application health
• System resources

Logging

• Structured logging with Winston
• Request/response logging
• Error tracking with stack traces
• Performance metrics

Metrics

• Claims processed per minute
• Processing time statistics
• Error rates and types
• Queue depths and throughput

🔒 Security Features

• Input Validation: Comprehensive request validation
• SQL Injection Protection: Parameterized queries
• CORS Configuration: Configurable cross-origin requests
• Helmet Security: Security headers
• Rate Limiting: API rate limiting (configurable)
• Audit Logging: Complete audit trail

📋 Development Guidelines

Code Style

• TypeScript with strict mode
• ESLint configuration
• Prettier formatting
• Conventional commits

Architecture Patterns

• Service-oriented architecture

• Dependency injection

• Repository pattern

• Factory pattern for business rules

• Database Connection Pooling: Optimized PostgreSQL connections

• Queue Processing: Asynchronous job processing

• Caching: Redis-based caching (configurable)

• Indexing: Optimized database indexes

• Compression: Response compression

• Load Balancing: Ready for horizontal scaling

📚 Additional Resources

• API Documentation
• Database Schema
• Deployment Guide
• Troubleshooting

📄 License

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