# tukanzee/avt-testing architecture

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

- Interactive diagram: https://gitdiagram.com/tukanzee/avt-testing
- Repository: https://github.com/tukanzee/avt-testing

## Overview

Clinical Ground Truth Runner supports synthetic doctor–patient role-play, recording spoken facts, and exporting a ground-truth record. It also offers transcript-led AVT review and a separate Level 1 validator. The graph follows the documented workflows and sampled call/import relationships; the validator page and several of its internal stages were not excerpted, so their detailed wiring is not asserted.

Main entry points: [`src/validator/TranscriptAvtValidator.tsx`](https://github.com/tukanzee/avt-testing/blob/main/src/validator/TranscriptAvtValidator.tsx) (Transcript AVT workflow), [`src/App.tsx`](https://github.com/tukanzee/avt-testing/blob/main/src/App.tsx) (Application routing), [`src/validator/components/ClaimReview.tsx`](https://github.com/tukanzee/avt-testing/blob/main/src/validator/components/ClaimReview.tsx) (Claim review), [`src/validator/ValidatorPage.tsx`](https://github.com/tukanzee/avt-testing/blob/main/src/validator/ValidatorPage.tsx) (Validator entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scenario["Role-play scenarios"]
  node_app["Application routing<br/>[App.tsx]"]
  node_cases["Case catalogue<br/>[cases.ts]"]
  node_case_data["Clinical case scripts<br/>[dka.ts]"]
end

subgraph group_record["Ground-truth recording"]
  node_session["Spoken fact capture<br/>[App.tsx]"]
  node_json_export["JSON export<br/>[json.ts]"]
  node_pdf_export["PDF export<br/>[pdf.ts]"]
end

subgraph group_transcript["Transcript-led validation"]
  node_validator_page["Validator entry<br/>[ValidatorPage.tsx]"]
  node_transcript_workflow["Transcript AVT workflow"]
  node_transcript_parse["Transcript parsing<br/>[parseTranscript.ts]"]
  node_audio_prep["Audio preparation"]
  node_speaker_attribution["Speaker attribution"]
  node_local_transcription["Local transcription<br/>[localWhisper.ts]"]
  node_evidence_chunks["Evidence chunking"]
  node_claim_extraction["Atomic claim extraction<br/>[atomic.ts]"]
  node_evidence_matching["Evidence matching<br/>[evidenceMatcher.ts]"]
  node_browser_semantic["Local semantic models<br/>[browserSemantic.ts]"]
  node_claim_review["Claim review<br/>[ClaimReview.tsx]"]
  node_omission_review["Omission review<br/>[OmissionReview.tsx]"]
  node_findings_review["Findings review<br/>[FindingsReview.tsx]"]
end

subgraph group_level1["Level 1 validation"]
  node_level1_engine["Level 1 analysis<br/>[level1Engine.ts]"]
end

node_user(("Doctor / actor"))
node_reviewer(("Human reviewer"))

node_user -->|"uses"| node_app
node_app -->|"loads cases"| node_cases
node_cases -->|"catalogues"| node_case_data
node_app -->|"records spoken facts"| node_session
node_session -->|"exports JSON"| node_json_export
node_session -->|"exports PDF"| node_pdf_export
node_app -->|"opens validator"| node_validator_page
node_validator_page -.->|"offers workflow"| node_transcript_workflow
node_transcript_workflow -.->|"parses transcript"| node_transcript_parse
node_transcript_workflow -.->|"prepares audio"| node_audio_prep
node_audio_prep -.->|"transcribes locally"| node_local_transcription
node_speaker_attribution -->|"uses transcription"| node_local_transcription
node_transcript_workflow -.->|"attributes speakers"| node_speaker_attribution
node_transcript_workflow -.->|"builds evidence"| node_evidence_chunks
node_evidence_chunks -->|"extracts atomic claims"| node_claim_extraction
node_transcript_workflow -.->|"retrieves evidence"| node_evidence_matching
node_evidence_matching -.->|"checks entailment"| node_browser_semantic
node_transcript_workflow -.->|"presents claims"| node_claim_review
node_claim_review -->|"shows context"| node_evidence_chunks
node_claim_review -.->|"reviews omissions"| node_omission_review
node_transcript_workflow -.->|"reviews findings"| node_findings_review
node_reviewer -->|"reviews evidence"| node_claim_review
node_reviewer -->|"confirms omissions"| node_omission_review
node_reviewer -->|"reviews findings"| node_findings_review
node_validator_page -.->|"runs Level 1"| node_level1_engine
node_level1_engine -->|"judges statements"| node_browser_semantic

click node_app "https://github.com/tukanzee/avt-testing/blob/main/src/App.tsx"
click node_cases "https://github.com/tukanzee/avt-testing/blob/main/src/data/cases.ts"
click node_case_data "https://github.com/tukanzee/avt-testing/blob/main/src/data/cases/dka.ts"
click node_session "https://github.com/tukanzee/avt-testing/blob/main/src/App.tsx"
click node_json_export "https://github.com/tukanzee/avt-testing/blob/main/src/utils/json.ts"
click node_pdf_export "https://github.com/tukanzee/avt-testing/blob/main/src/utils/pdf.ts"
click node_validator_page "https://github.com/tukanzee/avt-testing/blob/main/src/validator/ValidatorPage.tsx"
click node_transcript_workflow "https://github.com/tukanzee/avt-testing/blob/main/src/validator/TranscriptAvtValidator.tsx"
click node_transcript_parse "https://github.com/tukanzee/avt-testing/blob/main/src/validator/transcript/parseTranscript.ts"
click node_audio_prep "https://github.com/tukanzee/avt-testing/blob/main/src/validator/components/AudioTranscriptPreparation.tsx"
click node_speaker_attribution "https://github.com/tukanzee/avt-testing/blob/main/src/validator/speakerAttribution/localAttribution.ts"
click node_local_transcription "https://github.com/tukanzee/avt-testing/blob/main/src/validator/transcription/localWhisper.ts"
click node_evidence_chunks "https://github.com/tukanzee/avt-testing/blob/main/src/validator/transcript/createEvidenceChunks.ts"
click node_claim_extraction "https://github.com/tukanzee/avt-testing/blob/main/src/validator/claimExtraction/atomic.ts"
click node_evidence_matching "https://github.com/tukanzee/avt-testing/blob/main/src/validator/matching/evidenceMatcher.ts"
click node_browser_semantic "https://github.com/tukanzee/avt-testing/blob/main/src/validator/browserSemantic.ts"
click node_claim_review "https://github.com/tukanzee/avt-testing/blob/main/src/validator/components/ClaimReview.tsx"
click node_omission_review "https://github.com/tukanzee/avt-testing/blob/main/src/validator/components/OmissionReview.tsx"
click node_findings_review "https://github.com/tukanzee/avt-testing/blob/main/src/validator/components/FindingsReview.tsx"
click node_level1_engine "https://github.com/tukanzee/avt-testing/blob/main/src/validator/level1Engine.ts"

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_app,node_cases,node_case_data,node_reviewer toneBlue
class node_session,node_json_export,node_pdf_export toneAmber
class node_validator_page,node_transcript_workflow,node_transcript_parse,node_audio_prep,node_speaker_attribution,node_local_transcription,node_evidence_chunks,node_claim_extraction,node_evidence_matching,node_browser_semantic,node_claim_review,node_omission_review,node_findings_review toneMint
class node_level1_engine toneRose
class node_user toneIndigo
```

## Components

### Role-play scenarios

- [Application routing](https://github.com/tukanzee/avt-testing/blob/main/src/App.tsx): `src/App.tsx`
- [Case catalogue](https://github.com/tukanzee/avt-testing/blob/main/src/data/cases.ts): `src/data/cases.ts`
- [Clinical case scripts](https://github.com/tukanzee/avt-testing/blob/main/src/data/cases/dka.ts): `src/data/cases/dka.ts`

### Ground-truth recording

- [Spoken fact capture](https://github.com/tukanzee/avt-testing/blob/main/src/App.tsx): `src/App.tsx`
- [JSON export](https://github.com/tukanzee/avt-testing/blob/main/src/utils/json.ts): `src/utils/json.ts`
- [PDF export](https://github.com/tukanzee/avt-testing/blob/main/src/utils/pdf.ts): `src/utils/pdf.ts`

### Transcript-led validation

- [Validator entry](https://github.com/tukanzee/avt-testing/blob/main/src/validator/ValidatorPage.tsx): `src/validator/ValidatorPage.tsx`
- [Transcript AVT workflow](https://github.com/tukanzee/avt-testing/blob/main/src/validator/TranscriptAvtValidator.tsx): `src/validator/TranscriptAvtValidator.tsx`
- [Transcript parsing](https://github.com/tukanzee/avt-testing/blob/main/src/validator/transcript/parseTranscript.ts): `src/validator/transcript/parseTranscript.ts`
- [Audio preparation](https://github.com/tukanzee/avt-testing/blob/main/src/validator/components/AudioTranscriptPreparation.tsx): `src/validator/components/AudioTranscriptPreparation.tsx`
- [Speaker attribution](https://github.com/tukanzee/avt-testing/blob/main/src/validator/speakerAttribution/localAttribution.ts): `src/validator/speakerAttribution/localAttribution.ts`
- [Local transcription](https://github.com/tukanzee/avt-testing/blob/main/src/validator/transcription/localWhisper.ts): `src/validator/transcription/localWhisper.ts`
- [Evidence chunking](https://github.com/tukanzee/avt-testing/blob/main/src/validator/transcript/createEvidenceChunks.ts): `src/validator/transcript/createEvidenceChunks.ts`
- [Atomic claim extraction](https://github.com/tukanzee/avt-testing/blob/main/src/validator/claimExtraction/atomic.ts): `src/validator/claimExtraction/atomic.ts`
- [Evidence matching](https://github.com/tukanzee/avt-testing/blob/main/src/validator/matching/evidenceMatcher.ts): `src/validator/matching/evidenceMatcher.ts`
- [Local semantic models](https://github.com/tukanzee/avt-testing/blob/main/src/validator/browserSemantic.ts): `src/validator/browserSemantic.ts`
- [Claim review](https://github.com/tukanzee/avt-testing/blob/main/src/validator/components/ClaimReview.tsx): `src/validator/components/ClaimReview.tsx`
- [Omission review](https://github.com/tukanzee/avt-testing/blob/main/src/validator/components/OmissionReview.tsx): `src/validator/components/OmissionReview.tsx`
- [Findings review](https://github.com/tukanzee/avt-testing/blob/main/src/validator/components/FindingsReview.tsx): `src/validator/components/FindingsReview.tsx`

### Level 1 validation

- [Level 1 analysis](https://github.com/tukanzee/avt-testing/blob/main/src/validator/level1Engine.ts): `src/validator/level1Engine.ts`

### Other components

- **Doctor / actor**
- **Human reviewer**

## Connections

- Doctor / actor → Application routing: uses
- Application routing → Case catalogue: loads cases (evidence: `src/App.tsx`)
- Case catalogue → Clinical case scripts: catalogues (evidence: `src/data/cases.ts`)
- Application routing → Spoken fact capture: records spoken facts (evidence: `src/App.tsx`)
- Spoken fact capture → JSON export: exports JSON (evidence: `src/App.tsx`)
- Spoken fact capture → PDF export: exports PDF (evidence: `src/App.tsx`)
- Application routing → Validator entry: opens validator (evidence: `src/App.tsx`)
- Validator entry → Transcript AVT workflow: offers workflow
- Transcript AVT workflow → Transcript parsing: parses transcript
- Transcript AVT workflow → Audio preparation: prepares audio
- Audio preparation → Local transcription: transcribes locally
- Speaker attribution → Local transcription: uses transcription (evidence: `src/validator/speakerAttribution/localAttribution.ts`)
- Transcript AVT workflow → Speaker attribution: attributes speakers
- Transcript AVT workflow → Evidence chunking: builds evidence (evidence: `src/validator/transcript/createEvidenceChunks.ts`)
- Evidence chunking → Atomic claim extraction: extracts atomic claims (evidence: `src/validator/transcript/createEvidenceChunks.ts`)
- Transcript AVT workflow → Evidence matching: retrieves evidence
- Evidence matching → Local semantic models: checks entailment
- Transcript AVT workflow → Claim review: presents claims
- Claim review → Evidence chunking: shows context (evidence: `src/validator/components/ClaimReview.tsx`)
- Claim review → Omission review: reviews omissions (evidence: `src/validator/components/OmissionReview.tsx`)
- Transcript AVT workflow → Findings review: reviews findings
- Human reviewer → Claim review: reviews evidence
- Human reviewer → Omission review: confirms omissions
- Human reviewer → Findings review: reviews findings
- Validator entry → Level 1 analysis: runs Level 1
- Level 1 analysis → Local semantic models: judges statements (evidence: `src/validator/level1Engine.ts`)
