# farazajmal/gp-ultrahub-api architecture

> Architecture diagram of the GitHub repository farazajmal/gp-ultrahub-api, 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/farazajmal/gp-ultrahub-api
- Repository: https://github.com/farazajmal/gp-ultrahub-api

## Overview

GP UltraHub API serves clinic and doctor discovery endpoints alongside a conversational receptionist that turns patient messages into provider and availability results. The primary chat workflow is routed through the AI service, which coordinates intent extraction, follow-up handling, session search state, execution, and response generation; doctor search and ranking supply the matching results. Data is loaded from a remote availability feed, with a local-file fallback. The README provides no capability detail, so the broader endpoint and subsystem map is based on the tree and shown excerpts; some internal links rely on SOURCE INDEX references.

Main entry points: [`services/ai_service.py`](https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/ai_service.py) (Chat orchestration), [`services/doctor_service.py`](https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/doctor_service.py) (Doctor search), [`app.py`](https://github.com/farazajmal/gp-ultrahub-api/blob/main/app.py) (FastAPI app), [`services/data_service.py`](https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/data_service.py) (Availability data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API routes"]
  node_app["FastAPI app<br/>[app.py]"]
  node_clinic_routes["Clinic endpoints<br/>[clinics.py]"]
  node_doctor_routes["Doctor endpoints<br/>[doctors.py]"]
  node_search_routes["Search endpoint<br/>[search.py]"]
  node_chat_route["Chat endpoint<br/>[chat.py]"]
end

subgraph group_conversation["Receptionist chat"]
  node_ai["Chat orchestration<br/>[ai_service.py]"]
  node_intent["Intent extraction<br/>[intent_service.py]"]
  node_followup["Follow-up checks"]
  node_memory["Conversation memory<br/>[memory_service.py]"]
  node_search_state["Search state"]
  node_execution["Search execution"]
end

subgraph group_discovery["Doctor discovery"]
  node_doctor_service["Doctor search<br/>[doctor_service.py]"]
  node_ranking["Medical ranking<br/>[ranking_service.py]"]
end

subgraph group_shared["Shared services"]
  node_data["Availability data<br/>[data_service.py]"]
  node_date_parser["Date and time parsing<br/>[date_parser.py]"]
  node_conversation_utils["Conversation formatting<br/>[conversation.py]"]
end

node_patient(("Patient"))
node_availability_feed[("Availability feed")]
node_openai(("OpenAI"))

node_patient -->|"sends requests"| node_app
node_app -->|"registers routes"| node_clinic_routes
node_app -->|"registers routes"| node_doctor_routes
node_app -->|"registers routes"| node_search_routes
node_app -->|"registers routes"| node_chat_route
node_app -->|"loads data"| node_data
node_clinic_routes -->|"loads clinic data"| node_data
node_doctor_routes -->|"loads doctor data"| node_data
node_doctor_routes -->|"requests recommendations"| node_doctor_service
node_search_routes -->|"searches doctors"| node_doctor_service
node_chat_route -->|"handles chat"| node_ai
node_ai -->|"extracts intent"| node_intent
node_ai -->|"checks follow-up"| node_followup
node_ai -->|"uses memory"| node_memory
node_ai -->|"updates state"| node_search_state
node_ai -->|"dispatches search"| node_execution
node_ai -->|"requests matches"| node_doctor_service
node_ai -->|"loads data"| node_data
node_ai -->|"parses availability"| node_date_parser
node_intent -->|"formats history"| node_conversation_utils
node_intent -->|"normalizes days"| node_date_parser
node_followup -->|"formats history"| node_conversation_utils
node_execution -->|"runs search"| node_doctor_service
node_doctor_service -->|"loads records"| node_data
node_doctor_service -->|"scores matches"| node_ranking
node_doctor_service -->|"filters availability"| node_date_parser
node_data -->|"fetches records"| node_availability_feed
node_intent -->|"requests extraction"| node_openai
node_followup -->|"requests evaluation"| node_openai

click node_app "https://github.com/farazajmal/gp-ultrahub-api/blob/main/app.py"
click node_clinic_routes "https://github.com/farazajmal/gp-ultrahub-api/blob/main/routes/clinics.py"
click node_doctor_routes "https://github.com/farazajmal/gp-ultrahub-api/blob/main/routes/doctors.py"
click node_search_routes "https://github.com/farazajmal/gp-ultrahub-api/blob/main/routes/search.py"
click node_chat_route "https://github.com/farazajmal/gp-ultrahub-api/blob/main/routes/chat.py"
click node_ai "https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/ai_service.py"
click node_intent "https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/intent_service.py"
click node_followup "https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/followup_service.py"
click node_memory "https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/memory_service.py"
click node_search_state "https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/search_state_service.py"
click node_execution "https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/execution_service.py"
click node_doctor_service "https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/doctor_service.py"
click node_ranking "https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/ranking_service.py"
click node_data "https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/data_service.py"
click node_date_parser "https://github.com/farazajmal/gp-ultrahub-api/blob/main/utils/date_parser.py"
click node_conversation_utils "https://github.com/farazajmal/gp-ultrahub-api/blob/main/utils/conversation.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_clinic_routes,node_doctor_routes,node_search_routes,node_chat_route toneBlue
class node_ai,node_intent,node_followup,node_memory,node_search_state,node_execution,node_availability_feed toneAmber
class node_doctor_service,node_ranking toneMint
class node_data,node_date_parser,node_conversation_utils toneRose
class node_patient,node_openai toneIndigo
```

## Components

### API routes

- [FastAPI app](https://github.com/farazajmal/gp-ultrahub-api/blob/main/app.py): `app.py`
- [Clinic endpoints](https://github.com/farazajmal/gp-ultrahub-api/blob/main/routes/clinics.py): `routes/clinics.py`
- [Doctor endpoints](https://github.com/farazajmal/gp-ultrahub-api/blob/main/routes/doctors.py): `routes/doctors.py`
- [Search endpoint](https://github.com/farazajmal/gp-ultrahub-api/blob/main/routes/search.py): `routes/search.py`
- [Chat endpoint](https://github.com/farazajmal/gp-ultrahub-api/blob/main/routes/chat.py): `routes/chat.py`

### Receptionist chat

- [Chat orchestration](https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/ai_service.py): `services/ai_service.py`
- [Intent extraction](https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/intent_service.py): `services/intent_service.py`
- [Follow-up checks](https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/followup_service.py): `services/followup_service.py`
- [Conversation memory](https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/memory_service.py): `services/memory_service.py`
- [Search state](https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/search_state_service.py): `services/search_state_service.py`
- [Search execution](https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/execution_service.py): `services/execution_service.py`

### Doctor discovery

- [Doctor search](https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/doctor_service.py): `services/doctor_service.py`
- [Medical ranking](https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/ranking_service.py): `services/ranking_service.py`

### Shared services

- [Availability data](https://github.com/farazajmal/gp-ultrahub-api/blob/main/services/data_service.py): `services/data_service.py`
- [Date and time parsing](https://github.com/farazajmal/gp-ultrahub-api/blob/main/utils/date_parser.py): `utils/date_parser.py`
- [Conversation formatting](https://github.com/farazajmal/gp-ultrahub-api/blob/main/utils/conversation.py): `utils/conversation.py`

### Other components

- **Patient**
- **Availability feed**
- **OpenAI**

## Connections

- Patient → FastAPI app: sends requests (evidence: `app.py`)
- FastAPI app → Clinic endpoints: registers routes (evidence: `app.py`)
- FastAPI app → Doctor endpoints: registers routes (evidence: `app.py`)
- FastAPI app → Search endpoint: registers routes (evidence: `app.py`)
- FastAPI app → Chat endpoint: registers routes (evidence: `app.py`)
- FastAPI app → Availability data: loads data (evidence: `app.py`)
- Clinic endpoints → Availability data: loads clinic data (evidence: `routes/clinics.py`)
- Doctor endpoints → Availability data: loads doctor data (evidence: `routes/doctors.py`)
- Doctor endpoints → Doctor search: requests recommendations (evidence: `routes/doctors.py`)
- Search endpoint → Doctor search: searches doctors (evidence: `routes/search.py`)
- Chat endpoint → Chat orchestration: handles chat (evidence: `routes/chat.py`)
- Chat orchestration → Intent extraction: extracts intent (evidence: `services/ai_service.py`)
- Chat orchestration → Follow-up checks: checks follow-up (evidence: `services/ai_service.py`)
- Chat orchestration → Conversation memory: uses memory (evidence: `services/ai_service.py`)
- Chat orchestration → Search state: updates state (evidence: `services/ai_service.py`)
- Chat orchestration → Search execution: dispatches search (evidence: `services/ai_service.py`)
- Chat orchestration → Doctor search: requests matches (evidence: `services/ai_service.py`)
- Chat orchestration → Availability data: loads data (evidence: `services/ai_service.py`)
- Chat orchestration → Date and time parsing: parses availability (evidence: `services/ai_service.py`)
- Intent extraction → Conversation formatting: formats history (evidence: `services/intent_service.py`)
- Intent extraction → Date and time parsing: normalizes days (evidence: `services/intent_service.py`)
- Follow-up checks → Conversation formatting: formats history (evidence: `services/followup_service.py`)
- Search execution → Doctor search: runs search (evidence: `services/execution_service.py`)
- Doctor search → Availability data: loads records (evidence: `services/doctor_service.py`)
- Doctor search → Medical ranking: scores matches (evidence: `services/doctor_service.py`)
- Doctor search → Date and time parsing: filters availability (evidence: `services/doctor_service.py`)
- Availability data → Availability feed: fetches records (evidence: `services/data_service.py`)
- Intent extraction → OpenAI: requests extraction (evidence: `services/intent_service.py`)
- Follow-up checks → OpenAI: requests evaluation (evidence: `services/followup_service.py`)
