# wassimkraiem243/claimguardai architecture

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

- Interactive diagram: https://gitdiagram.com/wassimkraiem243/claimguardai
- Repository: https://github.com/wassimkraiem243/claimguardai

## Overview

ClaimGuard AI turns uploaded healthcare claims into normalized envelopes, validates them against 15 payer rules, and presents results for human review. The Phase 1 UI drives ingestion and validation through the FastAPI API; the engine records auditable outcomes. Separate dashboard and findings capabilities support seeded findings and optional Ollama explanations. The sampled sources show the core ingestion, validation, audit, and UI calls; unsampled dashboard and findings wiring is shown only where documented, with uncertain links omitted.

Main entry points: [`apps/api/app/infrastructure/rule_engine/core/engine.py`](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/infrastructure/rule_engine/core/engine.py) (Rule engine), [`apps/api/app/routers/validation.py`](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/routers/validation.py) (Validation route), [`apps/web/lib/phase1-api.ts`](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/web/lib/phase1-api.ts) (Web API client), [`apps/api/app/services/ingest_claim.py`](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/services/ingest_claim.py) (Ingestion use case)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User experience"]
  node_flow["Phase 1 flow"]
  node_webapi["Web API client<br/>[phase1-api.ts]"]
end

subgraph group_api["API workflows"]
  node_apiapp["FastAPI application<br/>[main.py]"]
  node_claims["Claim ingestion route<br/>[claims.py]"]
  node_ingest["Ingestion use case<br/>[ingest_claim.py]"]
  node_parsers["Format parsers"]
  node_mapping["Envelope mapping<br/>[normalizer.py]"]
  node_envelope["Normalized claim"]
  node_validation["Validation route<br/>[validation.py]"]
  node_validation_service["Validation service<br/>[rule_validation.py]"]
end

subgraph group_engine["Validation engine"]
  node_engine["Rule engine<br/>[engine.py]"]
  node_context["Claim context<br/>[context.py]"]
  node_rules["R001–R015 rules"]
  node_policy[("Policy store<br/>[policy_store.py]")]
end

subgraph group_insights["Insights and state"]
  node_audit_hook["Audit adapter<br/>[audit_hook.py]"]
  node_audit[("Audit log<br/>[audit_log.py]")]
  node_findings["Findings and analysis<br/>[findings.py]"]
  node_ollama["Ollama analysis<br/>[ollama.py]"]
  node_dashboard["Dashboard and metrics<br/>[dashboard.py]"]
  node_storage[("Application storage<br/>[store.py]")]
end

node_user(("Claim reviewer"))

node_user -->|"uses"| node_flow
node_flow -->|"requests"| node_webapi
node_webapi -->|"uploads claims"| node_claims
node_webapi -->|"submits envelope"| node_validation
node_apiapp -->|"registers"| node_claims
node_apiapp -->|"registers"| node_validation
node_claims -.->|"ingests upload"| node_ingest
node_ingest -->|"selects parser"| node_parsers
node_parsers -->|"normalizes claim"| node_mapping
node_ingest -->|"returns claims"| node_envelope
node_validation -->|"audits validation"| node_audit_hook
node_validation -->|"delegates validation"| node_validation_service
node_validation_service -->|"validates claim"| node_engine
node_audit_hook -->|"runs validation"| node_engine
node_engine -->|"builds context"| node_context
node_engine -->|"loads policy"| node_policy
node_engine -->|"dispatches rules"| node_rules
node_audit_hook -->|"writes audit events"| node_audit
node_findings -.->|"explains findings"| node_ollama
node_dashboard -.->|"reads dashboard data"| node_storage

