# kelsengile/appointmed architecture

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

- Interactive diagram: https://gitdiagram.com/kelsengile/appointmed
- Repository: https://github.com/kelsengile/appointmed

## Overview

AppointMed is a clinic appointment and management system: patients submit public booking requests, while role-authorized staff review requests and manage visits through examination and payment. The shared FastAPI backend serves a React portal and persists clinic records in MySQL. The graph preserves documented clinical and administrative capabilities; several unsampled service relationships are shown as unverified rather than inferred from names. Connections between sampled modules use the source index or excerpts, and documented product flows cite the README.

Main entry points: [`source/backend/services/appointment_service.py`](https://github.com/kelsengile/appointmed/blob/main/source/backend/services/appointment_service.py) (Visit lifecycle), [`source/backend/repositories`](https://github.com/kelsengile/appointmed/tree/main/source/backend/repositories) (Repositories), [`source/backend/routes/staff_routes.py`](https://github.com/kelsengile/appointmed/blob/main/source/backend/routes/staff_routes.py) (Staff routes), [`source/backend/routes/admin_routes.py`](https://github.com/kelsengile/appointmed/blob/main/source/backend/routes/admin_routes.py) (Admin routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["React application<br/>[app.tsx]"]
  node_publicpages["Public pages"]
  node_staffportal["Staff portal"]
  node_adminpages["Admin pages"]
  node_authcontext["Session context<br/>[AuthContext.tsx]"]
  node_frontendapi["API client<br/>[client.ts]"]
end

subgraph group_api["API and access"]
  node_backend["FastAPI app<br/>[main.py]"]
  node_publicroutes["Public routes<br/>[public_routes.py]"]
  node_staffroutes["Staff routes<br/>[staff_routes.py]"]
  node_adminroutes["Admin routes<br/>[admin_routes.py]"]
  node_auth["Authentication<br/>[auth_service.py]"]
  node_security["Access control<br/>[security.py]"]
end

subgraph group_care["Clinic workflows"]
  node_booking["Booking and scheduling<br/>[booking_service.py]"]
  node_appointments["Visit lifecycle"]
  node_queue["Check-in queue<br/>[waiting_queue.py]"]
  node_clinical["Exams and billing<br/>[billing_service.py]"]
  node_patientrecords["Patient records<br/>[patient_service.py]"]
end

subgraph group_admin["Administration"]
  node_adminservice["Admin operations<br/>[admin_service.py]"]
  node_reports["Reports and dashboard"]
  node_dbtools["Backup and database tools"]
end

subgraph group_storage["Data layer"]
  node_repositories["Repositories"]
  node_domain["Roles and status model<br/>[domain.py]"]
  node_mysql[("Clinic database<br/>[database.py]")]
end

node_patient(("Patient"))
node_staff(("Clinic staff"))

node_patient -->|"uses"| node_publicpages
node_staff -->|"uses"| node_staffportal
node_publicpages -->|"routes through"| node_webapp
node_staffportal -->|"routes through"| node_webapp
node_adminpages -->|"routes through"| node_webapp
node_webapp -->|"uses"| node_authcontext
node_authcontext -->|"calls"| node_frontendapi
node_publicpages -.->|"requests data"| node_frontendapi
node_staffportal -.->|"requests data"| node_frontendapi
node_adminpages -->|"requests data"| node_frontendapi
node_frontendapi -->|"HTTP requests"| node_backend
node_backend -->|"registers"| node_publicroutes
node_backend -->|"registers"| node_staffroutes
node_backend -->|"registers"| node_adminroutes
node_publicroutes -->|"calls"| node_booking
node_publicroutes -->|"calls"| node_patientrecords
node_publicroutes -.->|"handles requests"| node_appointments
node_staffroutes -->|"calls"| node_appointments
node_staffroutes -->|"calls"| node_reports
node_staffroutes -.->|"calls"| node_clinical
node_adminroutes -->|"calls"| node_adminservice
node_adminroutes -->|"calls"| node_reports
node_adminroutes -.->|"calls"| node_dbtools
node_staffroutes -->|"checks features"| node_security
node_adminroutes -->|"checks features"| node_security
node_auth -->|"creates tokens"| node_security
node_appointments -.->|"uses"| node_queue
node_booking -.->|"reads and writes"| node_repositories
node_appointments -->|"reads and writes"| node_repositories
node_auth -->|"reads and writes"| node_repositories
node_adminservice -.->|"reads and writes"| node_repositories
node_reports -->|"queries"| node_repositories
node_dbtools -->|"uses"| node_repositories
node_repositories -->|"executes queries"| node_mysql
node_appointments -.->|"enforces visit states"| node_domain
node_security -->|"checks role access"| node_domain
node_patient -->|"requests appointment"| node_booking
node_booking -->|"review and schedule"| node_appointments
node_appointments -->|"advances visit"| node_clinical
node_clinical -->|"records visit"| node_patientrecords
node_staff -->|"administers clinic"| node_adminpages

click node_webapp "https://github.com/kelsengile/appointmed/blob/main/source/frontend/src/app.tsx"
click node_publicpages "https://github.com/kelsengile/appointmed/tree/main/source/frontend/src/pages"
click node_staffportal "https://github.com/kelsengile/appointmed/tree/main/source/frontend/src/pages/staff"
click node_adminpages "https://github.com/kelsengile/appointmed/tree/main/source/frontend/src/pages/admin"
click node_authcontext "https://github.com/kelsengile/appointmed/blob/main/source/frontend/src/context/AuthContext.tsx"
click node_frontendapi "https://github.com/kelsengile/appointmed/blob/main/source/frontend/src/api/client.ts"
click node_backend "https://github.com/kelsengile/appointmed/blob/main/source/main.py"
click node_publicroutes "https://github.com/kelsengile/appointmed/blob/main/source/backend/routes/public_routes.py"
click node_staffroutes "https://github.com/kelsengile/appointmed/blob/main/source/backend/routes/staff_routes.py"
click node_adminroutes "https://github.com/kelsengile/appointmed/blob/main/source/backend/routes/admin_routes.py"
click node_auth "https://github.com/kelsengile/appointmed/blob/main/source/backend/services/auth_service.py"
click node_security "https://github.com/kelsengile/appointmed/blob/main/source/backend/core/security.py"
click node_booking "https://github.com/kelsengile/appointmed/blob/main/source/backend/services/booking_service.py"
click node_appointments "https://github.com/kelsengile/appointmed/blob/main/source/backend/services/appointment_service.py"
click node_queue "https://github.com/kelsengile/appointmed/blob/main/source/backend/services/waiting_queue.py"
click node_clinical "https://github.com/kelsengile/appointmed/blob/main/source/backend/services/billing_service.py"
click node_patientrecords "https://github.com/kelsengile/appointmed/blob/main/source/backend/services/patient_service.py"
click node_adminservice "https://github.com/kelsengile/appointmed/blob/main/source/backend/services/admin_service.py"
click node_reports "https://github.com/kelsengile/appointmed/blob/main/source/backend/services/dashboard_service.py"
click node_dbtools "https://github.com/kelsengile/appointmed/blob/main/source/backend/services/database_service.py"
click node_repositories "https://github.com/kelsengile/appointmed/tree/main/source/backend/repositories"
click node_domain "https://github.com/kelsengile/appointmed/blob/main/source/backend/models/domain.py"
click node_mysql "https://github.com/kelsengile/appointmed/blob/main/source/backend/core/database.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_webapp,node_publicpages,node_staffportal,node_adminpages,node_authcontext,node_frontendapi toneBlue
class node_backend,node_publicroutes,node_staffroutes,node_adminroutes,node_auth,node_security toneAmber
class node_booking,node_appointments,node_queue,node_clinical,node_patientrecords toneMint
class node_adminservice,node_reports,node_dbtools toneRose
class node_repositories,node_domain,node_mysql,node_patient,node_staff toneIndigo
```

## Components

### Web experience

- [React application](https://github.com/kelsengile/appointmed/blob/main/source/frontend/src/app.tsx): `source/frontend/src/app.tsx`
- [Public pages](https://github.com/kelsengile/appointmed/tree/main/source/frontend/src/pages): `source/frontend/src/pages`
- [Staff portal](https://github.com/kelsengile/appointmed/tree/main/source/frontend/src/pages/staff): `source/frontend/src/pages/staff`
- [Admin pages](https://github.com/kelsengile/appointmed/tree/main/source/frontend/src/pages/admin): `source/frontend/src/pages/admin`
- [Session context](https://github.com/kelsengile/appointmed/blob/main/source/frontend/src/context/AuthContext.tsx): `source/frontend/src/context/AuthContext.tsx`
- [API client](https://github.com/kelsengile/appointmed/blob/main/source/frontend/src/api/client.ts): `source/frontend/src/api/client.ts`

### API and access

- [FastAPI app](https://github.com/kelsengile/appointmed/blob/main/source/main.py): `source/main.py`
- [Public routes](https://github.com/kelsengile/appointmed/blob/main/source/backend/routes/public_routes.py): `source/backend/routes/public_routes.py`
- [Staff routes](https://github.com/kelsengile/appointmed/blob/main/source/backend/routes/staff_routes.py): `source/backend/routes/staff_routes.py`
- [Admin routes](https://github.com/kelsengile/appointmed/blob/main/source/backend/routes/admin_routes.py): `source/backend/routes/admin_routes.py`
- [Authentication](https://github.com/kelsengile/appointmed/blob/main/source/backend/services/auth_service.py): `source/backend/services/auth_service.py`
- [Access control](https://github.com/kelsengile/appointmed/blob/main/source/backend/core/security.py): `source/backend/core/security.py`

### Clinic workflows

- [Booking and scheduling](https://github.com/kelsengile/appointmed/blob/main/source/backend/services/booking_service.py): `source/backend/services/booking_service.py`
- [Visit lifecycle](https://github.com/kelsengile/appointmed/blob/main/source/backend/services/appointment_service.py): `source/backend/services/appointment_service.py`
- [Check-in queue](https://github.com/kelsengile/appointmed/blob/main/source/backend/services/waiting_queue.py): `source/backend/services/waiting_queue.py`
- [Exams and billing](https://github.com/kelsengile/appointmed/blob/main/source/backend/services/billing_service.py): `source/backend/services/billing_service.py`
- [Patient records](https://github.com/kelsengile/appointmed/blob/main/source/backend/services/patient_service.py): `source/backend/services/patient_service.py`

### Administration

- [Admin operations](https://github.com/kelsengile/appointmed/blob/main/source/backend/services/admin_service.py): `source/backend/services/admin_service.py`
- [Reports and dashboard](https://github.com/kelsengile/appointmed/blob/main/source/backend/services/dashboard_service.py): `source/backend/services/dashboard_service.py`
- [Backup and database tools](https://github.com/kelsengile/appointmed/blob/main/source/backend/services/database_service.py): `source/backend/services/database_service.py`

### Data layer

- [Repositories](https://github.com/kelsengile/appointmed/tree/main/source/backend/repositories): `source/backend/repositories`
- [Roles and status model](https://github.com/kelsengile/appointmed/blob/main/source/backend/models/domain.py): `source/backend/models/domain.py`
- [Clinic database](https://github.com/kelsengile/appointmed/blob/main/source/backend/core/database.py): `source/backend/core/database.py`

### Other components

- **Patient**
- **Clinic staff**

## Connections

- Patient → Public pages: uses (evidence: `README.md`)
- Clinic staff → Staff portal: uses (evidence: `README.md`)
- Public pages → React application: routes through (evidence: `source/frontend/src/app.tsx`)
- Staff portal → React application: routes through (evidence: `source/frontend/src/app.tsx`)
- Admin pages → React application: routes through (evidence: `source/frontend/src/app.tsx`)
- React application → Session context: uses (evidence: `source/frontend/src/app.tsx`)
- Session context → API client: calls (evidence: `source/frontend/src/context/AuthContext.tsx`)
- Public pages → API client: requests data
- Staff portal → API client: requests data
- Admin pages → API client: requests data (evidence: `source/frontend/src/pages/admin/DatabasePage.tsx`)
- API client → FastAPI app: HTTP requests (evidence: `README.md`)
- FastAPI app → Public routes: registers (evidence: `source/main.py`)
- FastAPI app → Staff routes: registers (evidence: `source/main.py`)
- FastAPI app → Admin routes: registers (evidence: `source/main.py`)
- Public routes → Booking and scheduling: calls (evidence: `source/backend/routes/public_routes.py`)
- Public routes → Patient records: calls (evidence: `source/backend/routes/public_routes.py`)
- Public routes → Visit lifecycle: handles requests
- Staff routes → Visit lifecycle: calls (evidence: `source/backend/routes/staff_routes.py`)
- Staff routes → Reports and dashboard: calls (evidence: `source/backend/routes/staff_routes.py`)
- Staff routes → Exams and billing: calls (evidence: `source/backend/routes/staff_routes.py`)
- Admin routes → Admin operations: calls (evidence: `source/backend/routes/admin_routes.py`)
- Admin routes → Reports and dashboard: calls (evidence: `source/backend/routes/admin_routes.py`)
- Admin routes → Backup and database tools: calls
- Staff routes → Access control: checks features (evidence: `source/backend/routes/staff_routes.py`)
- Admin routes → Access control: checks features (evidence: `source/backend/routes/admin_routes.py`)
- Authentication → Access control: creates tokens (evidence: `source/backend/services/auth_service.py`)
- Visit lifecycle → Check-in queue: uses
- Booking and scheduling → Repositories: reads and writes
- Visit lifecycle → Repositories: reads and writes (evidence: `source/backend/services/appointment_service.py`)
- Authentication → Repositories: reads and writes (evidence: `source/backend/services/auth_service.py`)
- Admin operations → Repositories: reads and writes (evidence: `source/backend/services/admin_service.py`)
- Reports and dashboard → Repositories: queries (evidence: `source/backend/services/dashboard_service.py`)
- Backup and database tools → Repositories: uses (evidence: `source/backend/services/database_service.py`)
- Repositories → Clinic database: executes queries (evidence: `source/backend/repositories/appointment_repository.py`)
- Visit lifecycle → Roles and status model: enforces visit states (evidence: `source/backend/services/appointment_service.py`)
- Access control → Roles and status model: checks role access (evidence: `source/backend/core/security.py`)
- Patient → Booking and scheduling: requests appointment (evidence: `README.md`)
- Booking and scheduling → Visit lifecycle: review and schedule (evidence: `README.md`)
- Visit lifecycle → Exams and billing: advances visit (evidence: `README.md`)
- Exams and billing → Patient records: records visit (evidence: `README.md`)
- Clinic staff → Admin pages: administers clinic (evidence: `README.md`)