# mohammed-alshaibani/healthyai architecture

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

## Overview

HealTrip AI helps patients in Saudi Arabia find healthcare providers through a bilingual chat assistant and a provider directory. In the chat flow, the web client sends a message to the API; the API validates it, checks for emergencies before invoking the agent, and the agent can request doctor or hospital searches. Search results are grounded in database data, with fallback datasets when the database is unavailable. The directory also supports provider registration. The README documents uploads and bilingual UI; source excerpts do not show the full upload path or all directory API wiring.

Main entry points: [`apps/web/src/components/ChatWindow.tsx`](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/web/src/components/ChatWindow.tsx) (Chat UI), [`apps/api/src/chat/chat.service.ts`](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/chat/chat.service.ts) (Chat Service), [`apps/api/src/agent/agent.ts`](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/agent/agent.ts) (Agent Orchestrator), [`apps/api/src/doctors/doctors.service.ts`](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/doctors/doctors.service.ts) (Doctor Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Patient Web App"]
  node_chat_ui["Chat UI<br/>[ChatWindow.tsx]"]
  node_chat_input["Chat Input<br/>[ChatInput.tsx]"]
  node_message_list["Message List<br/>[MessageList.tsx]"]
  node_web_api["Web API Client<br/>[api.ts]"]
  node_directory_ui["Provider Directory<br/>[page.tsx]"]
end

subgraph group_api["API Orchestration"]
  node_api_app["API App<br/>[app.ts]"]
  node_chat_controller["Chat Endpoint<br/>[chat.controller.ts]"]
  node_chat_service["Chat Service<br/>[chat.service.ts]"]
  node_validation["Request Validation"]
  node_safety["Emergency Safety<br/>[safety.service.ts]"]
  node_provider_controller["Provider Endpoints"]
end

subgraph group_assistant["Assistant and Search"]
  node_agent["Agent Orchestrator<br/>[agent.ts]"]
  node_prompts["Agent Prompts<br/>[prompts.ts]"]
  node_tool_registry["Search Tool Registry<br/>[tools.ts]"]
  node_llm_adapter["OpenAI Adapter<br/>[openai-adapter.ts]"]
  node_llm_interface["LLM Interface<br/>[llm-provider.ts]"]
end

subgraph group_data["Healthcare Data"]
  node_provider_service["Provider Service"]
  node_doctor_search["Doctor Search<br/>[doctors.service.ts]"]
  node_hospital_search["Hospital Search"]
  node_geo["Geo Resolution<br/>[geo.ts]"]
  node_fallback["Fallback Data<br/>[fallback-data.ts]"]
  node_prisma["Prisma Client<br/>[prisma.ts]"]
end

node_patient(("Patient"))
node_postgres[("PostgreSQL")]
node_nominatim["Nominatim"]

node_patient -->|"uses"| node_chat_ui
node_chat_ui -->|"renders"| node_chat_input
node_chat_ui -->|"renders"| node_message_list
node_chat_ui -->|"sends messages"| node_web_api
node_web_api -->|"POSTs chat"| node_chat_controller
node_api_app -->|"routes chat"| node_chat_controller
node_chat_controller -->|"validates request"| node_validation
node_chat_controller -->|"delegates message"| node_chat_service
node_chat_service -->|"checks emergency"| node_safety
node_chat_service -->|"builds location context"| node_prompts
node_chat_service -->|"runs agent"| node_agent
node_agent -->|"dispatches tools"| node_tool_registry
node_agent -->|"uses prompts"| node_prompts
node_agent -->|"requests completion"| node_llm_interface
node_llm_adapter -->|"implements"| node_llm_interface
node_tool_registry -->|"searches doctors"| node_doctor_search
node_tool_registry -->|"searches hospitals"| node_hospital_search
node_doctor_search -->|"queries"| node_prisma
node_hospital_search -->|"queries"| node_prisma
node_prisma -.->|"accesses"| node_postgres
node_doctor_search -->|"uses on failure"| node_fallback
node_hospital_search -->|"uses on failure"| node_fallback
node_doctor_search -->|"resolves location"| node_geo
node_hospital_search -->|"resolves location"| node_geo
node_geo -->|"reverse geocodes"| node_nominatim
node_patient -->|"browses providers"| node_directory_ui
node_directory_ui -.->|"requests directory actions"| node_provider_controller
node_api_app -->|"routes providers"| node_provider_controller
node_provider_controller -->|"validates registration"| node_validation
node_provider_controller -->|"delegates provider actions"| node_provider_service
node_provider_service -->|"queries and writes"| node_prisma

click node_chat_ui "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/web/src/components/ChatWindow.tsx"
click node_chat_input "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/web/src/components/ChatInput.tsx"
click node_message_list "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/web/src/components/MessageList.tsx"
click node_web_api "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/web/src/lib/api.ts"
click node_directory_ui "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/web/src/app/providers/page.tsx"
click node_api_app "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/app.ts"
click node_chat_controller "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/chat/chat.controller.ts"
click node_chat_service "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/chat/chat.service.ts"
click node_validation "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/shared/middleware/validate-request.ts"
click node_safety "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/safety/safety.service.ts"
click node_provider_controller "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/providers/providers.controller.ts"
click node_provider_service "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/providers/providers.service.ts"
click node_agent "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/agent/agent.ts"
click node_prompts "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/agent/prompts.ts"
click node_tool_registry "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/agent/tools.ts"
click node_llm_adapter "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/llm/openai-adapter.ts"
click node_llm_interface "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/llm/llm-provider.ts"
click node_doctor_search "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/doctors/doctors.service.ts"
click node_hospital_search "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/hospitals/hospitals.service.ts"
click node_geo "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/shared/geo.ts"
click node_fallback "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/shared/fallback-data.ts"
click node_prisma "https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/lib/prisma.ts"

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_chat_ui,node_chat_input,node_message_list,node_web_api,node_directory_ui toneBlue
class node_api_app,node_chat_controller,node_chat_service,node_validation,node_safety,node_provider_controller,node_postgres toneAmber
class node_agent,node_prompts,node_tool_registry,node_llm_adapter,node_llm_interface toneMint
class node_provider_service,node_doctor_search,node_hospital_search,node_geo,node_fallback,node_prisma toneRose
class node_patient,node_nominatim toneIndigo
```

## Components

### Patient Web App

- [Chat UI](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/web/src/components/ChatWindow.tsx): `apps/web/src/components/ChatWindow.tsx`
- [Chat Input](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/web/src/components/ChatInput.tsx): `apps/web/src/components/ChatInput.tsx`
- [Message List](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/web/src/components/MessageList.tsx): `apps/web/src/components/MessageList.tsx`
- [Web API Client](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`
- [Provider Directory](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/web/src/app/providers/page.tsx): `apps/web/src/app/providers/page.tsx`

### API Orchestration

- [API App](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Chat Endpoint](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/chat/chat.controller.ts): `apps/api/src/chat/chat.controller.ts`
- [Chat Service](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/chat/chat.service.ts): `apps/api/src/chat/chat.service.ts`
- [Request Validation](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/shared/middleware/validate-request.ts): `apps/api/src/shared/middleware/validate-request.ts`
- [Emergency Safety](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/safety/safety.service.ts): `apps/api/src/safety/safety.service.ts`
- [Provider Endpoints](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/providers/providers.controller.ts): `apps/api/src/providers/providers.controller.ts`

### Assistant and Search

- [Agent Orchestrator](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/agent/agent.ts): `apps/api/src/agent/agent.ts`
- [Agent Prompts](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/agent/prompts.ts): `apps/api/src/agent/prompts.ts`
- [Search Tool Registry](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/agent/tools.ts): `apps/api/src/agent/tools.ts`
- [OpenAI Adapter](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/llm/openai-adapter.ts): `apps/api/src/llm/openai-adapter.ts`
- [LLM Interface](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/llm/llm-provider.ts): `apps/api/src/llm/llm-provider.ts`

### Healthcare Data

- [Provider Service](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/providers/providers.service.ts): `apps/api/src/providers/providers.service.ts`
- [Doctor Search](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/doctors/doctors.service.ts): `apps/api/src/doctors/doctors.service.ts`
- [Hospital Search](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/hospitals/hospitals.service.ts): `apps/api/src/hospitals/hospitals.service.ts`
- [Geo Resolution](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/shared/geo.ts): `apps/api/src/shared/geo.ts`
- [Fallback Data](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/shared/fallback-data.ts): `apps/api/src/shared/fallback-data.ts`
- [Prisma Client](https://github.com/mohammed-alshaibani/healthyai/blob/main/apps/api/src/lib/prisma.ts): `apps/api/src/lib/prisma.ts`

### Other components

- **Patient**
- **PostgreSQL**
- **Nominatim**

## Connections

- Patient → Chat UI: uses (evidence: `README.md`)
- Chat UI → Chat Input: renders (evidence: `apps/web/src/components/ChatWindow.tsx`)
- Chat UI → Message List: renders (evidence: `apps/web/src/components/ChatWindow.tsx`)
- Chat UI → Web API Client: sends messages (evidence: `apps/web/src/components/ChatWindow.tsx`)
- Web API Client → Chat Endpoint: POSTs chat (evidence: `apps/web/src/lib/api.ts`)
- API App → Chat Endpoint: routes chat (evidence: `apps/api/src/app.ts`)
- Chat Endpoint → Request Validation: validates request (evidence: `apps/api/src/chat/chat.controller.ts`)
- Chat Endpoint → Chat Service: delegates message (evidence: `apps/api/src/chat/chat.controller.ts`)
- Chat Service → Emergency Safety: checks emergency (evidence: `apps/api/src/chat/chat.service.ts`)
- Chat Service → Agent Prompts: builds location context (evidence: `apps/api/src/chat/chat.service.ts`)
- Chat Service → Agent Orchestrator: runs agent (evidence: `apps/api/src/chat/chat.service.ts`)
- Agent Orchestrator → Search Tool Registry: dispatches tools (evidence: `apps/api/src/agent/agent.ts`)
- Agent Orchestrator → Agent Prompts: uses prompts (evidence: `apps/api/src/agent/agent.ts`)
- Agent Orchestrator → LLM Interface: requests completion (evidence: `apps/api/src/agent/agent.ts`)
- OpenAI Adapter → LLM Interface: implements (evidence: `apps/api/src/llm/openai-adapter.ts`)
- Search Tool Registry → Doctor Search: searches doctors (evidence: `apps/api/src/agent/tools.ts`)
- Search Tool Registry → Hospital Search: searches hospitals (evidence: `apps/api/src/agent/tools.ts`)
- Doctor Search → Prisma Client: queries (evidence: `apps/api/src/doctors/doctors.service.ts`)
- Hospital Search → Prisma Client: queries (evidence: `apps/api/src/hospitals/hospitals.service.ts`)
- Prisma Client → PostgreSQL: accesses
- Doctor Search → Fallback Data: uses on failure (evidence: `apps/api/src/doctors/doctors.service.ts`)
- Hospital Search → Fallback Data: uses on failure (evidence: `apps/api/src/hospitals/hospitals.service.ts`)
- Doctor Search → Geo Resolution: resolves location (evidence: `apps/api/src/doctors/doctors.service.ts`)
- Hospital Search → Geo Resolution: resolves location (evidence: `apps/api/src/hospitals/hospitals.service.ts`)
- Geo Resolution → Nominatim: reverse geocodes (evidence: `apps/api/src/shared/geo.ts`)
- Patient → Provider Directory: browses providers (evidence: `apps/web/src/app/providers/page.tsx`)
- Provider Directory → Provider Endpoints: requests directory actions
- API App → Provider Endpoints: routes providers (evidence: `apps/api/src/app.ts`)
- Provider Endpoints → Request Validation: validates registration (evidence: `apps/api/src/providers/providers.controller.ts`)
- Provider Endpoints → Provider Service: delegates provider actions (evidence: `apps/api/src/providers/providers.controller.ts`)
- Provider Service → Prisma Client: queries and writes (evidence: `apps/api/src/providers/providers.service.ts`)