# athish2211/ptaiv3 architecture

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

- Interactive diagram: https://gitdiagram.com/athish2211/ptaiv3
- Repository: https://github.com/athish2211/ptaiv3

## Overview

PTAI is an AI-native electronic health record and clinical analytics platform. Its documented workflows cover clinical records and prescription safety, uploaded prescription processing, dataset profiling and analytics, and clinician queries handled by a multi-agent AI layer. The sampled backend shows API routing, query orchestration, safety checks, local-model calls, and analytics-agent dispatch; the README documents additional product capabilities. Frontend-to-backend request wiring and several unsampled subsystems are not shown, so those connections are omitted.

Main entry points: [`backend/app/main.py`](https://github.com/athish2211/ptaiv3/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/ai/llm/client.py`](https://github.com/athish2211/ptaiv3/blob/main/backend/app/ai/llm/client.py) (Local model client), [`backend/app/services/prescription_upload_service.py`](https://github.com/athish2211/ptaiv3/blob/main/backend/app/services/prescription_upload_service.py) (Prescription ingestion), [`backend/app/core/database.py`](https://github.com/athish2211/ptaiv3/blob/main/backend/app/core/database.py) (Database setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Clinician experience"]
  node_ehr_ui["EHR screens<br/>[page.tsx]"]
  node_prescription_ui["Prescription builder<br/>[page.tsx]"]
  node_analytics_ui["Analytics screens<br/>[page.tsx]"]
  node_reports_ui["Reports hub<br/>[page.tsx]"]
end

subgraph group_clinical["Clinical services"]
  node_clinical_api["Clinical API routes"]
  node_document_api["Document endpoint<br/>[documents.py]"]
  node_prescription_upload["Prescription ingestion"]
  node_documentation["Documentation assistant"]
  node_clinical_models["Clinical data models"]
end

subgraph group_intelligence["AI and analytics"]
  node_ai_api["AI query endpoint<br/>[ai_query.py]"]
  node_analytics_api["Analytics endpoint<br/>[analytics.py]"]
  node_dataset_api["Dataset endpoints<br/>[datasets.py]"]
  node_dataset_ingest["Dataset profiling"]
  node_analytics_service["Analytics service"]
  node_pipeline["Analysis pipeline<br/>[core_pipeline.py]"]
  node_profiling["Data profiling<br/>[data_profiling.py]"]
  node_clinical_agents["Clinical analysis agents"]
  node_orchestrator["AI orchestrator<br/>[orchestrator.py]"]
  node_safety["Safety guardrail<br/>[safety_agent.py]"]
  node_rag["Document retrieval"]
  node_llm["Local model client<br/>[client.py]"]
end

subgraph group_platform["Platform foundation"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_database[("PostgreSQL / pgvector")]
  node_database_setup["Database setup<br/>[database.py]"]
  node_user_model["User and tokens<br/>[user.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_clinician(("Clinician"))
node_ollama(("Ollama"))

node_api_app -->|"routes requests"| node_clinical_api
node_api_app -->|"routes requests"| node_ai_api
node_api_app -->|"routes requests"| node_analytics_api
node_api_app -->|"routes requests"| node_dataset_api
node_api_app -->|"routes requests"| node_document_api
node_ai_api -->|"routes query"| node_orchestrator
node_orchestrator -->|"checks safety"| node_safety
node_orchestrator -->|"generates response"| node_llm
node_llm -->|"sends prompts"| node_ollama
node_analytics_api -->|"calls analytics"| node_analytics_service
node_analytics_api -->|"runs analysis"| node_clinical_agents
node_dataset_api -->|"calls service"| node_dataset_ingest
node_dataset_ingest -->|"stores dataset"| node_clinical_models
node_document_api -->|"uses assistant"| node_documentation
node_prescription_upload -->|"creates chunks"| node_rag
node_prescription_upload -->|"creates records"| node_clinical_models
node_prescription_upload -->|"embeds text"| node_llm
node_pipeline -->|"uses profiling"| node_profiling
node_pipeline -->|"dispatches analysis"| node_clinical_agents
node_database_setup -->|"reads settings"| node_config
node_database_setup -->|"initializes schema"| node_clinical_models
node_database_setup -->|"creates tables"| node_database
node_llm -->|"reads model settings"| node_config
node_clinician -.->|"uses"| node_ehr_ui
node_clinician -.->|"uses"| node_prescription_ui
node_clinician -.->|"uses"| node_analytics_ui
node_clinician -.->|"uses"| node_reports_ui

click node_ehr_ui "https://github.com/athish2211/ptaiv3/blob/main/frontend/src/app/(app)/patients/page.tsx"
click node_prescription_ui "https://github.com/athish2211/ptaiv3/blob/main/frontend/src/app/(app)/prescriptions/new/page.tsx"
click node_analytics_ui "https://github.com/athish2211/ptaiv3/blob/main/frontend/src/app/(app)/analytics/page.tsx"
click node_reports_ui "https://github.com/athish2211/ptaiv3/blob/main/frontend/src/app/(app)/reports/page.tsx"
click node_api_app "https://github.com/athish2211/ptaiv3/blob/main/backend/app/main.py"
click node_clinical_api "https://github.com/athish2211/ptaiv3/tree/main/backend/app/api"
click node_ai_api "https://github.com/athish2211/ptaiv3/blob/main/backend/app/api/ai_query.py"
click node_analytics_api "https://github.com/athish2211/ptaiv3/blob/main/backend/app/api/analytics.py"
click node_dataset_api "https://github.com/athish2211/ptaiv3/blob/main/backend/app/api/datasets.py"
click node_document_api "https://github.com/athish2211/ptaiv3/blob/main/backend/app/api/documents.py"
click node_prescription_upload "https://github.com/athish2211/ptaiv3/blob/main/backend/app/services/prescription_upload_service.py"
click node_dataset_ingest "https://github.com/athish2211/ptaiv3/blob/main/backend/app/services/dataset_upload_service.py"
click node_analytics_service "https://github.com/athish2211/ptaiv3/blob/main/backend/app/services/analytics_service.py"
click node_pipeline "https://github.com/athish2211/ptaiv3/blob/main/backend/app/utils/core_pipeline.py"
click node_profiling "https://github.com/athish2211/ptaiv3/blob/main/backend/app/utils/data_profiling.py"
click node_clinical_agents "https://github.com/athish2211/ptaiv3/tree/main/backend/app/agents"
click node_orchestrator "https://github.com/athish2211/ptaiv3/blob/main/backend/app/ai/supervisor/orchestrator.py"
click node_safety "https://github.com/athish2211/ptaiv3/blob/main/backend/app/ai/agents/safety_agent.py"
click node_documentation "https://github.com/athish2211/ptaiv3/blob/main/backend/app/ai/agents/documentation_agent.py"
click node_rag "https://github.com/athish2211/ptaiv3/tree/main/backend/app/ai/rag"
click node_llm "https://github.com/athish2211/ptaiv3/blob/main/backend/app/ai/llm/client.py"
click node_database_setup "https://github.com/athish2211/ptaiv3/blob/main/backend/app/core/database.py"
click node_clinical_models "https://github.com/athish2211/ptaiv3/tree/main/backend/app/models"
click node_user_model "https://github.com/athish2211/ptaiv3/blob/main/backend/app/models/user.py"
click node_config "https://github.com/athish2211/ptaiv3/blob/main/backend/app/core/config.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_ehr_ui,node_prescription_ui,node_analytics_ui,node_reports_ui toneBlue
class node_clinical_api,node_document_api,node_prescription_upload,node_documentation,node_clinical_models toneAmber
class node_ai_api,node_analytics_api,node_dataset_api,node_dataset_ingest,node_analytics_service,node_pipeline,node_profiling,node_clinical_agents,node_orchestrator,node_safety,node_rag,node_llm toneMint
class node_api_app,node_database,node_database_setup,node_user_model,node_config toneRose
class node_clinician,node_ollama toneIndigo
```

## Components

### Clinician experience

- [EHR screens](https://github.com/athish2211/ptaiv3/blob/main/frontend/src/app/(app)/patients/page.tsx): `frontend/src/app/(app)/patients/page.tsx`
- [Prescription builder](https://github.com/athish2211/ptaiv3/blob/main/frontend/src/app/(app)/prescriptions/new/page.tsx): `frontend/src/app/(app)/prescriptions/new/page.tsx`
- [Analytics screens](https://github.com/athish2211/ptaiv3/blob/main/frontend/src/app/(app)/analytics/page.tsx): `frontend/src/app/(app)/analytics/page.tsx`
- [Reports hub](https://github.com/athish2211/ptaiv3/blob/main/frontend/src/app/(app)/reports/page.tsx): `frontend/src/app/(app)/reports/page.tsx`

### Clinical services

- [Clinical API routes](https://github.com/athish2211/ptaiv3/tree/main/backend/app/api): `backend/app/api`
- [Document endpoint](https://github.com/athish2211/ptaiv3/blob/main/backend/app/api/documents.py): `backend/app/api/documents.py`
- [Prescription ingestion](https://github.com/athish2211/ptaiv3/blob/main/backend/app/services/prescription_upload_service.py): `backend/app/services/prescription_upload_service.py`
- [Documentation assistant](https://github.com/athish2211/ptaiv3/blob/main/backend/app/ai/agents/documentation_agent.py): `backend/app/ai/agents/documentation_agent.py`
- [Clinical data models](https://github.com/athish2211/ptaiv3/tree/main/backend/app/models): `backend/app/models`

### AI and analytics

- [AI query endpoint](https://github.com/athish2211/ptaiv3/blob/main/backend/app/api/ai_query.py): `backend/app/api/ai_query.py`
- [Analytics endpoint](https://github.com/athish2211/ptaiv3/blob/main/backend/app/api/analytics.py): `backend/app/api/analytics.py`
- [Dataset endpoints](https://github.com/athish2211/ptaiv3/blob/main/backend/app/api/datasets.py): `backend/app/api/datasets.py`
- [Dataset profiling](https://github.com/athish2211/ptaiv3/blob/main/backend/app/services/dataset_upload_service.py): `backend/app/services/dataset_upload_service.py`
- [Analytics service](https://github.com/athish2211/ptaiv3/blob/main/backend/app/services/analytics_service.py): `backend/app/services/analytics_service.py`
- [Analysis pipeline](https://github.com/athish2211/ptaiv3/blob/main/backend/app/utils/core_pipeline.py): `backend/app/utils/core_pipeline.py`
- [Data profiling](https://github.com/athish2211/ptaiv3/blob/main/backend/app/utils/data_profiling.py): `backend/app/utils/data_profiling.py`
- [Clinical analysis agents](https://github.com/athish2211/ptaiv3/tree/main/backend/app/agents): `backend/app/agents`
- [AI orchestrator](https://github.com/athish2211/ptaiv3/blob/main/backend/app/ai/supervisor/orchestrator.py): `backend/app/ai/supervisor/orchestrator.py`
- [Safety guardrail](https://github.com/athish2211/ptaiv3/blob/main/backend/app/ai/agents/safety_agent.py): `backend/app/ai/agents/safety_agent.py`
- [Document retrieval](https://github.com/athish2211/ptaiv3/tree/main/backend/app/ai/rag): `backend/app/ai/rag`
- [Local model client](https://github.com/athish2211/ptaiv3/blob/main/backend/app/ai/llm/client.py): `backend/app/ai/llm/client.py`

### Platform foundation

- [FastAPI application](https://github.com/athish2211/ptaiv3/blob/main/backend/app/main.py): `backend/app/main.py`
- **PostgreSQL / pgvector**
- [Database setup](https://github.com/athish2211/ptaiv3/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [User and tokens](https://github.com/athish2211/ptaiv3/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Runtime configuration](https://github.com/athish2211/ptaiv3/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### Other components

- **Clinician**
- **Ollama**

## Connections

- FastAPI application → Clinical API routes: routes requests (evidence: `backend/app/main.py`)
- FastAPI application → AI query endpoint: routes requests (evidence: `backend/app/main.py`)
- FastAPI application → Analytics endpoint: routes requests (evidence: `backend/app/main.py`)
- FastAPI application → Dataset endpoints: routes requests (evidence: `backend/app/main.py`)
- FastAPI application → Document endpoint: routes requests (evidence: `backend/app/main.py`)
- AI query endpoint → AI orchestrator: routes query (evidence: `backend/app/api/ai_query.py`)
- AI orchestrator → Safety guardrail: checks safety (evidence: `backend/app/ai/supervisor/orchestrator.py`)
- AI orchestrator → Local model client: generates response (evidence: `backend/app/ai/supervisor/orchestrator.py`)
- Local model client → Ollama: sends prompts (evidence: `backend/app/ai/llm/client.py`)
- Analytics endpoint → Analytics service: calls analytics (evidence: `backend/app/api/analytics.py`)
- Analytics endpoint → Clinical analysis agents: runs analysis (evidence: `backend/app/api/analytics.py`)
- Dataset endpoints → Dataset profiling: calls service (evidence: `backend/app/api/datasets.py`)
- Dataset profiling → Clinical data models: stores dataset (evidence: `backend/app/services/dataset_upload_service.py`)
- Document endpoint → Documentation assistant: uses assistant (evidence: `backend/app/api/documents.py`)
- Prescription ingestion → Document retrieval: creates chunks (evidence: `backend/app/services/prescription_upload_service.py`)
- Prescription ingestion → Clinical data models: creates records (evidence: `backend/app/services/prescription_upload_service.py`)
- Prescription ingestion → Local model client: embeds text (evidence: `backend/app/services/prescription_upload_service.py`)
- Analysis pipeline → Data profiling: uses profiling (evidence: `backend/app/utils/core_pipeline.py`)
- Analysis pipeline → Clinical analysis agents: dispatches analysis (evidence: `backend/app/utils/core_pipeline.py`)
- Database setup → Runtime configuration: reads settings (evidence: `backend/app/core/database.py`)
- Database setup → Clinical data models: initializes schema (evidence: `backend/app/core/database.py`)
- Database setup → PostgreSQL / pgvector: creates tables (evidence: `backend/app/core/database.py`)
- Local model client → Runtime configuration: reads model settings (evidence: `backend/app/ai/llm/client.py`)
- Clinician → EHR screens: uses
- Clinician → Prescription builder: uses
- Clinician → Analytics screens: uses
- Clinician → Reports hub: uses