click node_flow "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/web/components/PreSubmissionFlow.tsx"
click node_webapi "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/web/lib/phase1-api.ts"
click node_apiapp "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/main.py"
click node_claims "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/routers/claims.py"
click node_ingest "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/services/ingest_claim.py"
click node_parsers "https://github.com/wassimkraiem243/claimguardai/tree/main/apps/api/app/infrastructure/parsers"
click node_mapping "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/mappers/normalizer.py"
click node_envelope "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/domain/normalized_claim.py"
click node_validation "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/routers/validation.py"
click node_validation_service "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/services/rule_validation.py"
click node_engine "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/infrastructure/rule_engine/core/engine.py"
click node_context "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/infrastructure/rule_engine/core/context.py"
click node_rules "https://github.com/wassimkraiem243/claimguardai/tree/main/apps/api/app/infrastructure/rule_engine/rules"
click node_policy "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/infrastructure/rule_engine/stores/policy_store.py"
click node_audit_hook "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/infrastructure/rule_engine/audit_hook.py"
click node_audit "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/infrastructure/audit_log.py"
click node_findings "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/routers/findings.py"
click node_ollama "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/infrastructure/ollama.py"
click node_dashboard "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/routers/dashboard.py"
click node_storage "https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/repositories/store.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_flow,node_webapi,node_user toneBlue
class node_apiapp,node_claims,node_ingest,node_parsers,node_mapping,node_envelope,node_validation,node_validation_service toneAmber
class node_engine,node_context,node_rules,node_policy toneMint
class node_audit_hook,node_audit,node_findings,node_ollama,node_dashboard,node_storage toneRose
```

## Components

### User experience

- [Phase 1 flow](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/web/components/PreSubmissionFlow.tsx): `apps/web/components/PreSubmissionFlow.tsx`
- [Web API client](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/web/lib/phase1-api.ts): `apps/web/lib/phase1-api.ts`

### API workflows

- [FastAPI application](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Claim ingestion route](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/routers/claims.py): `apps/api/app/routers/claims.py`
- [Ingestion use case](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/services/ingest_claim.py): `apps/api/app/services/ingest_claim.py`
- [Format parsers](https://github.com/wassimkraiem243/claimguardai/tree/main/apps/api/app/infrastructure/parsers): `apps/api/app/infrastructure/parsers`
- [Envelope mapping](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/mappers/normalizer.py): `apps/api/app/mappers/normalizer.py`
- [Normalized claim](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/domain/normalized_claim.py): `apps/api/app/domain/normalized_claim.py`
- [Validation route](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/routers/validation.py): `apps/api/app/routers/validation.py`
- [Validation service](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/services/rule_validation.py): `apps/api/app/services/rule_validation.py`

### Validation engine

- [Rule engine](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/infrastructure/rule_engine/core/engine.py): `apps/api/app/infrastructure/rule_engine/core/engine.py`
- [Claim context](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/infrastructure/rule_engine/core/context.py): `apps/api/app/infrastructure/rule_engine/core/context.py`
- [R001–R015 rules](https://github.com/wassimkraiem243/claimguardai/tree/main/apps/api/app/infrastructure/rule_engine/rules): `apps/api/app/infrastructure/rule_engine/rules`
- [Policy store](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/infrastructure/rule_engine/stores/policy_store.py): `apps/api/app/infrastructure/rule_engine/stores/policy_store.py`

### Insights and state

- [Audit adapter](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/infrastructure/rule_engine/audit_hook.py): `apps/api/app/infrastructure/rule_engine/audit_hook.py`
- [Audit log](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/infrastructure/audit_log.py): `apps/api/app/infrastructure/audit_log.py`
- [Findings and analysis](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/routers/findings.py): `apps/api/app/routers/findings.py`
- [Ollama analysis](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/infrastructure/ollama.py): `apps/api/app/infrastructure/ollama.py`
- [Dashboard and metrics](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/routers/dashboard.py): `apps/api/app/routers/dashboard.py`
- [Application storage](https://github.com/wassimkraiem243/claimguardai/blob/main/apps/api/app/repositories/store.py): `apps/api/app/repositories/store.py`

### Other components

- **Claim reviewer**

## Connections

- Claim reviewer → Phase 1 flow: uses (evidence: `README.md`)
- Phase 1 flow → Web API client: requests (evidence: `apps/web/components/PreSubmissionFlow.tsx`)
- Web API client → Claim ingestion route: uploads claims (evidence: `README.md`)
- Web API client → Validation route: submits envelope (evidence: `README.md`)
- FastAPI application → Claim ingestion route: registers (evidence: `apps/api/app/main.py`)
- FastAPI application → Validation route: registers (evidence: `apps/api/app/main.py`)
- Claim ingestion route → Ingestion use case: ingests upload
- Ingestion use case → Format parsers: selects parser (evidence: `apps/api/app/services/ingest_claim.py`)
- Format parsers → Envelope mapping: normalizes claim (evidence: `apps/api/app/infrastructure/parsers/pack_fhir_parser.py`)
- Ingestion use case → Normalized claim: returns claims (evidence: `apps/api/app/services/ingest_claim.py`)
- Validation route → Audit adapter: audits validation (evidence: `apps/api/app/routers/validation.py`)
- Validation route → Validation service: delegates validation (evidence: `apps/api/app/routers/validation.py`)
- Validation service → Rule engine: validates claim (evidence: `apps/api/app/routers/validation.py`)
- Audit adapter → Rule engine: runs validation (evidence: `apps/api/app/infrastructure/rule_engine/audit_hook.py`)
- Rule engine → Claim context: builds context (evidence: `apps/api/app/infrastructure/rule_engine/core/engine.py`)
- Rule engine → Policy store: loads policy (evidence: `apps/api/app/infrastructure/rule_engine/core/engine.py`)
- Rule engine → R001–R015 rules: dispatches rules (evidence: `apps/api/app/infrastructure/rule_engine/core/engine.py`)
- Audit adapter → Audit log: writes audit events (evidence: `apps/api/app/infrastructure/rule_engine/audit_hook.py`)
- Findings and analysis → Ollama analysis: explains findings
- Dashboard and metrics → Application storage: reads dashboard data
