# anushkapunekar/careflow-ai architecture

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

- Interactive diagram: https://gitdiagram.com/anushkapunekar/careflow-ai
- Repository: https://github.com/anushkapunekar/careflow-ai

## Overview

CareFlow AI is a browser-based voice receptionist: a user speaks through the web UI, FastAPI manages conversational and appointment context, and the LLM can request clinic-knowledge retrieval or appointment actions. Appointment tools use SQLite as the authority for availability and booking; RAG retrieves clinic information from a local FAQ and FAISS index. The README documents additional cancellation/rescheduling and protected administrative RAG capabilities; their exact endpoint wiring is not fully visible in the excerpts.

Main entry points: [`app/main.py`](https://github.com/anushkapunekar/careflow-ai/blob/main/app/main.py) (FastAPI service), [`app/rag.py`](https://github.com/anushkapunekar/careflow-ai/blob/main/app/rag.py) (RAG search), [`static/index.html`](https://github.com/anushkapunekar/careflow-ai/blob/main/static/index.html) (Voice web UI), [`app/llm.py`](https://github.com/anushkapunekar/careflow-ai/blob/main/app/llm.py) (LLM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Voice interaction"]
  node_browser["Voice web UI<br/>[index.html]"]
  node_api["FastAPI service<br/>[main.py]"]
end

subgraph group_agent["Conversation agent"]
  node_llm["LLM client<br/>[llm.py]"]
  node_groq["Groq API"]
end

subgraph group_appointments["Appointment management"]
  node_tools["Appointment tools<br/>[tools.py]"]
  node_db[("SQLite database<br/>[database.py]")]
end

subgraph group_knowledge["Clinic knowledge"]
  node_rag["RAG search<br/>[rag.py]"]
  node_hf["Hugging Face embeddings"]
  node_faq["Clinic FAQ<br/>[clinic_faq.txt]"]
  node_index[("FAISS index<br/>[careflow.index]")]
  node_chunks["FAQ chunks<br/>[chunks.json]"]
end

node_user(("Clinic visitor"))
node_admin(("Admin operator"))

node_user -->|"speaks to"| node_browser
node_browser -->|"sends interaction"| node_api
node_api -->|"returns response"| node_browser
node_api -->|"requests response"| node_llm
node_llm -->|"calls model"| node_groq
node_api -->|"dispatches actions"| node_tools
node_api -->|"searches knowledge"| node_rag
node_tools -->|"reads and updates"| node_db
node_rag -->|"requests embeddings"| node_hf
node_rag -->|"loads source text"| node_faq
node_rag -->|"searches vectors"| node_index
node_rag -->|"loads chunk text"| node_chunks
node_admin -.->|"uses protected operations"| node_api

click node_browser "https://github.com/anushkapunekar/careflow-ai/blob/main/static/index.html"
click node_api "https://github.com/anushkapunekar/careflow-ai/blob/main/app/main.py"
click node_llm "https://github.com/anushkapunekar/careflow-ai/blob/main/app/llm.py"
click node_tools "https://github.com/anushkapunekar/careflow-ai/blob/main/app/tools.py"
click node_db "https://github.com/anushkapunekar/careflow-ai/blob/main/app/database.py"
click node_rag "https://github.com/anushkapunekar/careflow-ai/blob/main/app/rag.py"
click node_faq "https://github.com/anushkapunekar/careflow-ai/blob/main/knowledge/clinic_faq.txt"
click node_index "https://github.com/anushkapunekar/careflow-ai/blob/main/knowledge/careflow.index"
click node_chunks "https://github.com/anushkapunekar/careflow-ai/blob/main/knowledge/chunks.json"

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_browser,node_api toneBlue
class node_llm,node_groq toneAmber
class node_tools,node_db toneMint
class node_rag,node_hf,node_faq,node_index,node_chunks toneRose
class node_user,node_admin toneIndigo
```

## Components

### Voice interaction

- [Voice web UI](https://github.com/anushkapunekar/careflow-ai/blob/main/static/index.html): `static/index.html`
- [FastAPI service](https://github.com/anushkapunekar/careflow-ai/blob/main/app/main.py): `app/main.py`

### Conversation agent

- [LLM client](https://github.com/anushkapunekar/careflow-ai/blob/main/app/llm.py): `app/llm.py`
- **Groq API**

### Appointment management

- [Appointment tools](https://github.com/anushkapunekar/careflow-ai/blob/main/app/tools.py): `app/tools.py`
- [SQLite database](https://github.com/anushkapunekar/careflow-ai/blob/main/app/database.py): `app/database.py`

### Clinic knowledge

- [RAG search](https://github.com/anushkapunekar/careflow-ai/blob/main/app/rag.py): `app/rag.py`
- **Hugging Face embeddings**
- [Clinic FAQ](https://github.com/anushkapunekar/careflow-ai/blob/main/knowledge/clinic_faq.txt): `knowledge/clinic_faq.txt`
- [FAISS index](https://github.com/anushkapunekar/careflow-ai/blob/main/knowledge/careflow.index): `knowledge/careflow.index`
- [FAQ chunks](https://github.com/anushkapunekar/careflow-ai/blob/main/knowledge/chunks.json): `knowledge/chunks.json`

### Other components

- **Clinic visitor**
- **Admin operator**

## Connections

- Clinic visitor → Voice web UI: speaks to
- Voice web UI → FastAPI service: sends interaction
- FastAPI service → Voice web UI: returns response
- FastAPI service → LLM client: requests response
- LLM client → Groq API: calls model
- FastAPI service → Appointment tools: dispatches actions
- FastAPI service → RAG search: searches knowledge
- Appointment tools → SQLite database: reads and updates
- RAG search → Hugging Face embeddings: requests embeddings
- RAG search → Clinic FAQ: loads source text
- RAG search → FAISS index: searches vectors
- RAG search → FAQ chunks: loads chunk text
- Admin operator → FastAPI service: uses protected operations