# aryavaidya08/lens architecture

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

- Interactive diagram: https://gitdiagram.com/aryavaidya08/lens
- Repository: https://github.com/aryavaidya08/lens

## Overview

HCP Spatial Copilot turns a medication scan into a personalized, patient-aware drug briefing and voice Q&A, with engagement recorded for later familiarity-based answers. The primary workflow runs from the iOS camera through drug identification and the shared API to backend personalization and dossier retrieval; clinicians can also use the React dashboard. Separate branches cover accounts, patient charts, medication reviews, and synced chat/history. Backend startup wiring and selected client calls are evidenced in source excerpts; other product flows and subsystem links are represented from README documentation, not unsampled implementation details.

Main entry points: [`backend/app/main.py`](https://github.com/aryavaidya08/lens/blob/main/backend/app/main.py) (FastAPI App), [`backend/app/routes/drug.py`](https://github.com/aryavaidya08/lens/blob/main/backend/app/routes/drug.py) (Drug Routes), [`backend/app/db/mongo.py`](https://github.com/aryavaidya08/lens/blob/main/backend/app/db/mongo.py) (MongoDB), [`frontend/src/App.jsx`](https://github.com/aryavaidya08/lens/blob/main/frontend/src/App.jsx) (Web Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ios["iOS Copilot"]
  node_ios_app["iOS App"]
  node_camera_detection["Camera Detection"]
  node_hud["AR HUD"]
  node_voice_session["Voice Assistant"]
  node_document_scan["Medication Scan"]
  node_ios_api["iOS API Client<br/>[APIClient.swift]"]
end

subgraph group_backend_api["Backend API"]
  node_api_app["FastAPI App<br/>[main.py]"]
  node_auth_routes["Account Routes<br/>[auth.py]"]
  node_profile_routes["Profile Routes<br/>[profile.py]"]
  node_detect_routes["Detection Route<br/>[detect.py]"]
  node_drug_routes["Drug Routes<br/>[drug.py]"]
  node_engagement_routes["Engagement Route<br/>[engagement.py]"]
  node_review_routes["Review Routes"]
end

subgraph group_drug_intelligence["Drug Intelligence"]
  node_drug_catalog[("Drug Catalog<br/>[catalog.py]")]
  node_personalization["HCP Personalization<br/>[scorer.py]"]
  node_patient_safety["Patient Safety Check<br/>[patient_check.py]"]
  node_dossier_ingest["Dossier Ingestion<br/>[ingest.py]"]
  node_retrieval["Dossier Retrieval<br/>[index.py]"]
  node_embeddings["Text Embeddings<br/>[embed.py]"]
  node_llm["Answer Generation<br/>[client.py]"]
end

subgraph group_clinical_data["Clinical Data"]
  node_mongo[("MongoDB<br/>[mongo.py]")]
  node_accounts["Account Storage<br/>[accounts.py]"]
  node_sessions["Session Storage<br/>[sessions.py]"]
end

subgraph group_web["Web Dashboard"]
  node_web_app["Web Dashboard<br/>[App.jsx]"]
  node_web_api["Web API Client<br/>[api.js]"]
end

node_hcp(("Clinician"))
node_external_llm["xAI Grok"]

node_hcp -->|"scans package"| node_camera_detection
node_camera_detection -->|"submits barcode/OCR"| node_ios_api
node_ios_api -->|"calls API"| node_api_app
node_api_app -->|"registers route"| node_detect_routes
node_detect_routes -.->|"resolves identity"| node_drug_catalog
node_api_app -->|"registers route"| node_drug_routes
node_drug_routes -.->|"scores familiarity"| node_personalization
node_drug_routes -.->|"checks patient context"| node_patient_safety
node_drug_routes -.->|"retrieves dossier"| node_retrieval
node_retrieval -->|"embeds query"| node_embeddings
node_api_app -->|"loads dossiers"| node_dossier_ingest
node_dossier_ingest -.->|"creates vectors"| node_embeddings
node_drug_routes -.->|"generates answer"| node_llm
node_llm -.->|"requests completion"| node_external_llm
node_drug_routes -.->|"logs interaction"| node_engagement_routes
node_camera_detection -.->|"drives overlay"| node_hud
node_voice_session -->|"sends follow-up"| node_ios_api
node_hcp -->|"asks by voice"| node_voice_session
node_hcp -->|"scans medication list"| node_document_scan
node_document_scan -->|"saves review"| node_ios_api
node_api_app -->|"registers route"| node_auth_routes
node_api_app -->|"registers route"| node_profile_routes
node_api_app -->|"registers route"| node_review_routes
node_auth_routes -->|"manages accounts"| node_accounts
node_auth_routes -->|"creates sessions"| node_sessions
node_profile_routes -.->|"reads and writes charts"| node_mongo
node_review_routes -->|"stores reviews"| node_mongo
node_accounts -.->|"persists account data"| node_mongo
node_sessions -->|"persists sessions"| node_mongo
node_api_app -->|"initializes store"| node_mongo
node_hcp -->|"uses dashboard"| node_web_app
node_web_app -->|"requests backend data"| node_web_api
node_web_api -.->|"calls shared API"| node_api_app
node_web_app -->|"looks up and asks"| node_drug_routes
node_web_app -.->|"manages patients and chats"| node_profile_routes

click node_ios_app "https://github.com/aryavaidya08/lens/blob/main/Lens/Lens/App/HCPCopilotApp.swift"
click node_camera_detection "https://github.com/aryavaidya08/lens/blob/main/Lens/Lens/AR/ARSessionManager.swift"
click node_hud "https://github.com/aryavaidya08/lens/blob/main/Lens/Lens/AR/HUDOverlayView.swift"
click node_voice_session "https://github.com/aryavaidya08/lens/blob/main/Lens/Lens/Voice/VoiceAssistantSession.swift"
click node_document_scan "https://github.com/aryavaidya08/lens/blob/main/Lens/Lens/Detection/MedicationDocumentScanner.swift"
click node_ios_api "https://github.com/aryavaidya08/lens/blob/main/Lens/Lens/Networking/APIClient.swift"
click node_web_app "https://github.com/aryavaidya08/lens/blob/main/frontend/src/App.jsx"
click node_web_api "https://github.com/aryavaidya08/lens/blob/main/frontend/src/api.js"
click node_api_app "https://github.com/aryavaidya08/lens/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/aryavaidya08/lens/blob/main/backend/app/routes/auth.py"
click node_profile_routes "https://github.com/aryavaidya08/lens/blob/main/backend/app/routes/profile.py"
click node_detect_routes "https://github.com/aryavaidya08/lens/blob/main/backend/app/routes/detect.py"
click node_drug_routes "https://github.com/aryavaidya08/lens/blob/main/backend/app/routes/drug.py"
click node_engagement_routes "https://github.com/aryavaidya08/lens/blob/main/backend/app/routes/engagement.py"
click node_review_routes "https://github.com/aryavaidya08/lens/blob/main/backend/app/routes/medication_reviews.py"
click node_drug_catalog "https://github.com/aryavaidya08/lens/blob/main/backend/app/detection/catalog.py"
click node_personalization "https://github.com/aryavaidya08/lens/blob/main/backend/app/personalization/scorer.py"
click node_patient_safety "https://github.com/aryavaidya08/lens/blob/main/backend/app/personalization/patient_check.py"
click node_dossier_ingest "https://github.com/aryavaidya08/lens/blob/main/backend/app/retrieval/ingest.py"
click node_retrieval "https://github.com/aryavaidya08/lens/blob/main/backend/app/retrieval/index.py"
click node_embeddings "https://github.com/aryavaidya08/lens/blob/main/backend/app/retrieval/embed.py"
click node_llm "https://github.com/aryavaidya08/lens/blob/main/backend/app/llm/client.py"
click node_mongo "https://github.com/aryavaidya08/lens/blob/main/backend/app/db/mongo.py"
click node_accounts "https://github.com/aryavaidya08/lens/blob/main/backend/app/db/accounts.py"
click node_sessions "https://github.com/aryavaidya08/lens/blob/main/backend/app/db/sessions.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_ios_app,node_camera_detection,node_hud,node_voice_session,node_document_scan,node_ios_api toneBlue
class node_api_app,node_auth_routes,node_profile_routes,node_detect_routes,node_drug_routes,node_engagement_routes,node_review_routes toneAmber
class node_drug_catalog,node_personalization,node_patient_safety,node_dossier_ingest,node_retrieval,node_embeddings,node_llm toneMint
class node_mongo,node_accounts,node_sessions toneRose
class node_web_app,node_web_api,node_hcp,node_external_llm toneIndigo
```

## Components

### iOS Copilot

- [iOS App](https://github.com/aryavaidya08/lens/blob/main/Lens/Lens/App/HCPCopilotApp.swift): `Lens/Lens/App/HCPCopilotApp.swift`
- [Camera Detection](https://github.com/aryavaidya08/lens/blob/main/Lens/Lens/AR/ARSessionManager.swift): `Lens/Lens/AR/ARSessionManager.swift`
- [AR HUD](https://github.com/aryavaidya08/lens/blob/main/Lens/Lens/AR/HUDOverlayView.swift): `Lens/Lens/AR/HUDOverlayView.swift`
- [Voice Assistant](https://github.com/aryavaidya08/lens/blob/main/Lens/Lens/Voice/VoiceAssistantSession.swift): `Lens/Lens/Voice/VoiceAssistantSession.swift`
- [Medication Scan](https://github.com/aryavaidya08/lens/blob/main/Lens/Lens/Detection/MedicationDocumentScanner.swift): `Lens/Lens/Detection/MedicationDocumentScanner.swift`
- [iOS API Client](https://github.com/aryavaidya08/lens/blob/main/Lens/Lens/Networking/APIClient.swift): `Lens/Lens/Networking/APIClient.swift`

### Backend API

- [FastAPI App](https://github.com/aryavaidya08/lens/blob/main/backend/app/main.py): `backend/app/main.py`
- [Account Routes](https://github.com/aryavaidya08/lens/blob/main/backend/app/routes/auth.py): `backend/app/routes/auth.py`
- [Profile Routes](https://github.com/aryavaidya08/lens/blob/main/backend/app/routes/profile.py): `backend/app/routes/profile.py`
- [Detection Route](https://github.com/aryavaidya08/lens/blob/main/backend/app/routes/detect.py): `backend/app/routes/detect.py`
- [Drug Routes](https://github.com/aryavaidya08/lens/blob/main/backend/app/routes/drug.py): `backend/app/routes/drug.py`
- [Engagement Route](https://github.com/aryavaidya08/lens/blob/main/backend/app/routes/engagement.py): `backend/app/routes/engagement.py`
- [Review Routes](https://github.com/aryavaidya08/lens/blob/main/backend/app/routes/medication_reviews.py): `backend/app/routes/medication_reviews.py`

### Drug Intelligence

- [Drug Catalog](https://github.com/aryavaidya08/lens/blob/main/backend/app/detection/catalog.py): `backend/app/detection/catalog.py`
- [HCP Personalization](https://github.com/aryavaidya08/lens/blob/main/backend/app/personalization/scorer.py): `backend/app/personalization/scorer.py`
- [Patient Safety Check](https://github.com/aryavaidya08/lens/blob/main/backend/app/personalization/patient_check.py): `backend/app/personalization/patient_check.py`
- [Dossier Ingestion](https://github.com/aryavaidya08/lens/blob/main/backend/app/retrieval/ingest.py): `backend/app/retrieval/ingest.py`
- [Dossier Retrieval](https://github.com/aryavaidya08/lens/blob/main/backend/app/retrieval/index.py): `backend/app/retrieval/index.py`
- [Text Embeddings](https://github.com/aryavaidya08/lens/blob/main/backend/app/retrieval/embed.py): `backend/app/retrieval/embed.py`
- [Answer Generation](https://github.com/aryavaidya08/lens/blob/main/backend/app/llm/client.py): `backend/app/llm/client.py`

### Clinical Data

- [MongoDB](https://github.com/aryavaidya08/lens/blob/main/backend/app/db/mongo.py): `backend/app/db/mongo.py`
- [Account Storage](https://github.com/aryavaidya08/lens/blob/main/backend/app/db/accounts.py): `backend/app/db/accounts.py`
- [Session Storage](https://github.com/aryavaidya08/lens/blob/main/backend/app/db/sessions.py): `backend/app/db/sessions.py`

### Web Dashboard

- [Web Dashboard](https://github.com/aryavaidya08/lens/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Web API Client](https://github.com/aryavaidya08/lens/blob/main/frontend/src/api.js): `frontend/src/api.js`

### Other components

- **Clinician**
- **xAI Grok**

## Connections

- Clinician → Camera Detection: scans package (evidence: `README.md`)
- Camera Detection → iOS API Client: submits barcode/OCR (evidence: `Lens/Lens/AR/ARSessionManager.swift`)
- iOS API Client → FastAPI App: calls API (evidence: `Lens/Lens/Networking/APIClient.swift`)
- FastAPI App → Detection Route: registers route (evidence: `backend/app/main.py`)
- Detection Route → Drug Catalog: resolves identity
- FastAPI App → Drug Routes: registers route (evidence: `backend/app/main.py`)
- Drug Routes → HCP Personalization: scores familiarity (evidence: `README.md`)
- Drug Routes → Patient Safety Check: checks patient context (evidence: `README.md`)
- Drug Routes → Dossier Retrieval: retrieves dossier (evidence: `README.md`)
- Dossier Retrieval → Text Embeddings: embeds query (evidence: `backend/app/retrieval/index.py`)
- FastAPI App → Dossier Ingestion: loads dossiers (evidence: `backend/app/main.py`)
- Dossier Ingestion → Text Embeddings: creates vectors (evidence: `backend/app/retrieval/ingest.py`)
- Drug Routes → Answer Generation: generates answer (evidence: `README.md`)
- Answer Generation → xAI Grok: requests completion (evidence: `README.md`)
- Drug Routes → Engagement Route: logs interaction (evidence: `README.md`)
- Camera Detection → AR HUD: drives overlay (evidence: `README.md`)
- Voice Assistant → iOS API Client: sends follow-up (evidence: `Lens/Lens/Voice/VoiceAssistantSession.swift`)
- Clinician → Voice Assistant: asks by voice (evidence: `README.md`)
- Clinician → Medication Scan: scans medication list (evidence: `README.md`)
- Medication Scan → iOS API Client: saves review (evidence: `Lens/Lens/Views/MedicationReviewsView.swift`)
- FastAPI App → Account Routes: registers route (evidence: `backend/app/main.py`)
- FastAPI App → Profile Routes: registers route (evidence: `backend/app/main.py`)
- FastAPI App → Review Routes: registers route (evidence: `backend/app/main.py`)
- Account Routes → Account Storage: manages accounts (evidence: `backend/app/routes/auth.py`)
- Account Routes → Session Storage: creates sessions (evidence: `backend/app/routes/auth.py`)
- Profile Routes → MongoDB: reads and writes charts (evidence: `README.md`)
- Review Routes → MongoDB: stores reviews (evidence: `backend/app/routes/medication_reviews.py`)
- Account Storage → MongoDB: persists account data (evidence: `README.md`)
- Session Storage → MongoDB: persists sessions (evidence: `backend/app/db/sessions.py`)
- FastAPI App → MongoDB: initializes store (evidence: `backend/app/main.py`)
- Clinician → Web Dashboard: uses dashboard (evidence: `README.md`)
- Web Dashboard → Web API Client: requests backend data (evidence: `frontend/src/App.jsx`)
- Web API Client → FastAPI App: calls shared API (evidence: `README.md`)
- Web Dashboard → Drug Routes: looks up and asks (evidence: `frontend/src/App.jsx`)
- Web Dashboard → Profile Routes: manages patients and chats (evidence: `README.md`)