# supriya090/llm-clinical-coding-audit architecture

> Architecture diagram of the GitHub repository supriya090/llm-clinical-coding-audit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/supriya090/llm-clinical-coding-audit
- Repository: https://github.com/supriya090/llm-clinical-coding-audit

## Overview

This is a code-only reference implementation for interpretable clinical ICD coding and audit. Its principal workflow prepares discharge-note evidence, predicts codes using a classifier trained with embedding-matched silver evidence, then verifies candidate codes with LLMs; audit and evaluation modules support error analysis. The README and excerpts establish the major stages, but do not show a single orchestrator or all inter-module handoffs, so some documented pipeline links are represented at subsystem level.

Main entry points: [`src/preprocessing/section_splitting.py`](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/preprocessing/section_splitting.py) (Section splitting), [`src/prompts.py`](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/prompts.py) (Shared prompts), [`src/verification/deepseek_verifier.py`](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/verification/deepseek_verifier.py) (DeepSeek verification), [`src/code_classifier/inference.py`](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/code_classifier/inference.py) (Code inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Note preparation"]
  node_preprocess["Section splitting"]
  node_negation["Negation filtering"]
end

subgraph group_evidence["Evidence generation"]
  node_silver["Silver matching"]
  node_extract_prompt["Shared prompts<br/>[prompts.py]"]
  node_gpt_extract["GPT extraction<br/>[gpt_extractor.py]"]
  node_gemini_extract["Gemini extraction"]
  node_deepseek_extract["DeepSeek extraction"]
end

subgraph group_coding["Code prediction"]
  node_train["Classifier training"]
  node_inference["Code inference<br/>[inference.py]"]
end

subgraph group_verify["Code verification"]
  node_gpt_verify["GPT verification<br/>[gpt_verifier.py]"]
  node_gemini_verify["Gemini verification<br/>[gemini_verifier.py]"]
  node_deepseek_verify["DeepSeek verification"]
end

subgraph group_analysis["Audit and evaluation"]
  node_audit_crosscheck["Ensemble crosscheck"]
  node_iaa["Agreement analysis<br/>[iaa_analysis.py]"]
  node_reporting["Audit reporting<br/>[reporting.py]"]
  node_metrics["Code metrics<br/>[metrics.py]"]
end

node_clinical_data["Clinical notes"]
node_llm_services{{"LLM services"}}
node_audit_results["Audit results"]

node_clinical_data -->|"provides notes"| node_preprocess
node_preprocess -->|"filters phrases"| node_negation
node_preprocess -->|"supplies candidates"| node_silver
node_preprocess -->|"supplies candidates"| node_gpt_extract
node_preprocess -->|"supplies candidates"| node_gemini_extract
node_preprocess -->|"supplies candidates"| node_deepseek_extract
node_silver -->|"creates training data"| node_train
node_gpt_extract -->|"uses templates"| node_extract_prompt
node_gemini_extract -->|"uses templates"| node_extract_prompt
node_deepseek_extract -->|"uses templates"| node_extract_prompt
node_gpt_extract -->|"requests extraction"| node_llm_services
node_gemini_extract -->|"requests extraction"| node_llm_services
node_deepseek_extract -->|"requests extraction"| node_llm_services
node_train -->|"produces model"| node_inference
node_inference -->|"provides candidate codes"| node_gpt_verify
node_inference -->|"provides candidate codes"| node_gemini_verify
node_inference -->|"provides candidate codes"| node_deepseek_verify
node_gpt_verify -->|"uses templates"| node_extract_prompt
node_gemini_verify -->|"uses templates"| node_extract_prompt
node_deepseek_verify -->|"uses templates"| node_extract_prompt
node_gpt_verify -->|"requests verification"| node_llm_services
node_gemini_verify -->|"requests verification"| node_llm_services
node_deepseek_verify -->|"requests verification"| node_llm_services
node_deepseek_verify -->|"informs undercoding audit"| node_audit_crosscheck
node_gpt_verify -->|"writes verification output"| node_audit_results
node_gemini_verify -->|"writes verification output"| node_audit_results
node_deepseek_verify -->|"writes verification output"| node_audit_results
node_audit_crosscheck -->|"supports audit"| node_audit_results
node_iaa -->|"reports agreement"| node_audit_results
node_reporting -->|"reports findings"| node_audit_results
node_metrics -->|"measures performance"| node_audit_results

click node_preprocess "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/preprocessing/section_splitting.py"
click node_negation "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/preprocessing/negation_removal.py"
click node_silver "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/silver_evidence/embedding_matching.py"
click node_extract_prompt "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/prompts.py"
click node_gpt_extract "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/evidence_extraction/gpt_extractor.py"
click node_gemini_extract "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/evidence_extraction/gemini_extractor.py"
click node_deepseek_extract "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/evidence_extraction/deepseek_extractor.py"
click node_train "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/code_classifier/train_classifier.py"
click node_inference "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/code_classifier/inference.py"
click node_gpt_verify "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/verification/gpt_verifier.py"
click node_gemini_verify "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/verification/gemini_verifier.py"
click node_deepseek_verify "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/verification/deepseek_verifier.py"
click node_audit_crosscheck "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/audit/ensemble_crosscheck.py"
click node_iaa "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/audit/iaa_analysis.py"
click node_reporting "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/audit/reporting.py"
click node_metrics "https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/evaluation/metrics.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_preprocess,node_negation toneBlue
class node_silver,node_extract_prompt,node_gpt_extract,node_gemini_extract,node_deepseek_extract toneAmber
class node_train,node_inference toneMint
class node_gpt_verify,node_gemini_verify,node_deepseek_verify toneRose
class node_audit_crosscheck,node_iaa,node_reporting,node_metrics,node_clinical_data,node_llm_services,node_audit_results toneIndigo
```

## Components

### Note preparation

- [Section splitting](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/preprocessing/section_splitting.py): `src/preprocessing/section_splitting.py`
- [Negation filtering](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/preprocessing/negation_removal.py): `src/preprocessing/negation_removal.py`

### Evidence generation

- [Silver matching](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/silver_evidence/embedding_matching.py): `src/silver_evidence/embedding_matching.py`
- [Shared prompts](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/prompts.py): `src/prompts.py`
- [GPT extraction](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/evidence_extraction/gpt_extractor.py): `src/evidence_extraction/gpt_extractor.py`
- [Gemini extraction](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/evidence_extraction/gemini_extractor.py): `src/evidence_extraction/gemini_extractor.py`
- [DeepSeek extraction](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/evidence_extraction/deepseek_extractor.py): `src/evidence_extraction/deepseek_extractor.py`

### Code prediction

- [Classifier training](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/code_classifier/train_classifier.py): `src/code_classifier/train_classifier.py`
- [Code inference](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/code_classifier/inference.py): `src/code_classifier/inference.py`

### Code verification

- [GPT verification](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/verification/gpt_verifier.py): `src/verification/gpt_verifier.py`
- [Gemini verification](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/verification/gemini_verifier.py): `src/verification/gemini_verifier.py`
- [DeepSeek verification](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/verification/deepseek_verifier.py): `src/verification/deepseek_verifier.py`

### Audit and evaluation

- [Ensemble crosscheck](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/audit/ensemble_crosscheck.py): `src/audit/ensemble_crosscheck.py`
- [Agreement analysis](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/audit/iaa_analysis.py): `src/audit/iaa_analysis.py`
- [Audit reporting](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/audit/reporting.py): `src/audit/reporting.py`
- [Code metrics](https://github.com/supriya090/llm-clinical-coding-audit/blob/main/src/evaluation/metrics.py): `src/evaluation/metrics.py`

### Other components

- **Clinical notes**
- **LLM services**
- **Audit results**

## Connections

- Clinical notes → Section splitting: provides notes (evidence: `README.md`)
- Section splitting → Negation filtering: filters phrases (evidence: `src/preprocessing/section_splitting.py`)
- Section splitting → Silver matching: supplies candidates (evidence: `src/preprocessing/section_splitting.py`)
- Section splitting → GPT extraction: supplies candidates (evidence: `src/preprocessing/section_splitting.py`)
- Section splitting → Gemini extraction: supplies candidates (evidence: `src/preprocessing/section_splitting.py`)
- Section splitting → DeepSeek extraction: supplies candidates (evidence: `src/preprocessing/section_splitting.py`)
- Silver matching → Classifier training: creates training data (evidence: `src/silver_evidence/embedding_matching.py`)
- GPT extraction → Shared prompts: uses templates (evidence: `src/evidence_extraction/gpt_extractor.py`)
- Gemini extraction → Shared prompts: uses templates (evidence: `src/evidence_extraction/gemini_extractor.py`)
- DeepSeek extraction → Shared prompts: uses templates (evidence: `src/evidence_extraction/deepseek_extractor.py`)
- GPT extraction → LLM services: requests extraction (evidence: `src/evidence_extraction/gpt_extractor.py`)
- Gemini extraction → LLM services: requests extraction (evidence: `src/evidence_extraction/gemini_extractor.py`)
- DeepSeek extraction → LLM services: requests extraction (evidence: `src/evidence_extraction/deepseek_extractor.py`)
- Classifier training → Code inference: produces model (evidence: `README.md`)
- Code inference → GPT verification: provides candidate codes (evidence: `README.md`)
- Code inference → Gemini verification: provides candidate codes (evidence: `README.md`)
- Code inference → DeepSeek verification: provides candidate codes (evidence: `README.md`)
- GPT verification → Shared prompts: uses templates (evidence: `src/verification/gpt_verifier.py`)
- Gemini verification → Shared prompts: uses templates (evidence: `src/verification/gemini_verifier.py`)
- DeepSeek verification → Shared prompts: uses templates (evidence: `src/verification/deepseek_verifier.py`)
- GPT verification → LLM services: requests verification (evidence: `src/verification/gpt_verifier.py`)
- Gemini verification → LLM services: requests verification (evidence: `src/verification/gemini_verifier.py`)
- DeepSeek verification → LLM services: requests verification (evidence: `src/verification/deepseek_verifier.py`)
- DeepSeek verification → Ensemble crosscheck: informs undercoding audit (evidence: `src/verification/deepseek_verifier.py`)
- GPT verification → Audit results: writes verification output (evidence: `src/verification/gpt_verifier.py`)
- Gemini verification → Audit results: writes verification output (evidence: `src/verification/gemini_verifier.py`)
- DeepSeek verification → Audit results: writes verification output (evidence: `src/verification/deepseek_verifier.py`)
- Ensemble crosscheck → Audit results: supports audit (evidence: `README.md`)
- Agreement analysis → Audit results: reports agreement (evidence: `README.md`)
- Audit reporting → Audit results: reports findings (evidence: `README.md`)
- Code metrics → Audit results: measures performance (evidence: `README.md`)
