# starom00n/tharmya architecture

> Architecture diagram of the GitHub repository starom00n/tharmya, 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/starom00n/tharmya
- Repository: https://github.com/starom00n/tharmya

## Overview

TharmYa AI is a Thai OTC-medicine guidance assistant. A user enters symptoms through the elder-friendly web UI; safety checks can short-circuit emergencies or unsuitable requests, while passed requests combine patient details with relevant drug information before a configurable LLM streams a reply. The repository also documents a standalone validation and regression-reporting capability. The validation branch is included as a product capability; tests and delivery tooling are not. Some internal call details are unsampled, so those links rely on README workflow documentation.

Main entry points: [`app.py`](https://github.com/starom00n/tharmya/blob/main/app.py) (Chat handler), [`rag_engine.py`](https://github.com/starom00n/tharmya/blob/main/rag_engine.py) (RAG retrieval), [`validation.py`](https://github.com/starom00n/tharmya/blob/main/validation.py) (Validation runner), [`prompt_engine.py`](https://github.com/starom00n/tharmya/blob/main/prompt_engine.py) (Safety pre-check)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webui["Gradio UI<br/>[app.py]"]
  node_chatflow["Chat handler<br/>[app.py]"]
  node_reply["Streamed guidance<br/>[app.py]"]
end

subgraph group_guidance["Guidance workflow"]
  node_safety["Safety pre-check<br/>[prompt_engine.py]"]
  node_profile["Patient context<br/>[prompt_engine.py]"]
  node_prompt["Prompt assembly<br/>[prompt_engine.py]"]
  node_llm["LLM provider<br/>[app.py]"]
end

subgraph group_knowledge["Drug knowledge"]
  node_rag["RAG retrieval<br/>[rag_engine.py]"]
  node_tfidf["TF-IDF index<br/>[rag_engine.py]"]
  node_interactions["Interaction checker<br/>[rag_engine.py]"]
  node_drugdata[("OTC drug database")]
end

subgraph group_validation["Validation"]
  node_validator["Validation runner<br/>[validation.py]"]
  node_evaluation["Safety and accuracy evaluation<br/>[validation.py]"]
  node_reports["Regression reports<br/>[validation.py]"]
end

node_user(("Person"))
node_providers{{"AI services"}}

node_user -->|"enters symptoms"| node_webui
node_webui -->|"submits chat"| node_chatflow
node_chatflow -->|"checks request"| node_safety
node_chatflow -->|"builds context"| node_profile
node_chatflow -->|"retrieves drugs"| node_rag
node_rag -->|"searches index"| node_tfidf
node_tfidf -->|"indexes records"| node_drugdata
node_rag -->|"checks interactions"| node_interactions
node_rag -->|"loads records"| node_drugdata
node_chatflow -->|"builds prompt"| node_prompt
node_chatflow -->|"streams request"| node_llm
node_llm -->|"calls provider"| node_providers
node_llm -->|"yields tokens"| node_reply
node_reply -->|"renders reply"| node_webui
node_validator -->|"checks cases"| node_safety
node_validator -->|"retrieves context"| node_rag
node_validator -->|"evaluates replies"| node_evaluation
node_evaluation -->|"records regression"| node_reports

click node_webui "https://github.com/starom00n/tharmya/blob/main/app.py"
click node_chatflow "https://github.com/starom00n/tharmya/blob/main/app.py"
click node_safety "https://github.com/starom00n/tharmya/blob/main/prompt_engine.py"
click node_profile "https://github.com/starom00n/tharmya/blob/main/prompt_engine.py"
click node_rag "https://github.com/starom00n/tharmya/blob/main/rag_engine.py"
click node_tfidf "https://github.com/starom00n/tharmya/blob/main/rag_engine.py"
click node_interactions "https://github.com/starom00n/tharmya/blob/main/rag_engine.py"
click node_drugdata "https://github.com/starom00n/tharmya/blob/main/thai_otc_drugs.json"
click node_prompt "https://github.com/starom00n/tharmya/blob/main/prompt_engine.py"
click node_llm "https://github.com/starom00n/tharmya/blob/main/app.py"
click node_reply "https://github.com/starom00n/tharmya/blob/main/app.py"
click node_validator "https://github.com/starom00n/tharmya/blob/main/validation.py"
click node_evaluation "https://github.com/starom00n/tharmya/blob/main/validation.py"
click node_reports "https://github.com/starom00n/tharmya/blob/main/validation.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_webui,node_chatflow,node_reply toneBlue
class node_safety,node_profile,node_prompt,node_llm toneAmber
class node_rag,node_tfidf,node_interactions,node_drugdata toneMint
class node_validator,node_evaluation,node_reports toneRose
class node_user,node_providers toneIndigo
```

## Components

### Web experience

- [Gradio UI](https://github.com/starom00n/tharmya/blob/main/app.py): `app.py`
- [Chat handler](https://github.com/starom00n/tharmya/blob/main/app.py): `app.py`
- [Streamed guidance](https://github.com/starom00n/tharmya/blob/main/app.py): `app.py`

### Guidance workflow

- [Safety pre-check](https://github.com/starom00n/tharmya/blob/main/prompt_engine.py): `prompt_engine.py`
- [Patient context](https://github.com/starom00n/tharmya/blob/main/prompt_engine.py): `prompt_engine.py`
- [Prompt assembly](https://github.com/starom00n/tharmya/blob/main/prompt_engine.py): `prompt_engine.py`
- [LLM provider](https://github.com/starom00n/tharmya/blob/main/app.py): `app.py`

### Drug knowledge

- [RAG retrieval](https://github.com/starom00n/tharmya/blob/main/rag_engine.py): `rag_engine.py`
- [TF-IDF index](https://github.com/starom00n/tharmya/blob/main/rag_engine.py): `rag_engine.py`
- [Interaction checker](https://github.com/starom00n/tharmya/blob/main/rag_engine.py): `rag_engine.py`
- [OTC drug database](https://github.com/starom00n/tharmya/blob/main/thai_otc_drugs.json): `thai_otc_drugs.json`

### Validation

- [Validation runner](https://github.com/starom00n/tharmya/blob/main/validation.py): `validation.py`
- [Safety and accuracy evaluation](https://github.com/starom00n/tharmya/blob/main/validation.py): `validation.py`
- [Regression reports](https://github.com/starom00n/tharmya/blob/main/validation.py): `validation.py`

### Other components

- **Person**
- **AI services**

## Connections

- Person → Gradio UI: enters symptoms (evidence: `README.md`)
- Gradio UI → Chat handler: submits chat (evidence: `README.md`)
- Chat handler → Safety pre-check: checks request (evidence: `README.md`)
- Chat handler → Patient context: builds context (evidence: `README.md`)
- Chat handler → RAG retrieval: retrieves drugs (evidence: `app.py`)
- RAG retrieval → TF-IDF index: searches index (evidence: `rag_engine.py`)
- TF-IDF index → OTC drug database: indexes records (evidence: `rag_engine.py`)
- RAG retrieval → Interaction checker: checks interactions (evidence: `rag_engine.py`)
- RAG retrieval → OTC drug database: loads records (evidence: `rag_engine.py`)
- Chat handler → Prompt assembly: builds prompt (evidence: `README.md`)
- Chat handler → LLM provider: streams request (evidence: `README.md`)
- LLM provider → AI services: calls provider (evidence: `README.md`)
- LLM provider → Streamed guidance: yields tokens (evidence: `app.py`)
- Streamed guidance → Gradio UI: renders reply (evidence: `README.md`)
- Validation runner → Safety pre-check: checks cases (evidence: `validation.py`)
- Validation runner → RAG retrieval: retrieves context (evidence: `validation.py`)
- Validation runner → Safety and accuracy evaluation: evaluates replies (evidence: `README.md`)
- Safety and accuracy evaluation → Regression reports: records regression (evidence: `README.md`)
