# samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics architecture

> Architecture diagram of the GitHub repository samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics
- Repository: https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics

## Overview

#### Purpose and Runtime Topology
Health Diagnostics AI Agent ingests blood-work reports, extracts and normalizes laboratory values, produces risk-oriented interpretation, persists report history, and supports contextual user chat. It is deployed as independently scalable FastAPI and Streamlit services, with Render provisioning defined in `render.yaml` and service containers in `Dockerfile.backend` and `Dockerfile.frontend`.

#### Application Entry Points
The backend API is assembled and launched through `backend/main.py`; route modules expose health, report, analysis, and chat capabilities under `backend/routes/health.py`, `backend/routes/reports.py`, `backend/routes/analyze.py`, and `backend/routes/chat.py`. The Streamlit client begins at `frontend/app.py`, with page-level workflows in `frontend/pages/upload.py`, `frontend/pages/dashboard.py`, `frontend/pages/history.py`, and `frontend/pages/chat.py`.

#### Report Ingestion and Extraction
Upload/analysis requests enter the API route layer and are orchestrated by `backend/services/analysis_service.py`. Format-specific handling is split between OCR extraction in `backend/services/ocr_service.py` and structured-content parsing in `backend/services/parser_service.py`. This boundary supports PDFs/images as OCR inputs and JSON/CSV as structured inputs before a common blood-parameter model is produced.

#### Validation and Clinical Interpretation
Parsed measurements are validated by `backend/services/validator_service.py` and represented through models such as `backend/models/blood_parameter.py` and `backend/models/report.py`. Domain logic then normalizes units (`backend/domain/unit_converter.py`), compares values with maintained ranges (`backend/domain/reference_ranges.py`, `backend/data/reference_ranges.json`), calculates risk (`backend/domain/risk_calculator.py`), and creates report-level interpretation (`backend/domain/report_interpreter.py`).

#### AI Analysis and Conversation
The LLM boundary is centralized in `backend/services/llm_service.py`, preventing route and domain layers from directly depending on an AI provider. `backend/services/chat_service.py` uses that capability to answer questions grounded in report context; chat request/state schemas reside in `backend/models/chat.py`. Provider credentials are environment-driven through `backend/config.py` and `.env.example` (including the documented Groq integration).

#### Persistence and Historical Comparisons
Database access follows a repository boundary: `backend/db/client.py` owns Supabase connectivity and `backend/db/repository.py` encapsulates data operations. Report and health representations in `backend/models/report.py` and `backend/models/health.py` form the persistence-facing contract. This enables the history UI to retrieve prior reports and supports multi-report trend comparison without coupling frontend pages to Supabase.

#### Frontend-to-Backend Boundary
Streamlit pages call the FastAPI service through `frontend/api_client.py`, configured by `frontend/config.py`; session-scoped UI state is managed in `frontend/session.py`. The frontend does not implement diagnostic logic: upload submits source material, dashboard renders analysis, history presents persisted reports, and chat sends conversational requests. `API_BASE_URL` provides the deployment boundary between separately hosted services.

