# heykvr/dental-client-management-backend architecture

> Architecture diagram of the GitHub repository heykvr/dental-client-management-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/heykvr/dental-client-management-backend
- Repository: https://github.com/heykvr/dental-client-management-backend

## Overview

This is a FastAPI backend for dental-clinic patient and case-sheet management. Clinic staff use its REST API to create, find, and update patients; record clinical case sheets; view dashboard metrics; request grounded, stateless AI chat; and receive AI summaries that refresh after changes. The documented architecture is routes → services → repositories. The graph includes validation, persistence, Gemini, and the background-summary capability. Some route and service implementations were not excerpted, so their edges rely on the SOURCE INDEX or README where available.

Main entry points: [`app/api/deps.py`](https://github.com/heykvr/dental-client-management-backend/blob/main/app/api/deps.py) (Dependency wiring), [`app/services/chat_service.py`](https://github.com/heykvr/dental-client-management-backend/blob/main/app/services/chat_service.py) (Patient-grounded chat), [`app/api/v1`](https://github.com/heykvr/dental-client-management-backend/tree/main/app/api/v1) (REST routes), [`app/repositories/case_sheet_repo.py`](https://github.com/heykvr/dental-client-management-backend/blob/main/app/repositories/case_sheet_repo.py) (Case-sheet repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and validation"]
  node_api_routes["REST routes"]
  node_dependencies["Dependency wiring<br/>[deps.py]"]
  node_patient_schema["Patient validation<br/>[patient.py]"]
  node_case_schema["Case-sheet validation<br/>[case_sheet.py]"]
end

subgraph group_domain["Clinic workflows"]
  node_patient_service["Patient workflow<br/>[patient_service.py]"]
  node_case_service["Case-sheet workflow"]
  node_dashboard_service["Dashboard metrics"]
end

subgraph group_storage["Persistence"]
  node_patient_repo["Patient repository<br/>[patient_repo.py]"]
  node_case_repo["Case-sheet repository<br/>[case_sheet_repo.py]"]
  node_counter_repo["ID counter<br/>[counter_repo.py]"]
end

subgraph group_ai["AI features"]
  node_summary_service["Summary generation<br/>[summary_service.py]"]
  node_chat_service["Patient-grounded chat<br/>[chat_service.py]"]
  node_ai_service["AI client<br/>[ai_service.py]"]
  node_summary_prompt["Summary instructions<br/>[summary.txt]"]
  node_chat_prompt["Chat instructions<br/>[chat_system.txt]"]
end

subgraph group_platform["Runtime foundations"]
  node_runtime["Application startup<br/>[main.py]"]
  node_database_setup["Database connection<br/>[database.py]"]
  node_rate_limit["Request rate limits<br/>[rate_limit.py]"]
  node_error_handlers["Error responses<br/>[exceptions.py]"]
end

node_staff(("Clinic staff"))
node_mongodb[("MongoDB")]
node_gemini["Google Gemini"]

node_staff -->|"sends requests"| node_api_routes
node_api_routes -->|"resolves services"| node_dependencies
node_dependencies -->|"constructs"| node_patient_service
node_dependencies -->|"constructs"| node_case_service
node_dependencies -->|"constructs"| node_dashboard_service
node_dependencies -->|"constructs"| node_summary_service
node_dependencies -->|"constructs"| node_chat_service
node_api_routes -->|"validates patient data"| node_patient_schema
node_api_routes -->|"validates case data"| node_case_schema
node_patient_service -->|"reads and writes"| node_patient_repo
node_patient_service -->|"allocates IDs"| node_counter_repo
node_case_service -->|"reads and saves"| node_case_repo
node_dashboard_service -->|"aggregates patients"| node_patient_repo
node_dashboard_service -->|"counts statuses"| node_case_repo
node_summary_service -->|"loads and saves summary"| node_case_repo
node_summary_service -->|"generates summary"| node_ai_service
node_summary_service -->|"loads instructions"| node_summary_prompt
node_chat_service -->|"requests response"| node_ai_service
node_chat_service -->|"uses case workflow"| node_case_service
node_chat_service -->|"uses patient workflow"| node_patient_service
node_chat_service -->|"loads clinical record"| node_case_repo
node_chat_service -.->|"uses instructions"| node_chat_prompt
node_ai_service -->|"calls provider"| node_gemini
node_patient_repo -->|"queries patients"| node_mongodb
node_case_repo -->|"queries embedded sheets"| node_mongodb
node_counter_repo -->|"allocates sequence"| node_mongodb
node_runtime -->|"mounts router"| node_api_routes
node_runtime -->|"initializes database"| node_database_setup
node_api_routes -->|"applies limits"| node_rate_limit
node_runtime -->|"registers handlers"| node_error_handlers

click node_api_routes "https://github.com/heykvr/dental-client-management-backend/tree/main/app/api/v1"
click node_dependencies "https://github.com/heykvr/dental-client-management-backend/blob/main/app/api/deps.py"
click node_patient_schema "https://github.com/heykvr/dental-client-management-backend/blob/main/app/schemas/patient.py"
click node_case_schema "https://github.com/heykvr/dental-client-management-backend/blob/main/app/schemas/case_sheet.py"
click node_patient_service "https://github.com/heykvr/dental-client-management-backend/blob/main/app/services/patient_service.py"
click node_case_service "https://github.com/heykvr/dental-client-management-backend/blob/main/app/services/case_sheet_service.py"
click node_dashboard_service "https://github.com/heykvr/dental-client-management-backend/blob/main/app/services/dashboard_service.py"
click node_patient_repo "https://github.com/heykvr/dental-client-management-backend/blob/main/app/repositories/patient_repo.py"
click node_case_repo "https://github.com/heykvr/dental-client-management-backend/blob/main/app/repositories/case_sheet_repo.py"
click node_counter_repo "https://github.com/heykvr/dental-client-management-backend/blob/main/app/repositories/counter_repo.py"
click node_summary_service "https://github.com/heykvr/dental-client-management-backend/blob/main/app/services/summary_service.py"
click node_chat_service "https://github.com/heykvr/dental-client-management-backend/blob/main/app/services/chat_service.py"
click node_ai_service "https://github.com/heykvr/dental-client-management-backend/blob/main/app/services/ai_service.py"
click node_summary_prompt "https://github.com/heykvr/dental-client-management-backend/blob/main/app/prompts/summary.txt"
click node_chat_prompt "https://github.com/heykvr/dental-client-management-backend/blob/main/app/prompts/chat_system.txt"
click node_runtime "https://github.com/heykvr/dental-client-management-backend/blob/main/app/main.py"
click node_database_setup "https://github.com/heykvr/dental-client-management-backend/blob/main/app/core/database.py"
click node_rate_limit "https://github.com/heykvr/dental-client-management-backend/blob/main/app/core/rate_limit.py"
click node_error_handlers "https://github.com/heykvr/dental-client-management-backend/blob/main/app/core/exceptions.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_api_routes,node_dependencies,node_patient_schema,node_case_schema toneBlue
class node_patient_service,node_case_service,node_dashboard_service,node_mongodb toneAmber
class node_patient_repo,node_case_repo,node_counter_repo toneMint
class node_summary_service,node_chat_service,node_ai_service,node_summary_prompt,node_chat_prompt toneRose
class node_runtime,node_database_setup,node_rate_limit,node_error_handlers,node_staff,node_gemini toneIndigo
```

## Components

### API and validation

- [REST routes](https://github.com/heykvr/dental-client-management-backend/tree/main/app/api/v1): `app/api/v1`
- [Dependency wiring](https://github.com/heykvr/dental-client-management-backend/blob/main/app/api/deps.py): `app/api/deps.py`
- [Patient validation](https://github.com/heykvr/dental-client-management-backend/blob/main/app/schemas/patient.py): `app/schemas/patient.py`
- [Case-sheet validation](https://github.com/heykvr/dental-client-management-backend/blob/main/app/schemas/case_sheet.py): `app/schemas/case_sheet.py`

### Clinic workflows

- [Patient workflow](https://github.com/heykvr/dental-client-management-backend/blob/main/app/services/patient_service.py): `app/services/patient_service.py`
- [Case-sheet workflow](https://github.com/heykvr/dental-client-management-backend/blob/main/app/services/case_sheet_service.py): `app/services/case_sheet_service.py`
- [Dashboard metrics](https://github.com/heykvr/dental-client-management-backend/blob/main/app/services/dashboard_service.py): `app/services/dashboard_service.py`

### Persistence

- [Patient repository](https://github.com/heykvr/dental-client-management-backend/blob/main/app/repositories/patient_repo.py): `app/repositories/patient_repo.py`
- [Case-sheet repository](https://github.com/heykvr/dental-client-management-backend/blob/main/app/repositories/case_sheet_repo.py): `app/repositories/case_sheet_repo.py`
- [ID counter](https://github.com/heykvr/dental-client-management-backend/blob/main/app/repositories/counter_repo.py): `app/repositories/counter_repo.py`

### AI features

- [Summary generation](https://github.com/heykvr/dental-client-management-backend/blob/main/app/services/summary_service.py): `app/services/summary_service.py`
- [Patient-grounded chat](https://github.com/heykvr/dental-client-management-backend/blob/main/app/services/chat_service.py): `app/services/chat_service.py`
- [AI client](https://github.com/heykvr/dental-client-management-backend/blob/main/app/services/ai_service.py): `app/services/ai_service.py`
- [Summary instructions](https://github.com/heykvr/dental-client-management-backend/blob/main/app/prompts/summary.txt): `app/prompts/summary.txt`
- [Chat instructions](https://github.com/heykvr/dental-client-management-backend/blob/main/app/prompts/chat_system.txt): `app/prompts/chat_system.txt`

### Runtime foundations

- [Application startup](https://github.com/heykvr/dental-client-management-backend/blob/main/app/main.py): `app/main.py`
- [Database connection](https://github.com/heykvr/dental-client-management-backend/blob/main/app/core/database.py): `app/core/database.py`
- [Request rate limits](https://github.com/heykvr/dental-client-management-backend/blob/main/app/core/rate_limit.py): `app/core/rate_limit.py`
- [Error responses](https://github.com/heykvr/dental-client-management-backend/blob/main/app/core/exceptions.py): `app/core/exceptions.py`

### Other components

- **Clinic staff**
- **MongoDB**
- **Google Gemini**

## Connections

- Clinic staff → REST routes: sends requests (evidence: `README.md`)
- REST routes → Dependency wiring: resolves services (evidence: `app/api/v1/patients.py`)
- Dependency wiring → Patient workflow: constructs (evidence: `app/api/deps.py`)
- Dependency wiring → Case-sheet workflow: constructs (evidence: `app/api/deps.py`)
- Dependency wiring → Dashboard metrics: constructs (evidence: `app/api/deps.py`)
- Dependency wiring → Summary generation: constructs (evidence: `app/api/deps.py`)
- Dependency wiring → Patient-grounded chat: constructs (evidence: `app/api/deps.py`)
- REST routes → Patient validation: validates patient data (evidence: `app/api/v1/patients.py`)
- REST routes → Case-sheet validation: validates case data (evidence: `app/api/v1/case_sheets.py`)
- Patient workflow → Patient repository: reads and writes (evidence: `app/services/patient_service.py`)
- Patient workflow → ID counter: allocates IDs (evidence: `app/services/patient_service.py`)
- Case-sheet workflow → Case-sheet repository: reads and saves (evidence: `app/services/case_sheet_service.py`)
- Dashboard metrics → Patient repository: aggregates patients (evidence: `app/services/dashboard_service.py`)
- Dashboard metrics → Case-sheet repository: counts statuses (evidence: `app/services/dashboard_service.py`)
- Summary generation → Case-sheet repository: loads and saves summary (evidence: `app/services/summary_service.py`)
- Summary generation → AI client: generates summary (evidence: `app/services/summary_service.py`)
- Summary generation → Summary instructions: loads instructions (evidence: `app/services/summary_service.py`)
- Patient-grounded chat → AI client: requests response (evidence: `app/services/chat_service.py`)
- Patient-grounded chat → Case-sheet workflow: uses case workflow (evidence: `app/services/chat_service.py`)
- Patient-grounded chat → Patient workflow: uses patient workflow (evidence: `app/services/chat_service.py`)
- Patient-grounded chat → Case-sheet repository: loads clinical record (evidence: `app/services/chat_service.py`)
- Patient-grounded chat → Chat instructions: uses instructions
- AI client → Google Gemini: calls provider (evidence: `app/services/ai_service.py`)
- Patient repository → MongoDB: queries patients (evidence: `app/repositories/patient_repo.py`)
- Case-sheet repository → MongoDB: queries embedded sheets (evidence: `app/repositories/case_sheet_repo.py`)
- ID counter → MongoDB: allocates sequence (evidence: `README.md`)
- Application startup → REST routes: mounts router (evidence: `app/main.py`)
- Application startup → Database connection: initializes database (evidence: `app/main.py`)
- REST routes → Request rate limits: applies limits (evidence: `app/api/v1/chat.py`)
- Application startup → Error responses: registers handlers (evidence: `app/main.py`)
