# wcthls/claimsguru architecture

> Architecture diagram of the GitHub repository wcthls/claimsguru, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wcthls/claimsguru
- Repository: https://github.com/wcthls/claimsguru

## Overview

ClaimGPT accepts claim documents through its web/API entry points, stores them, and runs an OCR-to-validation workflow before offering coding, risk/fraud analysis, search and chat, and payer-ready submission outputs. The README documents the service-level workflow and capabilities; sampled code confirms selected internal implementations, but most service-to-service HTTP wiring was not included, so those links are documented rather than inferred from imports.

Main entry points: [`libs/shared/models.py`](https://github.com/wcthls/claimsguru/blob/main/libs/shared/models.py) (Claims database), [`services/workflow/app/pipeline.py`](https://github.com/wcthls/claimsguru/blob/main/services/workflow/app/pipeline.py) (Workflow orchestration), [`services/submission/app/main.py`](https://github.com/wcthls/claimsguru/blob/main/services/submission/app/main.py) (Submission service), [`services/ingress/app/main.py`](https://github.com/wcthls/claimsguru/blob/main/services/ingress/app/main.py) (Upload and ingress)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and access"]
  node_web["Web UI"]
  node_admin["Admin UI"]
  node_gateway["API gateway<br/>[main.py]"]
end

subgraph group_processing["Claim processing"]
  node_ingress["Upload and ingress<br/>[main.py]"]
  node_ocr["OCR and scans<br/>[engine.py]"]
  node_parser["Document parsing<br/>[engine.py]"]
  node_parser_v2["Layout extraction<br/>[pipeline.py]"]
  node_workflow["Workflow orchestration<br/>[pipeline.py]"]
  node_tasks["Async processing<br/>[shared_tasks.py]"]
end

subgraph group_intelligence["Claim intelligence"]
  node_coding["Medical coding<br/>[engine.py]"]
  node_icd_rag["ICD-10 retrieval<br/>[icd10_rag.py]"]
  node_predictor["Rejection prediction<br/>[engine.py]"]
  node_fraud["Fraud detection<br/>[engine.py]"]
  node_validator["Rule validation<br/>[rules.py]"]
  node_chat["Claim chat<br/>[main.py]"]
  node_search["Claim search<br/>[main.py]"]
end

subgraph group_outcomes["Review and submission"]
  node_submission["Submission service<br/>[main.py]"]
  node_tpa_pdf["TPA reports<br/>[tpa_pdf.py]"]
  node_irda_pdf["IRDAI forms<br/>[irda_pdf.py]"]
end

subgraph group_platform["Shared platform"]
  node_storage[("Document storage<br/>[storage.py]")]
  node_claims_db[("Claims database<br/>[models.py]")]
end

node_user(("Claim user"))
node_ollama["Ollama LLM"]
node_payer["Payer systems"]

node_user -->|"uploads and reviews"| node_web
node_web -->|"calls REST/SSE"| node_gateway
node_admin -->|"calls REST"| node_gateway
node_gateway -->|"routes requests"| node_ingress
node_ingress -->|"stores documents"| node_storage
node_ingress -->|"records claims"| node_claims_db
node_workflow -->|"runs OCR"| node_ocr
node_workflow -->|"runs parsing"| node_parser
node_workflow -->|"runs coding"| node_coding
node_workflow -->|"scores risk"| node_predictor
node_workflow -->|"runs rules"| node_validator
node_ingress -->|"queues processing"| node_tasks
node_tasks -->|"runs OCR jobs"| node_ocr
node_ocr -->|"reads documents"| node_storage
node_parser -->|"invokes layout pipeline"| node_parser_v2
node_parser -->|"persists extracted fields"| node_claims_db
node_coding -->|"retrieves code matches"| node_icd_rag
node_predictor -.->|"persists predictions"| node_claims_db
node_fraud -->|"supplies fraud risk"| node_validator
node_chat -->|"generates responses"| node_ollama
node_chat -.->|"retrieves claim context"| node_search
node_chat -.->|"reads claim context"| node_claims_db
node_search -.->|"searches claim data"| node_claims_db
node_submission -->|"generates reports"| node_tpa_pdf
node_submission -->|"generates forms"| node_irda_pdf
node_submission -->|"records submissions"| node_claims_db
node_submission -.->|"submits claims"| node_payer
node_claims_db -.->|"serves claim results"| node_web

click node_web "https://github.com/wcthls/claimsguru/tree/main/ui/web"
click node_admin "https://github.com/wcthls/claimsguru/tree/main/ui/admin"
click node_gateway "https://github.com/wcthls/claimsguru/blob/main/main.py"
click node_ingress "https://github.com/wcthls/claimsguru/blob/main/services/ingress/app/main.py"
click node_storage "https://github.com/wcthls/claimsguru/blob/main/libs/shared/storage.py"
click node_ocr "https://github.com/wcthls/claimsguru/blob/main/services/ocr/app/engine.py"
click node_parser "https://github.com/wcthls/claimsguru/blob/main/services/parser/app/engine.py"
click node_parser_v2 "https://github.com/wcthls/claimsguru/blob/main/services/parser_v2/pipeline.py"
click node_workflow "https://github.com/wcthls/claimsguru/blob/main/services/workflow/app/pipeline.py"
click node_tasks "https://github.com/wcthls/claimsguru/blob/main/services/shared_tasks.py"
click node_coding "https://github.com/wcthls/claimsguru/blob/main/services/coding/app/engine.py"
click node_icd_rag "https://github.com/wcthls/claimsguru/blob/main/services/coding/app/icd10_rag.py"
click node_predictor "https://github.com/wcthls/claimsguru/blob/main/services/predictor/app/engine.py"
click node_fraud "https://github.com/wcthls/claimsguru/blob/main/services/fraud/app/engine.py"
click node_validator "https://github.com/wcthls/claimsguru/blob/main/services/validator/app/rules.py"
click node_chat "https://github.com/wcthls/claimsguru/blob/main/services/chat/app/main.py"
click node_search "https://github.com/wcthls/claimsguru/blob/main/services/search/app/main.py"
click node_submission "https://github.com/wcthls/claimsguru/blob/main/services/submission/app/main.py"
click node_tpa_pdf "https://github.com/wcthls/claimsguru/blob/main/services/submission/app/tpa_pdf.py"
click node_irda_pdf "https://github.com/wcthls/claimsguru/blob/main/services/submission/app/irda_pdf.py"
click node_claims_db "https://github.com/wcthls/claimsguru/blob/main/libs/shared/models.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_admin,node_gateway,node_user toneBlue
class node_ingress,node_ocr,node_parser,node_parser_v2,node_workflow,node_tasks toneAmber
class node_coding,node_icd_rag,node_predictor,node_fraud,node_validator,node_chat,node_search toneMint
class node_submission,node_tpa_pdf,node_irda_pdf toneRose
class node_storage,node_claims_db,node_ollama,node_payer toneIndigo
```

## Components

### Entry and access

- [Web UI](https://github.com/wcthls/claimsguru/tree/main/ui/web): `ui/web`
- [Admin UI](https://github.com/wcthls/claimsguru/tree/main/ui/admin): `ui/admin`
- [API gateway](https://github.com/wcthls/claimsguru/blob/main/main.py): `main.py`

### Claim processing

- [Upload and ingress](https://github.com/wcthls/claimsguru/blob/main/services/ingress/app/main.py): `services/ingress/app/main.py`
- [OCR and scans](https://github.com/wcthls/claimsguru/blob/main/services/ocr/app/engine.py): `services/ocr/app/engine.py`
- [Document parsing](https://github.com/wcthls/claimsguru/blob/main/services/parser/app/engine.py): `services/parser/app/engine.py`
- [Layout extraction](https://github.com/wcthls/claimsguru/blob/main/services/parser_v2/pipeline.py): `services/parser_v2/pipeline.py`
- [Workflow orchestration](https://github.com/wcthls/claimsguru/blob/main/services/workflow/app/pipeline.py): `services/workflow/app/pipeline.py`
- [Async processing](https://github.com/wcthls/claimsguru/blob/main/services/shared_tasks.py): `services/shared_tasks.py`

### Claim intelligence

- [Medical coding](https://github.com/wcthls/claimsguru/blob/main/services/coding/app/engine.py): `services/coding/app/engine.py`
- [ICD-10 retrieval](https://github.com/wcthls/claimsguru/blob/main/services/coding/app/icd10_rag.py): `services/coding/app/icd10_rag.py`
- [Rejection prediction](https://github.com/wcthls/claimsguru/blob/main/services/predictor/app/engine.py): `services/predictor/app/engine.py`
- [Fraud detection](https://github.com/wcthls/claimsguru/blob/main/services/fraud/app/engine.py): `services/fraud/app/engine.py`
- [Rule validation](https://github.com/wcthls/claimsguru/blob/main/services/validator/app/rules.py): `services/validator/app/rules.py`
- [Claim chat](https://github.com/wcthls/claimsguru/blob/main/services/chat/app/main.py): `services/chat/app/main.py`
- [Claim search](https://github.com/wcthls/claimsguru/blob/main/services/search/app/main.py): `services/search/app/main.py`

### Review and submission

- [Submission service](https://github.com/wcthls/claimsguru/blob/main/services/submission/app/main.py): `services/submission/app/main.py`
- [TPA reports](https://github.com/wcthls/claimsguru/blob/main/services/submission/app/tpa_pdf.py): `services/submission/app/tpa_pdf.py`
- [IRDAI forms](https://github.com/wcthls/claimsguru/blob/main/services/submission/app/irda_pdf.py): `services/submission/app/irda_pdf.py`

### Shared platform

- [Document storage](https://github.com/wcthls/claimsguru/blob/main/libs/shared/storage.py): `libs/shared/storage.py`
- [Claims database](https://github.com/wcthls/claimsguru/blob/main/libs/shared/models.py): `libs/shared/models.py`

### Other components

- **Claim user**
- **Ollama LLM**
- **Payer systems**

## Connections

- Claim user → Web UI: uploads and reviews (evidence: `README.md`)
- Web UI → API gateway: calls REST/SSE (evidence: `README.md`)
- Admin UI → API gateway: calls REST (evidence: `README.md`)
- API gateway → Upload and ingress: routes requests (evidence: `README.md`)
- Upload and ingress → Document storage: stores documents (evidence: `services/ingress/app/main.py`)
- Upload and ingress → Claims database: records claims (evidence: `services/ingress/app/main.py`)
- Workflow orchestration → OCR and scans: runs OCR (evidence: `README.md`)
- Workflow orchestration → Document parsing: runs parsing (evidence: `README.md`)
- Workflow orchestration → Medical coding: runs coding (evidence: `README.md`)
- Workflow orchestration → Rejection prediction: scores risk (evidence: `README.md`)
- Workflow orchestration → Rule validation: runs rules (evidence: `README.md`)
- Upload and ingress → Async processing: queues processing (evidence: `services/ingress/app/main.py`)
- Async processing → OCR and scans: runs OCR jobs (evidence: `services/shared_tasks.py`)
- OCR and scans → Document storage: reads documents (evidence: `services/ocr/app/engine.py`)
- Document parsing → Layout extraction: invokes layout pipeline (evidence: `services/parser/app/main.py`)
- Document parsing → Claims database: persists extracted fields
- Medical coding → ICD-10 retrieval: retrieves code matches (evidence: `services/coding/app/engine.py`)
- Rejection prediction → Claims database: persists predictions
- Fraud detection → Rule validation: supplies fraud risk (evidence: `README.md`)
- Claim chat → Ollama LLM: generates responses (evidence: `README.md`)
- Claim chat → Claim search: retrieves claim context
- Claim chat → Claims database: reads claim context
- Claim search → Claims database: searches claim data
- Submission service → TPA reports: generates reports (evidence: `services/submission/app/main.py`)
- Submission service → IRDAI forms: generates forms (evidence: `services/submission/app/main.py`)
- Submission service → Claims database: records submissions (evidence: `services/submission/app/main.py`)
- Submission service → Payer systems: submits claims
- Claims database → Web UI: serves claim results
