# lindsey5/healthcare-scheduling-system-ai architecture

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

- Interactive diagram: https://gitdiagram.com/lindsey5/healthcare-scheduling-system-ai
- Repository: https://github.com/lindsey5/healthcare-scheduling-system-ai

## Overview

This repository implements a healthcare-center chat API. A user submits a message to the chat route, which invokes a stateful agent; the agent can answer from the FAQ knowledge base or call external services for service listings and appointment details. The FAQ path retrieves and formats relevant answers from a persisted FAISS index built from the dataset. The README is empty, so capabilities and connections here are based on the sampled source and file tree; the external service API’s implementation is not present.

Main entry points: [`rag/vectorstore.py`](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/rag/vectorstore.py) (Vector store), [`routes/ai_agent_routes.py`](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/routes/ai_agent_routes.py) (Chat endpoint), [`agent/agent.py`](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/agent/agent.py) (Chat agent), [`agent/tools.py`](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/agent/tools.py) (Chat tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Chat API"]
  node_app["FastAPI app<br/>[app.py]"]
  node_chat_route["Chat endpoint<br/>[ai_agent_routes.py]"]
end

subgraph group_agent["Agent and tools"]
  node_agent_runtime["Chat agent<br/>[agent.py]"]
  node_toolset["Chat tools<br/>[tools.py]"]
end

subgraph group_knowledge["FAQ knowledge"]
  node_qa_chain["FAQ retrieval<br/>[chain.py]"]
  node_vectorstore["Vector store<br/>[vectorstore.py]"]
  node_ingest["FAQ ingestion<br/>[ingest.py]"]
  node_faq_data["FAQ dataset<br/>[datasets.json]"]
  node_faiss_index[("FAISS index<br/>[index.faiss]")]
  node_faiss_metadata["Index metadata<br/>[index.pkl]"]
end

subgraph group_models["Model providers"]
  node_model_factory["Model factory<br/>[model.py]"]
  node_chat_model{{"OpenRouter chat model"}}
  node_embedding_service{{"Embedding service"}}
end

node_user(("Chat user"))
node_health_api{{"Healthcare API"}}

node_user -->|"sends message"| node_chat_route
node_app -->|"registers route"| node_chat_route
node_app -->|"initializes"| node_agent_runtime
node_chat_route -->|"invokes"| node_agent_runtime
node_agent_runtime -->|"dispatches tools"| node_toolset
node_agent_runtime -->|"selects model"| node_model_factory
node_model_factory -->|"creates client"| node_chat_model
node_toolset -->|"asks questions"| node_qa_chain
node_qa_chain -->|"retrieves matches"| node_vectorstore
node_vectorstore -->|"loads and searches"| node_faiss_index
node_vectorstore -->|"loads metadata"| node_faiss_metadata
node_toolset -->|"fetches services or appointments"| node_health_api
node_ingest -->|"reads FAQs"| node_faq_data
node_ingest -->|"builds index"| node_vectorstore
node_vectorstore -->|"requests embeddings"| node_embedding_service
node_chat_route -->|"returns reply"| node_user

click node_app "https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/app.py"
click node_chat_route "https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/routes/ai_agent_routes.py"
click node_agent_runtime "https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/agent/agent.py"
click node_toolset "https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/agent/tools.py"
click node_qa_chain "https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/rag/chain.py"
click node_vectorstore "https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/rag/vectorstore.py"
click node_ingest "https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/rag/ingest.py"
click node_faq_data "https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/data/datasets.json"
click node_faiss_index "https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/faiss_db/index.faiss"
click node_faiss_metadata "https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/faiss_db/index.pkl"
click node_model_factory "https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/llm/model.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_app,node_chat_route,node_user toneBlue
class node_agent_runtime,node_toolset toneAmber
class node_qa_chain,node_vectorstore,node_ingest,node_faq_data,node_faiss_index,node_faiss_metadata,node_health_api toneMint
class node_model_factory,node_chat_model,node_embedding_service toneRose
```

## Components

### Chat API

- [FastAPI app](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/app.py): `app.py`
- [Chat endpoint](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/routes/ai_agent_routes.py): `routes/ai_agent_routes.py`

### Agent and tools

- [Chat agent](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/agent/agent.py): `agent/agent.py`
- [Chat tools](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/agent/tools.py): `agent/tools.py`

### FAQ knowledge

- [FAQ retrieval](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/rag/chain.py): `rag/chain.py`
- [Vector store](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/rag/vectorstore.py): `rag/vectorstore.py`
- [FAQ ingestion](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/rag/ingest.py): `rag/ingest.py`
- [FAQ dataset](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/data/datasets.json): `data/datasets.json`
- [FAISS index](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/faiss_db/index.faiss): `faiss_db/index.faiss`
- [Index metadata](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/faiss_db/index.pkl): `faiss_db/index.pkl`

### Model providers

- [Model factory](https://github.com/lindsey5/healthcare-scheduling-system-ai/blob/main/llm/model.py): `llm/model.py`
- **OpenRouter chat model**
- **Embedding service**

### Other components

- **Chat user**
- **Healthcare API**

## Connections

- Chat user → Chat endpoint: sends message
- FastAPI app → Chat endpoint: registers route
- FastAPI app → Chat agent: initializes
- Chat endpoint → Chat agent: invokes
- Chat agent → Chat tools: dispatches tools
- Chat agent → Model factory: selects model
- Model factory → OpenRouter chat model: creates client
- Chat tools → FAQ retrieval: asks questions
- FAQ retrieval → Vector store: retrieves matches
- Vector store → FAISS index: loads and searches
- Vector store → Index metadata: loads metadata
- Chat tools → Healthcare API: fetches services or appointments
- FAQ ingestion → FAQ dataset: reads FAQs
- FAQ ingestion → Vector store: builds index
- Vector store → Embedding service: requests embeddings
- Chat endpoint → Chat user: returns reply