# sk6594246/h_buddy architecture

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

- Interactive diagram: https://gitdiagram.com/sk6594246/h_buddy
- Repository: https://github.com/sk6594246/h_buddy

## Overview

Health Buddy is a family health-claim fact-checker with two interfaces: a PWA backed by FastAPI and a Gradio app. A claim is optionally extracted from an uploaded PDF or image, matched against a curated medical corpus, and sent with retrieved evidence to a language model for a verdict and cited explanation. The PWA also keeps local claim history and supports offline asset caching. The README documents a hosted Gradio endpoint and a Pages PWA; the sampled frontend instead posts to `/check`, so deployment-specific wiring is not inferred.

Main entry points: [`backend/main.py`](https://github.com/sk6594246/h_buddy/blob/main/backend/main.py) (FastAPI endpoint), [`backend/rag.py`](https://github.com/sk6594246/h_buddy/blob/main/backend/rag.py) (Chunk and retrieve evidence), [`backend/llm.py`](https://github.com/sk6594246/h_buddy/blob/main/backend/llm.py) (Verdict and report), [`frontend/app.js`](https://github.com/sk6594246/h_buddy/blob/main/frontend/app.js) (Health Buddy PWA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_pwa["Health Buddy PWA<br/>[app.js]"]
  node_pwa_assets["Offline asset cache<br/>[sw.js]"]
  node_history[("Browser claim history")]
  node_gradio["Gradio interface<br/>[app.py]"]
end

subgraph group_claim_api["Claim processing"]
  node_fastapi["FastAPI endpoint<br/>[main.py]"]
  node_rate_limit["Daily claim limit<br/>[main.py]"]
  node_file_text["PDF and image extraction<br/>[main.py]"]
end

subgraph group_evidence["Evidence retrieval"]
  node_corpus["Medical text corpus"]
  node_rag["Chunk and retrieve evidence<br/>[rag.py]"]
  node_embed["Sentence embeddings<br/>[rag.py]"]
  node_faiss[("FAISS vector index<br/>[rag.py]")]
end

subgraph group_verdict["Verdict generation"]
  node_llm["Verdict and report<br/>[llm.py]"]
end

node_family(("Family member"))
node_groq{{"Groq chat API"}}

node_family -->|"submits claim"| node_pwa
node_pwa -->|"POSTs claim"| node_fastapi
node_pwa -->|"reads and writes"| node_history
node_pwa_assets -->|"serves cached assets"| node_family
node_family -->|"submits claim"| node_gradio
node_gradio -->|"retrieves evidence"| node_rag
node_gradio -->|"requests verdict"| node_llm
node_fastapi -->|"checks quota"| node_rate_limit
node_fastapi -->|"extracts upload text"| node_file_text
node_fastapi -->|"retrieves evidence"| node_rag
node_fastapi -->|"requests verdict"| node_llm
node_rag -->|"loads text"| node_corpus
node_rag -->|"encodes chunks and query"| node_embed
node_rag -->|"builds and searches"| node_faiss
node_llm -.->|"requests completion"| node_groq
node_groq -.->|"returns JSON"| node_llm

click node_pwa "https://github.com/sk6594246/h_buddy/blob/main/frontend/app.js"
click node_pwa_assets "https://github.com/sk6594246/h_buddy/blob/main/frontend/sw.js"
click node_gradio "https://github.com/sk6594246/h_buddy/blob/main/app.py"
click node_fastapi "https://github.com/sk6594246/h_buddy/blob/main/backend/main.py"
click node_rate_limit "https://github.com/sk6594246/h_buddy/blob/main/backend/main.py"
click node_file_text "https://github.com/sk6594246/h_buddy/blob/main/backend/main.py"
click node_corpus "https://github.com/sk6594246/h_buddy/tree/main/backend/corpus"
click node_rag "https://github.com/sk6594246/h_buddy/blob/main/backend/rag.py"
click node_embed "https://github.com/sk6594246/h_buddy/blob/main/backend/rag.py"
click node_faiss "https://github.com/sk6594246/h_buddy/blob/main/backend/rag.py"
click node_llm "https://github.com/sk6594246/h_buddy/blob/main/backend/llm.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_pwa,node_pwa_assets,node_history,node_gradio toneBlue
class node_fastapi,node_rate_limit,node_file_text toneAmber
class node_corpus,node_rag,node_embed,node_faiss,node_groq toneMint
class node_llm toneRose
class node_family toneIndigo
```

## Components

### User interfaces

- [Health Buddy PWA](https://github.com/sk6594246/h_buddy/blob/main/frontend/app.js): `frontend/app.js`
- [Offline asset cache](https://github.com/sk6594246/h_buddy/blob/main/frontend/sw.js): `frontend/sw.js`
- **Browser claim history**
- [Gradio interface](https://github.com/sk6594246/h_buddy/blob/main/app.py): `app.py`

### Claim processing

- [FastAPI endpoint](https://github.com/sk6594246/h_buddy/blob/main/backend/main.py): `backend/main.py`
- [Daily claim limit](https://github.com/sk6594246/h_buddy/blob/main/backend/main.py): `backend/main.py`
- [PDF and image extraction](https://github.com/sk6594246/h_buddy/blob/main/backend/main.py): `backend/main.py`

### Evidence retrieval

- [Medical text corpus](https://github.com/sk6594246/h_buddy/tree/main/backend/corpus): `backend/corpus`
- [Chunk and retrieve evidence](https://github.com/sk6594246/h_buddy/blob/main/backend/rag.py): `backend/rag.py`
- [Sentence embeddings](https://github.com/sk6594246/h_buddy/blob/main/backend/rag.py): `backend/rag.py`
- [FAISS vector index](https://github.com/sk6594246/h_buddy/blob/main/backend/rag.py): `backend/rag.py`

### Verdict generation

- [Verdict and report](https://github.com/sk6594246/h_buddy/blob/main/backend/llm.py): `backend/llm.py`

### Other components

- **Family member**
- **Groq chat API**

## Connections

- Family member → Health Buddy PWA: submits claim
- Health Buddy PWA → FastAPI endpoint: POSTs claim
- Health Buddy PWA → Browser claim history: reads and writes
- Offline asset cache → Family member: serves cached assets
- Family member → Gradio interface: submits claim
- Gradio interface → Chunk and retrieve evidence: retrieves evidence
- Gradio interface → Verdict and report: requests verdict
- FastAPI endpoint → Daily claim limit: checks quota
- FastAPI endpoint → PDF and image extraction: extracts upload text
- FastAPI endpoint → Chunk and retrieve evidence: retrieves evidence
- FastAPI endpoint → Verdict and report: requests verdict
- Chunk and retrieve evidence → Medical text corpus: loads text
- Chunk and retrieve evidence → Sentence embeddings: encodes chunks and query
- Chunk and retrieve evidence → FAISS vector index: builds and searches
- Verdict and report → Groq chat API: requests completion
- Groq chat API → Verdict and report: returns JSON