gowtham943/claims-auditor-api

Purpose and Entry Points

Claims Auditor is an async FastAPI backend for user-scoped insurance-policy ingestion, claim auditing, and policy RAG chat. Application startup is main.py; HTTP routers are under routes/, and live pipeline status is exposed through routes/websocket.py. Deployment runs Uvicorn directly or the API container in docker-compose.yml.

API, Identity, and Request Boundary

The API exposes login/enrollment, policy and claim ingestion, RAG querying, health, and WebSocket tracking. JWT authentication establishes the requesting user; protected ingestion/chat requests must remain scoped to that identity.

• routes/auth_route.py

• routes/policy_ingestion.py

• routes/claim_ingestion.py

• config/auth.py

• routes/websocket.py

Policy Ingestion Pipeline

A policy PDF/DOCX upload is sent to Docling Serve for layout-aware Markdown extraction. The RAG engine chunks extracted content, creates Gemini embeddings, and persists policy metadata and vector-bearing chunks for later retrieval. Policy ownership is attached to the authenticated user.

• services/docling_extraction_service.py

• services/document_extraction_service.py

• rag_engine/policy_rag_engine.py

• models/policy_rule_book.py

• models/policy_chunks.py

Retrieval-Augmented Chat

Chat receives a question plus an ingested policy context. It retrieves semantically similar policy chunks from PostgreSQL/pgvector, then uses Gemini to form an answer grounded in those retrieved passages. Repository boundaries separate vector/database operations from route orchestration.

• routes/rag_chat.py

• rag_engine/policy_rag_engine.py

• repositories/rag_repository.py

• models/rag_schema.py

Claim Audit Pipeline

Claim documents enter through the claim-ingestion route, are extracted, and are audited against relevant policy rules using Gemini. Structured audit output—including violations and report schema—is stored as a claim submission/audit record and returned through list/detail endpoints.

• routes/claim_ingestion.py

• auditor/claims_auditor.py

• auditor/audit_report_schema.py

• auditor/violation_details.py

• models/claim_submission.py

Persistence and Domain Boundaries

SQLModel/SQLAlchemy repositories isolate persistence for users, policies, claims, and RAG data. PostgreSQL with pgvector is the durable system of record; Alembic defines the initial schema plus user ownership and policy-chunk evolution.

• repositories/user_repo.py

• repositories/policy_repo.py

• repositories/claim_repo.py

• models/user.py

• alembic/versions/d06295830475_initial_schema.py

• alembic/versions/1197f050d347_add_policy_chunk_table.py

Progress and Runtime Infrastructure

Long-running ingestion and audit stages emit tracking events through a WebSocket connection manager, allowing a dashboard to observe parsing, indexing, and audit progress independently of HTTP submission. The deployed topology is API + PostgreSQL/pgvector + separate Docling Serve; Gemini is an external API for embeddings, audit reasoning, and answers.

• ws_manager/connection_manager.py

• enums/pipeline_step.py

• docker-compose.yml

• config/database_config.py

• config/config_setting.py