ClaimCare — Full-Stack Health Insurance Claims Platform

ClaimCare is a modern, full-stack health insurance claims processing platform designed to streamline the workflow between Healthcare Providers, Medical Reviewers, and System Administrators.

It implements a strictly validated state machine for claim adjudication, real-time WebSocket notifications, a dynamic policy calculation engine, rule-based fraud detection, printable Explanation of Benefits (EOB) statements, and an immutable audit trail.

---

🔗 Project Links & Video Demo

• 🎥 Video Walkthrough (Vimeo): https://vimeo.com/1214711522
• 💻 GitHub Repository: https://github.com/sagardudhat/Health-Insurance-Claims-Platform

---

🏗 Architectural Overview

ClaimCare uses a modular Monorepo structure:

• Frontend (/frontend): Built with Next.js 14 (App Router), React 18, Zustand state management, TanStack React Query, and Tailwind CSS. Employs a Feature-Sliced Design (src/features) with thin page wrappers around domain-specific components.
• Backend (/backend): Built with Node.js, Express, and TypeScript. Follows a strict 3-tier Layered Architecture (Controllers $\rightarrow$ Services $\rightarrow$ Repositories) with MongoDB & Mongoose data persistence.

---

🔄 Claim Adjudication State Machine

Claims transition through a strictly enforced state machine map governed by backend validation:

stateDiagram-v2
    [*] --> SUBMITTED : Provider Submits
    SUBMITTED --> UNDER_REVIEW : Reviewer Claims
    UNDER_REVIEW --> APPROVED : Full Approval
    UNDER_REVIEW --> PARTIALLY_APPROVED : Partial Line Approval
    UNDER_REVIEW --> REJECTED : Denied
    UNDER_REVIEW --> NEEDS_REVISION : Revision Requested
    NEEDS_REVISION --> UNDER_REVIEW : Provider Resubmits
    APPROVED --> PAID : Admin Disburses Payout
    PARTIALLY_APPROVED --> PAID : Admin Disburses Payout
    REJECTED --> [*]
    PAID --> [*]

Loading

---

👥 User Guides (All 3 Platform Roles)

🩺 1. Healthcare Provider Guide (provider)

Providers submit and manage medical claims for patient care.

• Submit New Claims:
  1. Fill in Patient Name, Policy Number, DOB, Procedure Details, and Itemized Line Items.
  2. Upload mandatory supporting documents (PDF, JPEG, PNG up to 5MB).
  3. Submit claim $\rightarrow$ moves to SUBMITTED status and notifies Reviewers in real time.
• Track Claim Statuses: View real-time status badges, itemized cost breakdowns, and patient responsibility on the Provider Dashboard.
• Revise & Resubmit Claims:
  1. If a claim is marked NEEDS_REVISION by a reviewer, click Edit & Resubmit.
  2. Update patient details, line item quantities/costs, or attach additional files.
  3. Resubmit $\rightarrow$ claim status moves to UNDER_REVIEW, emitting real-time WebSocket alerts ("Revised Claim Resubmitted for Review") to reviewers.
• Generate EOB Statements: Click Print EOB on any approved/paid claim to generate an official printable Explanation of Benefits (EOB) document.

---

🔍 2. Medical Reviewer Guide (reviewer)

Reviewers adjudicate claims, inspect medical documentation, and approve insurance payouts.

• Medical Review Queue: View all claims waiting for review sorted by submission/priority.
• Adjudicate Claims:
  • Approve Full Claim: Approves all line items $\rightarrow$ triggers backend Policy Engine calculation.
  • Partially Approve: Select specific line items to deny (e.g. uncovered cosmetic add-ons).
  • Request Revision (NEEDS_REVISION): Send claim back to provider with mandatory reviewer notes specifying missing documentation.
  • Reject Claim: Denies reimbursement for non-covered procedures.
• Live Coverage Preview: The adjudication modal queries the Policy Engine to preview exact Approved Charges, Deductible Applied, Insurer Payout (80%), and Patient Owes before submitting decisions.
• Smart Navigation: Click the Back arrow on any claim detail page to return to the exact origin list (/reviewer/claims, /reviewer/queue, or /reviewer/dashboard).

---

🛡️ 3. Platform Administrator Guide (admin)

Administrators oversee system operations, financial disbursements, fraud detection, and policy rules.

• Platform Analytics: Bird's-eye dashboard displaying total claims, pending queue, total insurance payout disbursed, and flagged fraud count.
• Dynamic System Policy Settings:
  • Annual Deductible (Default $500): Yearly deductible amount absorbed per policy year.
  • Coverage Rate (Default 80%): Percentage covered by insurance post-deductible.
  • Annual Coverage Limit (Default $10,000): Maximum insurance payout cap per calendar year.
• Rule-Based Fraud Audit:
  • Claims exceeding 3x the historical average cost for their procedure code are automatically flagged with an Audit Flagged badge.
  • Administrators can review the anomaly rationale and click Unflag Claim with audit logging.
• Disburse Payouts: Move APPROVED and PARTIALLY_APPROVED claims to final PAID status.
• Immutable Audit Trail: Inspect an uneditable log of every action, timestamp, performer, and note for full regulatory compliance.

---

💰 Dynamic Policy Engine Logic

