# rahinooopp/osteo_guard_ai_hackathon architecture

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

## Overview

OsteoGuard AI is a Streamlit clinical decision-support app for osteoarthritis. Its main workflows are asking guideline-grounded questions and submitting clinical reports for extraction, scope checking, structured summarisation, and red-flag screening. It also offers patient-record management, risk-factor display, exercise-search suggestions, and retrieval statistics. Retrieval combines local dense and keyword search, rank fusion, and reranking; generation uses a configured external language-model provider. The graph follows README-documented capabilities and shown source references; some UI call details and unsampled implementation links are documented rather than independently verified in excerpts.

Main entry points: [`app.py`](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/app.py) (Streamlit app), [`backend.py`](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/backend.py) (Hybrid retrieval), [`safety.py`](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/safety.py) (Red-flag screening), [`resources.py`](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/resources.py) (Exercise searches)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Clinical interface"]
  node_ui["Streamlit app<br/>[app.py]"]
  node_config["Runtime config<br/>[config.py]"]
end

subgraph group_evidence["Guideline evidence"]
  node_query["Question answering<br/>[backend.py]"]
  node_retrieval["Hybrid retrieval<br/>[backend.py]"]
  node_vector[("Chroma index")]
  node_guidelines["Guideline corpus"]
  node_generation["LLM generation<br/>[backend.py]"]
  node_statistics["Retrieval statistics<br/>[backend.py]"]
end

subgraph group_reports["Report workflow"]
  node_extraction["Report extraction<br/>[reports.py]"]
  node_scope["Document scope gate<br/>[scope.py]"]
  node_summary["Report summarisation<br/>[backend.py]"]
  node_safety["Red-flag screening<br/>[safety.py]"]
end

subgraph group_clinical["Clinical tools"]
  node_risk["OA risk profile<br/>[risk.py]"]
  node_exercise["Exercise searches<br/>[resources.py]"]
end

subgraph group_records["Local records"]
  node_record_ui["Patient records UI<br/>[app.py]"]
  node_record_store[("Assessment store<br/>[records.py]")]
end

node_clinician(("Clinician"))
node_llm["LLM provider"]
node_youtube["YouTube search"]

node_clinician -->|"uses"| node_ui
node_ui -->|"checks settings"| node_config
node_ui -->|"submits question"| node_query
node_query -->|"retrieves evidence"| node_retrieval
node_retrieval -->|"queries"| node_vector
node_retrieval -->|"searches passages"| node_guidelines
node_query -->|"prompts with evidence"| node_generation
node_generation -->|"requests completion"| node_llm
node_ui -->|"extracts report"| node_extraction
node_ui -->|"checks document"| node_scope
node_ui -->|"requests summary"| node_summary
node_summary -->|"generates summary"| node_generation
node_summary -->|"retrieves related evidence"| node_retrieval
node_ui -->|"screens report"| node_safety
node_safety -->|"requests screening"| node_generation
node_ui -->|"calculates profile"| node_risk
node_ui -->|"offers searches"| node_exercise
node_exercise -->|"builds search links"| node_youtube
node_ui -->|"shows statistics"| node_statistics
node_ui -->|"opens records"| node_record_ui
node_record_ui -->|"reads and writes"| node_record_store
node_retrieval -->|"returns ranked passages"| node_generation

click node_ui "https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/app.py"
click node_config "https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/config.py"
click node_query "https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/backend.py"
click node_retrieval "https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/backend.py"
click node_vector "https://github.com/rahinooopp/osteo_guard_ai_hackathon/tree/main/data/osteoarthritis_db"
click node_guidelines "https://github.com/rahinooopp/osteo_guard_ai_hackathon/tree/main/data/guidelines"
click node_generation "https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/backend.py"
click node_extraction "https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/reports.py"
click node_scope "https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/scope.py"
click node_summary "https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/backend.py"
click node_safety "https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/safety.py"
click node_risk "https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/risk.py"
click node_exercise "https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/resources.py"
click node_statistics "https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/backend.py"
click node_record_ui "https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/app.py"
click node_record_store "https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/records.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_ui,node_config toneBlue
class node_query,node_retrieval,node_vector,node_guidelines,node_generation,node_statistics toneAmber
class node_extraction,node_scope,node_summary,node_safety toneMint
class node_risk,node_exercise toneRose
class node_record_ui,node_record_store,node_clinician,node_llm,node_youtube toneIndigo
```

## Components

### Clinical interface

- [Streamlit app](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/app.py): `app.py`
- [Runtime config](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/config.py): `config.py`

### Guideline evidence

- [Question answering](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/backend.py): `backend.py`
- [Hybrid retrieval](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/backend.py): `backend.py`
- [Chroma index](https://github.com/rahinooopp/osteo_guard_ai_hackathon/tree/main/data/osteoarthritis_db): `data/osteoarthritis_db`
- [Guideline corpus](https://github.com/rahinooopp/osteo_guard_ai_hackathon/tree/main/data/guidelines): `data/guidelines`
- [LLM generation](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/backend.py): `backend.py`
- [Retrieval statistics](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/backend.py): `backend.py`

### Report workflow

- [Report extraction](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/reports.py): `reports.py`
- [Document scope gate](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/scope.py): `scope.py`
- [Report summarisation](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/backend.py): `backend.py`
- [Red-flag screening](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/safety.py): `safety.py`

### Clinical tools

- [OA risk profile](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/risk.py): `risk.py`
- [Exercise searches](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/resources.py): `resources.py`

### Local records

- [Patient records UI](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/app.py): `app.py`
- [Assessment store](https://github.com/rahinooopp/osteo_guard_ai_hackathon/blob/main/records.py): `records.py`

### Other components

- **Clinician**
- **LLM provider**
- **YouTube search**

## Connections

- Clinician → Streamlit app: uses (evidence: `README.md`)
- Streamlit app → Runtime config: checks settings (evidence: `app.py`)
- Streamlit app → Question answering: submits question (evidence: `README.md`)
- Question answering → Hybrid retrieval: retrieves evidence (evidence: `README.md`)
- Hybrid retrieval → Chroma index: queries (evidence: `README.md`)
- Hybrid retrieval → Guideline corpus: searches passages (evidence: `README.md`)
- Question answering → LLM generation: prompts with evidence (evidence: `README.md`)
- LLM generation → LLM provider: requests completion (evidence: `README.md`)
- Streamlit app → Report extraction: extracts report (evidence: `README.md`)
- Streamlit app → Document scope gate: checks document (evidence: `README.md`)
- Streamlit app → Report summarisation: requests summary (evidence: `README.md`)
- Report summarisation → LLM generation: generates summary (evidence: `backend.py`)
- Report summarisation → Hybrid retrieval: retrieves related evidence (evidence: `README.md`)
- Streamlit app → Red-flag screening: screens report (evidence: `README.md`)
- Red-flag screening → LLM generation: requests screening (evidence: `safety.py`)
- Streamlit app → OA risk profile: calculates profile (evidence: `app.py`)
- Streamlit app → Exercise searches: offers searches (evidence: `app.py`)
- Exercise searches → YouTube search: builds search links (evidence: `resources.py`)
- Streamlit app → Retrieval statistics: shows statistics (evidence: `README.md`)
- Streamlit app → Patient records UI: opens records (evidence: `README.md`)
- Patient records UI → Assessment store: reads and writes (evidence: `app.py`)
- Hybrid retrieval → LLM generation: returns ranked passages (evidence: `backend.py`)
