# nareshparab/ai-assistant-healthcare architecture

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

- Interactive diagram: https://gitdiagram.com/nareshparab/ai-assistant-healthcare
- Repository: https://github.com/nareshparab/ai-assistant-healthcare

## Overview

This repository combines a healthcare document-processing backend with a Fire TV client and a separately scoped P4 rendering POC. The backend workflow extracts PDF text spans, structures them as AI proposals, applies a deterministic evidence gate, and persists extraction state; the sampled API also exposes evidence and device-pairing routes. The Fire TV tree shows a focus-validation screen, navigation, and local activity storage. Edges reflect explicit excerpts or SOURCE INDEX references; several client-to-backend and app-entry links are not shown, so they are omitted.

Main entry points: [`backend/extraction/orchestrator.py`](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/extraction/orchestrator.py) (Extraction job), [`backend/api/main.py`](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/api/main.py) (HTTP routes), [`backend/api/deps.py`](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/api/deps.py) (API dependencies), [`backend/ai/assist/document_structuring.py`](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/ai/assist/document_structuring.py) (AI structuring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Backend API"]
  node_api_main["HTTP routes<br/>[main.py]"]
  node_api_errors["Error envelope<br/>[errors.py]"]
  node_api_deps["API dependencies<br/>[deps.py]"]
end

subgraph group_extract["Document Extraction"]
  node_evidence["PDF evidence<br/>[pdf_evidence.py]"]
  node_synthetic["Synthetic documents<br/>[synthetic_data.py]"]
  node_spans["PDF text spans<br/>[spans.py]"]
  node_orchestrator["Extraction job<br/>[orchestrator.py]"]
  node_structuring["AI structuring"]
  node_schema["Proposal schema"]
  node_llm_client["LLM client<br/>[base.py]"]
  node_anthropic["Anthropic provider"]
  node_gate["Evidence gate<br/>[extraction_gate.py]"]
  node_routine_validator["Routine validator"]
end

subgraph group_storage["Backend Persistence"]
  node_device_store["Device pairing<br/>[devices.py]"]
  node_db[("SQLite database<br/>[db.py]")]
  node_documents_store["Document storage<br/>[documents.py]"]
  node_document_state["Document state<br/>[document_state.py]"]
  node_extraction_store["Extraction records<br/>[extraction.py]"]
end

subgraph group_tv["Fire TV Client"]
  node_main_activity["Activity entry<br/>[MainActivity.kt]"]
  node_focus_screen["Focus validation"]
  node_app_shell["App navigation<br/>[AppShell.kt]"]
  node_nav_state["Navigation state<br/>[NavigationState.kt]"]
  node_destination["Destinations<br/>[Destination.kt]"]
  node_shell_screens["Shell screens<br/>[ShellScreens.kt]"]
  node_activity_dao["Activity DAO"]
  node_activity_entity["Activity record"]
  node_app_database[("Local database<br/>[AppDatabase.kt]")]
  node_theme["UI theme<br/>[Theme.kt]"]
  node_safe_zone["Safe zone<br/>[SafeZone.kt]"]
end

subgraph group_poc["Transfer POC"]
  node_poc_main["POC HTTP routes<br/>[main.py]"]
  node_poc_extract["POC span extraction<br/>[extract.py]"]
  node_poc_render["POC highlighting<br/>[render.py]"]
end

node_tv_user(("TV user"))

node_api_main -->|"uses dependencies"| node_api_deps
node_api_main -->|"registers errors"| node_api_errors
node_api_main -->|"creates pairing code"| node_device_store
node_api_main -->|"builds evidence image"| node_evidence
node_api_main -->|"loads demo data"| node_synthetic
node_api_deps -->|"uses device storage"| node_device_store
node_api_deps -->|"opens connection"| node_db
node_orchestrator -->|"extracts spans"| node_spans
node_orchestrator -->|"builds model input"| node_structuring
node_orchestrator -->|"calls structured model"| node_llm_client
node_orchestrator -->|"applies gate"| node_gate
node_orchestrator -->|"persists extraction"| node_extraction_store
node_orchestrator -->|"updates state"| node_document_state
node_orchestrator -->|"opens connection"| node_db
node_structuring -->|"uses schema"| node_schema
node_structuring -->|"serializes spans"| node_spans
node_gate -->|"revalidates output"| node_schema
node_gate -->|"checks cited evidence"| node_spans
node_llm_client -.-> node_anthropic
node_app_shell -->|"uses navigation state"| node_nav_state
node_app_shell -->|"uses destinations"| node_destination
node_nav_state -->|"uses destinations"| node_destination
node_app_database -->|"provides DAO"| node_activity_dao
node_app_database -->|"stores entity"| node_activity_entity
node_activity_dao -->|"queries records"| node_activity_entity
node_theme -->|"uses safe zone"| node_safe_zone
node_tv_user -.->|"uses screen"| node_focus_screen
node_poc_main -->|"extracts matching span"| node_poc_extract
node_poc_main -->|"renders highlight"| node_poc_render

click node_api_main "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/api/main.py"
click node_api_errors "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/api/errors.py"
click node_api_deps "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/api/deps.py"
click node_device_store "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/storage/devices.py"
click node_evidence "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/documents/pdf_evidence.py"
click node_synthetic "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/documents/synthetic_data.py"
click node_spans "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/documents/spans.py"
click node_orchestrator "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/extraction/orchestrator.py"
click node_structuring "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/ai/assist/document_structuring.py"
click node_schema "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/ai/schemas/document_structuring.py"
click node_llm_client "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/ai/client/base.py"
click node_anthropic "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/ai/client/anthropic_client.py"
click node_gate "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/guardrail/extraction_gate.py"
click node_routine_validator "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/guardrail/routine_validator.py"
click node_db "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/storage/db.py"
click node_documents_store "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/storage/documents.py"
click node_document_state "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/storage/document_state.py"
click node_extraction_store "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/storage/extraction.py"
click node_main_activity "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/MainActivity.kt"
click node_focus_screen "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/P2FocusValidationScreen.kt"
click node_app_shell "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/nav/AppShell.kt"
click node_nav_state "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/nav/NavigationState.kt"
click node_destination "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/nav/Destination.kt"
click node_shell_screens "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/ui/ShellScreens.kt"
click node_activity_dao "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/data/local/ActivityRecordDao.kt"
click node_activity_entity "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/data/local/ActivityRecordEntity.kt"
click node_app_database "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/data/local/AppDatabase.kt"
click node_theme "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/design/Theme.kt"
click node_safe_zone "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/design/SafeZone.kt"
click node_poc_main "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/p4-transfer-package/p4-transfer-package/backend/app/main.py"
click node_poc_extract "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/p4-transfer-package/p4-transfer-package/backend/app/documents/extract.py"
click node_poc_render "https://github.com/nareshparab/ai-assistant-healthcare/blob/main/p4-transfer-package/p4-transfer-package/backend/app/documents/render.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_api_main,node_api_errors,node_api_deps,node_tv_user toneBlue
class node_evidence,node_synthetic,node_spans,node_orchestrator,node_structuring,node_schema,node_llm_client,node_anthropic,node_gate,node_routine_validator toneAmber
class node_device_store,node_db,node_documents_store,node_document_state,node_extraction_store toneMint
class node_main_activity,node_focus_screen,node_app_shell,node_nav_state,node_destination,node_shell_screens,node_activity_dao,node_activity_entity,node_app_database,node_theme,node_safe_zone toneRose
class node_poc_main,node_poc_extract,node_poc_render toneIndigo
```

## Components

### Backend API

- [HTTP routes](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/api/main.py): `backend/api/main.py`
- [Error envelope](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/api/errors.py): `backend/api/errors.py`
- [API dependencies](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/api/deps.py): `backend/api/deps.py`

### Document Extraction

- [PDF evidence](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/documents/pdf_evidence.py): `backend/documents/pdf_evidence.py`
- [Synthetic documents](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/documents/synthetic_data.py): `backend/documents/synthetic_data.py`
- [PDF text spans](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/documents/spans.py): `backend/documents/spans.py`
- [Extraction job](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/extraction/orchestrator.py): `backend/extraction/orchestrator.py`
- [AI structuring](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/ai/assist/document_structuring.py): `backend/ai/assist/document_structuring.py`
- [Proposal schema](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/ai/schemas/document_structuring.py): `backend/ai/schemas/document_structuring.py`
- [LLM client](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/ai/client/base.py): `backend/ai/client/base.py`
- [Anthropic provider](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/ai/client/anthropic_client.py): `backend/ai/client/anthropic_client.py`
- [Evidence gate](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/guardrail/extraction_gate.py): `backend/guardrail/extraction_gate.py`
- [Routine validator](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/guardrail/routine_validator.py): `backend/guardrail/routine_validator.py`

### Backend Persistence

- [Device pairing](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/storage/devices.py): `backend/storage/devices.py`
- [SQLite database](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/storage/db.py): `backend/storage/db.py`
- [Document storage](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/storage/documents.py): `backend/storage/documents.py`
- [Document state](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/storage/document_state.py): `backend/storage/document_state.py`
- [Extraction records](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/backend/storage/extraction.py): `backend/storage/extraction.py`

### Fire TV Client

- [Activity entry](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/MainActivity.kt): `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/MainActivity.kt`
- [Focus validation](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/P2FocusValidationScreen.kt): `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/P2FocusValidationScreen.kt`
- [App navigation](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/nav/AppShell.kt): `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/nav/AppShell.kt`
- [Navigation state](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/nav/NavigationState.kt): `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/nav/NavigationState.kt`
- [Destinations](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/nav/Destination.kt): `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/nav/Destination.kt`
- [Shell screens](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/ui/ShellScreens.kt): `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/ui/ShellScreens.kt`
- [Activity DAO](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/data/local/ActivityRecordDao.kt): `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/data/local/ActivityRecordDao.kt`
- [Activity record](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/data/local/ActivityRecordEntity.kt): `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/data/local/ActivityRecordEntity.kt`
- [Local database](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/data/local/AppDatabase.kt): `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/data/local/AppDatabase.kt`
- [UI theme](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/design/Theme.kt): `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/design/Theme.kt`
- [Safe zone](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/firetv/app/src/main/java/com/aiassistanthealthcare/firetv/design/SafeZone.kt): `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/design/SafeZone.kt`

### Transfer POC

- [POC HTTP routes](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/p4-transfer-package/p4-transfer-package/backend/app/main.py): `p4-transfer-package/p4-transfer-package/backend/app/main.py`
- [POC span extraction](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/p4-transfer-package/p4-transfer-package/backend/app/documents/extract.py): `p4-transfer-package/p4-transfer-package/backend/app/documents/extract.py`
- [POC highlighting](https://github.com/nareshparab/ai-assistant-healthcare/blob/main/p4-transfer-package/p4-transfer-package/backend/app/documents/render.py): `p4-transfer-package/p4-transfer-package/backend/app/documents/render.py`

### Other components

- **TV user**

## Connections

- HTTP routes → API dependencies: uses dependencies (evidence: `backend/api/main.py`)
- HTTP routes → Error envelope: registers errors (evidence: `backend/api/main.py`)
- HTTP routes → Device pairing: creates pairing code (evidence: `backend/api/main.py`)
- HTTP routes → PDF evidence: builds evidence image (evidence: `backend/api/main.py`)
- HTTP routes → Synthetic documents: loads demo data (evidence: `backend/api/main.py`)
- API dependencies → Device pairing: uses device storage (evidence: `backend/api/deps.py`)
- API dependencies → SQLite database: opens connection (evidence: `backend/api/deps.py`)
- Extraction job → PDF text spans: extracts spans (evidence: `backend/extraction/orchestrator.py`)
- Extraction job → AI structuring: builds model input (evidence: `backend/extraction/orchestrator.py`)
- Extraction job → LLM client: calls structured model (evidence: `backend/extraction/orchestrator.py`)
- Extraction job → Evidence gate: applies gate (evidence: `backend/extraction/orchestrator.py`)
- Extraction job → Extraction records: persists extraction (evidence: `backend/extraction/orchestrator.py`)
- Extraction job → Document state: updates state (evidence: `backend/extraction/orchestrator.py`)
- Extraction job → SQLite database: opens connection (evidence: `backend/extraction/orchestrator.py`)
- AI structuring → Proposal schema: uses schema (evidence: `backend/ai/assist/document_structuring.py`)
- AI structuring → PDF text spans: serializes spans (evidence: `backend/ai/assist/document_structuring.py`)
- Evidence gate → Proposal schema: revalidates output (evidence: `backend/guardrail/extraction_gate.py`)
- Evidence gate → PDF text spans: checks cited evidence (evidence: `backend/guardrail/extraction_gate.py`)
- LLM client → Anthropic provider (evidence: `backend/ai/client/anthropic_client.py`)
- App navigation → Navigation state: uses navigation state (evidence: `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/nav/AppShell.kt`)
- App navigation → Destinations: uses destinations (evidence: `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/nav/AppShell.kt`)
- Navigation state → Destinations: uses destinations (evidence: `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/nav/NavigationState.kt`)
- Local database → Activity DAO: provides DAO (evidence: `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/data/local/AppDatabase.kt`)
- Local database → Activity record: stores entity (evidence: `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/data/local/AppDatabase.kt`)
- Activity DAO → Activity record: queries records (evidence: `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/data/local/ActivityRecordDao.kt`)
- UI theme → Safe zone: uses safe zone (evidence: `firetv/app/src/main/java/com/aiassistanthealthcare/firetv/design/Theme.kt`)
- TV user → Focus validation: uses screen
- POC HTTP routes → POC span extraction: extracts matching span (evidence: `p4-transfer-package/p4-transfer-package/backend/app/main.py`)
- POC HTTP routes → POC highlighting: renders highlight (evidence: `p4-transfer-package/p4-transfer-package/backend/app/main.py`)