The Policy Engine calculates insurance payouts and patient responsibility dynamically based on policy rules ($500 Annual Deductible, 80% Coverage Rate, $10,000 Annual Payout Limit):

📐 Step-by-Step Calculation Rules

1. Remaining Deductible = Max(0, $500 - Prior Deductible Met This Year)
2. Deductible Applied = Min(Approved Line Items Total, Remaining Deductible)
3. Eligible Amount Post-Deductible = Max(0, Approved Line Items Total - Deductible Applied)
4. Insurer Payout (80% Coinsurance) = Min(Eligible Amount * 80%, Remaining Annual Limit)
5. Patient Responsibility = Total Claimed Amount - Insurer Payout

---

📊 Real-World 2-Claim Example

Assume a policyholder has a $500 Annual Deductible and 80% Coverage Rate:

🔹 Claim 1 (Approved First — $800 Claimed)

• Approved Total: $800.00
• Deductible Applied: $500.00 (Satisfies full yearly $500 deductible)
• Eligible Amount Post-Deductible: $800.00 - $500.00 = $300.00
• Insurer Payout (80%): $300.00 × 80% = $240.00
• Patient Owes: $800.00 - $240.00 = $560.00 ($500 deductible + $60 coinsurance)

🔹 Claim 2 (Approved Second — $330 Claimed)

• Approved Total: $330.00
• Deductible Applied: $0.00 (Yearly $500 deductible already satisfied by Claim 1)
• Eligible Amount Post-Deductible: $330.00
• Insurer Payout (80%): $330.00 × 80% = $264.00
• Patient Owes: $330.00 - $264.00 = $66.00 (20% coinsurance only)

Note

Approval Order Principle: Deductible accumulation orders prior claims by Approval Order (updatedAt), ensuring that whichever claim is approved first absorbs the yearly deductible.

---

🚨 Rule-Based Fraud Detection Engine

ClaimCare includes an automated, rule-based anomaly detection engine that evaluates every claim upon submission:

1. Procedure Code Benchmark: Queries historical claims sharing the exact procedure code (e.g., CPT-99214).
2. 3x Historical Average Threshold: If a claim's totalClaimed exceeds 3× the historical average cost for that procedure code, the claim is automatically flagged for audit.
3. Audit Flagging & Rationale:
   • Sets flagged = true on the Mongoose claim document.
   • Saves a detailed flagReason explaining the variance (e.g., "Claimed amount ($4,500.00) exceeds 3x procedure code historical average ($1,200.00)").
4. Visibility & Admin Override:
   • Internal Only: Fraud badges are visible exclusively to Medical Reviewers and Platform Administrators (hidden from providers to prevent workflow manipulation).
   • Admin Unflagging: Administrators can inspect the audit trail and click Unflag Claim to clear false positives with full audit logging.

---

🚀 Getting Started & Local Setup

Prerequisites

• Node.js (v22+ recommended)
• MongoDB (Local instance or Atlas URI)

---

1. Backend Setup (/backend)

# Navigate to backend directory
cd backend

# Install dependencies
npm install

# Create environment configuration file (.env)
cat <<EOT > .env
PORT=5000
MONGO_URI=mongodb://127.0.0.1:27017/claimcare
JWT_SECRET=super_secret_jwt_key_claimcare_2026
NODE_ENV=development
EOT

# Run Backend Unit Tests (Coverage Engine)
npm run test

# Start Express server (with hot-reloading)
npm run dev

Backend server will start at http://localhost:5000.

---

2. Frontend Setup (/frontend)

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Create local environment configuration (.env.local)
cat <<EOT > .env.local
NEXT_PUBLIC_API_URL=http://localhost:5000/api
EOT

# Start Next.js development server
npm run dev

Frontend application will start at http://localhost:3000.

---

📚 Interactive API Documentation (Swagger / OpenAPI 3.0)

• Interactive Swagger UI: http://localhost:5000/api-docs
• OpenAPI 3.0 JSON Spec: http://localhost:5000/api-docs/json

---

📂 Repository Directory Structure

claimcare/
├── backend/                  # Express / Node.js API
│   ├── src/
│   │   ├── config/           # OpenAPI / Swagger & policy defaults
│   │   ├── controllers/      # Route controllers (Express handlers)
│   │   ├── middleware/       # Auth JWT, Multer Upload & Validation
│   │   ├── models/           # Mongoose schemas (Claim, User, AuditLog)
│   │   ├── repositories/     # Data Access Layer
│   │   ├── routes/           # Express API routers
│   │   ├── services/         # Domain Business Logic Layer
│   │   └── tests/            # Unit tests for Policy Engine
│   └── package.json
└── frontend/                 # Next.js 14 App Router App
    ├── src/
    │   ├── app/              # Thin page route wrappers
    │   ├── components/       # Global UI components (NotificationCenter, EOB PDF)
    │   ├── features/         # Feature-Sliced Design modules
    │   │   ├── admin/        # Admin dashboard & settings
    │   │   ├── auth/         # Login & Register view components
    │   │   ├── claims/       # Provider submission & claim details
    │   │   └── review/       # Reviewer queue & adjudication modal
    │   └── lib/              # Axios API client & helpers
    └── package.json