Main entry points: [`backend/routes/analyze.py`](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/routes/analyze.py) (Health, reports, analysis & chat routes), [`backend/db/repository.py`](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/db/repository.py) (Repository), [`frontend/pages/upload.py`](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/frontend/pages/upload.py) (Upload, dashboard, history & chat), [`backend/services/analysis_service.py`](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/services/analysis_service.py) (Analysis service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Streamlit frontend"]
  node_streamlit["Streamlit app<br/>UI entry point<br/>[app.py]"]
  node_pages["Upload, dashboard, history &amp; chat<br/>UI workflows<br/>[upload.py]"]
  node_api_client["API client<br/>HTTP boundary<br/>[api_client.py]"]
  node_session["Session state<br/>UI state<br/>[session.py]"]
end

subgraph group_api["FastAPI backend"]
  node_fastapi["FastAPI application<br/>API entry point<br/>[main.py]"]
  node_routes["Health, reports, analysis &amp; chat routes<br/>route layer<br/>[analyze.py]"]
  node_analysis["Analysis service<br/>ingestion orchestrator"]
  node_extractors["OCR and structured parsers<br/>format extraction<br/>[ocr_service.py]"]
  node_chat_service["Chat service<br/>conversation orchestration<br/>[chat_service.py]"]
  node_llm{{"LLM service<br/>AI provider boundary<br/>[llm_service.py]"}}
  node_models["Report, parameter, health &amp; chat models<br/>application contracts<br/>[report.py]"]
end

subgraph group_clinical["Clinical interpretation"]
  node_validator["Validator service<br/>measurement validation"]
  node_units["Unit converter<br/>normalization<br/>[unit_converter.py]"]
  node_ranges["Reference ranges<br/>clinical rules"]
  node_risk["Risk calculator<br/>risk assessment<br/>[risk_calculator.py]"]
  node_interpreter["Report interpreter<br/>report interpretation"]
end

subgraph group_data["Persistence"]
  node_repository["Repository<br/>data access boundary<br/>[repository.py]"]
  node_supabase[("Supabase<br/>database<br/>[client.py]")]
end

node_deployment["Render deployment<br/>service provisioning<br/>[render.yaml]"]

node_streamlit -->|"renders"| node_pages
node_pages -->|"uses"| node_session
node_pages -->|"submits and retrieves"| node_api_client
node_api_client -->|"HTTP via API_BASE_URL"| node_fastapi
node_fastapi -->|"mounts"| node_routes
node_routes -->|"upload and analysis"| node_analysis
node_routes -->|"chat requests"| node_chat_service
node_analysis -->|"extracts source content"| node_extractors
node_extractors -->|"produces parameters"| node_models
node_analysis -->|"validates measurements"| node_validator
node_validator -->|"normalizes units"| node_units
node_units -->|"compares normalized values"| node_ranges
node_ranges -->|"supplies thresholds"| node_risk
node_risk -->|"provides risk assessment"| node_interpreter
node_interpreter -->|"persists interpreted report"| node_repository
node_routes -->|"history retrieval"| node_repository
node_repository -->|"data operations"| node_supabase
node_chat_service -->|"loads report context"| node_repository
node_chat_service -->|"generates grounded response"| node_llm
node_deployment -.->|"provisions frontend service"| node_streamlit
node_deployment -.->|"provisions backend service"| node_fastapi

click node_streamlit "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/frontend/app.py"
click node_pages "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/frontend/pages/upload.py"
click node_api_client "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/frontend/api_client.py"
click node_session "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/frontend/session.py"
click node_fastapi "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/main.py"
click node_routes "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/routes/analyze.py"
click node_analysis "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/services/analysis_service.py"
click node_extractors "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/services/ocr_service.py"
click node_chat_service "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/services/chat_service.py"
click node_llm "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/services/llm_service.py"
click node_models "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/models/report.py"
click node_validator "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/services/validator_service.py"
click node_units "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/domain/unit_converter.py"
click node_ranges "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/domain/reference_ranges.py"
click node_risk "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/domain/risk_calculator.py"
click node_interpreter "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/domain/report_interpreter.py"
click node_repository "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/db/repository.py"
click node_supabase "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/db/client.py"
click node_deployment "https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/render.yaml"

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_streamlit,node_pages,node_api_client,node_session toneBlue
class node_fastapi,node_routes,node_analysis,node_extractors,node_chat_service,node_llm,node_models toneAmber
class node_validator,node_units,node_ranges,node_risk,node_interpreter toneMint
class node_repository,node_supabase toneRose
class node_deployment toneNeutral
```

## Components

### Streamlit frontend

Separate UI runtime.

- [Streamlit app](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/frontend/app.py): UI entry point · `frontend/app.py`
- [Upload, dashboard, history & chat](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/frontend/pages/upload.py): UI workflows · `frontend/pages/upload.py`
- [API client](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/frontend/api_client.py): HTTP boundary · Uses API_BASE_URL to reach the separately deployed backend. · `frontend/api_client.py`
- [Session state](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/frontend/session.py): UI state · `frontend/session.py`

### FastAPI backend

API and orchestration runtime.

- [FastAPI application](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/main.py): API entry point · `backend/main.py`
- [Health, reports, analysis & chat routes](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/routes/analyze.py): route layer · `backend/routes/analyze.py`
- [Analysis service](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/services/analysis_service.py): ingestion orchestrator · `backend/services/analysis_service.py`
- [OCR and structured parsers](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/services/ocr_service.py): format extraction · OCR handles PDFs/images; parser handles JSON/CSV. · `backend/services/ocr_service.py`
- [Chat service](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/services/chat_service.py): conversation orchestration · Grounds answers in report context. · `backend/services/chat_service.py`
- [LLM service](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/services/llm_service.py): AI provider boundary · Centralizes provider access and credentials. · `backend/services/llm_service.py`
- [Report, parameter, health & chat models](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/models/report.py): application contracts · `backend/models/report.py`

### Clinical interpretation

Validation and deterministic diagnostic logic.

- [Validator service](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/services/validator_service.py): measurement validation · `backend/services/validator_service.py`
- [Unit converter](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/domain/unit_converter.py): normalization · `backend/domain/unit_converter.py`
- [Reference ranges](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/domain/reference_ranges.py): clinical rules · Maintained ranges are backed by reference_ranges.json. · `backend/domain/reference_ranges.py`
- [Risk calculator](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/domain/risk_calculator.py): risk assessment · `backend/domain/risk_calculator.py`
- [Report interpreter](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/domain/report_interpreter.py): report interpretation · `backend/domain/report_interpreter.py`

### Persistence

Supabase repository boundary.

- [Repository](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/db/repository.py): data access boundary · Encapsulates report persistence and retrieval. · `backend/db/repository.py`
- [Supabase](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/backend/db/client.py): database · `backend/db/client.py`

### Other components

- [Render deployment](https://github.com/samuveljohnson1416/multi-model-ai-agent-for-automated-health-diagnostics/blob/main/render.yaml): service provisioning · Provisions independently scalable frontend and backend services. · `render.yaml`

## Connections

- Streamlit app → Upload, dashboard, history & chat: renders
- Upload, dashboard, history & chat → Session state: uses
- Upload, dashboard, history & chat → API client: submits and retrieves
- API client → FastAPI application: HTTP via API_BASE_URL
- FastAPI application → Health, reports, analysis & chat routes: mounts
- Health, reports, analysis & chat routes → Analysis service: upload and analysis
- Health, reports, analysis & chat routes → Chat service: chat requests
- Analysis service → OCR and structured parsers: extracts source content
- OCR and structured parsers → Report, parameter, health & chat models: produces parameters
- Analysis service → Validator service: validates measurements
- Validator service → Unit converter: normalizes units
- Unit converter → Reference ranges: compares normalized values
- Reference ranges → Risk calculator: supplies thresholds
- Risk calculator → Report interpreter: provides risk assessment
- Report interpreter → Repository: persists interpreted report
- Health, reports, analysis & chat routes → Repository: history retrieval
- Repository → Supabase: data operations
- Chat service → Repository: loads report context
- Chat service → LLM service: generates grounded response
- Render deployment → Streamlit app: provisions frontend service
- Render deployment → FastAPI application: provisions backend service