# aswinram312004-droid/doctor-appointment-booking-system architecture

> Architecture diagram of the GitHub repository aswinram312004-droid/doctor-appointment-booking-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aswinram312004-droid/doctor-appointment-booking-system
- Repository: https://github.com/aswinram312004-droid/doctor-appointment-booking-system

## Overview

#### Purpose and topology
MediCare is a local full-stack doctor appointment system. A React single-page frontend lets patients browse doctors, authenticate, and book/manage appointments; a Flask API persists users, doctors, schedules, and appointments in PostgreSQL. Administrators manage doctor records and schedules.

#### Application entry points
- Flask starts from `backend/app.py`, which composes the API application and route modules.
- React boots from `frontend/src/main.jsx` and renders the top-level application in `frontend/src/App.jsx`.
- Backend environment and dependencies are defined in `backend/.env` and `backend/requirements.txt`; the frontend is a Vite/npm project via `frontend/package.json` and `frontend/vite.config.js`.

#### API and authentication boundary
The backend exposes the `/api` HTTP boundary for the frontend. Authentication routes in `backend/auth.py` register users and issue JWTs; protected appointment and administrative actions depend on those tokens. Flask configuration, request handling, and route registration are centralized in `backend/app.py`.

#### Persistence and domain model
PostgreSQL is the system of record, accessed through `backend/db.py`. The relational schema—including the database-enforced appointment-conflict constraint described by the README—is established in `backend/schema.py`. Operational bootstrap/validation scripts, `backend/setup.py`, `backend/create_admin.py`, and `backend/check_db.py`, support initial schema and admin/database setup rather than the request path.

#### Doctor catalog and administration
`backend/doctor.py` owns doctor-facing API behavior, including doctor listing/detail retrieval and likely admin management operations. The UI presents the catalog and detail views through `frontend/src/components/pages/DoctorsPage.jsx`, `frontend/src/components/sections/Doctors.jsx`, and `frontend/src/components/sections/DoctorDetails.jsx`; admin doctor controls are represented by `frontend/src/components/sections/AdminDoctors.jsx`.

#### Appointment lifecycle
`backend/appointments.py` handles the protected appointment workflow: retrieve a user’s appointments, create bookings, and cancel bookings. Its persistence boundary is the PostgreSQL layer in `backend/db.py`/`backend/schema.py`, where schedule conflicts must be rejected. The patient-facing booking surface is `frontend/src/components/sections/AppointmentPage.jsx`, with doctor selection/details feeding into it from `frontend/src/components/sections/DoctorDetails.jsx`.

#### Frontend composition and state boundaries
`frontend/src/App.jsx` coordinates page-level navigation and shared application composition. Authentication UI is isolated in `frontend/src/components/sections/LoginPage.jsx` and `frontend/src/components/sections/SignupPage.jsx`; reusable site framing is in `frontend/src/components/layout/Navbar.jsx` and `frontend/src/components/layout/Footer.jsx`. Static or display-oriented doctor data also exists at `frontend/src/data/doctors.js`, which should be distinguished from the API-backed doctor catalog when evolving data flow.

#### Runtime and external dependencies
The material runtimes are browser-based React/Vite, Python Flask, and PostgreSQL. The only identified external service boundary is the local PostgreSQL instance configured by `DATABASE_URL`; security relies on `SECRET_KEY` and `JWT_SECRET_KEY` supplied through `backend/.env`.

Main entry points: [`frontend/src/App.jsx`](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/App.jsx) (Application shell), [`frontend/src/components/pages/DoctorsPage.jsx`](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/components/pages/DoctorsPage.jsx) (Doctor catalog), [`backend/doctor.py`](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/doctor.py) (Doctor API), [`backend/app.py`](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/app.py) (Flask application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_react_boot["React bootstrap<br/>Vite entry<br/>[main.jsx]"]
  node_spa_app["Application shell<br/>React composition<br/>[App.jsx]"]
  node_site_chrome["Site framing<br/>layout components<br/>[Navbar.jsx]"]
  node_auth_ui["Authentication UI<br/>login and signup<br/>[LoginPage.jsx]"]
  node_catalog_ui["Doctor catalog<br/>catalog views<br/>[DoctorsPage.jsx]"]
  node_doctor_details_ui["Doctor details<br/>detail and booking handoff<br/>[DoctorDetails.jsx]"]
  node_booking_ui["Appointment UI<br/>patient booking"]
  node_admin_doctors_ui["Admin doctor controls<br/>administration UI<br/>[AdminDoctors.jsx]"]
  node_static_doctors["Static doctor data<br/>display data<br/>[doctors.js]"]
end

subgraph group_backend["Flask API"]
  node_flask_app["Flask application<br/>API composition<br/>[app.py]"]
  node_auth_api["Authentication API<br/>JWT routes<br/>[auth.py]"]
  node_doctor_api["Doctor API<br/>catalog and admin routes<br/>[doctor.py]"]
  node_appointments_api["Appointment API<br/>protected booking routes<br/>[appointments.py]"]
  node_database_access["Database access<br/>PostgreSQL adapter<br/>[db.py]"]
  node_bootstrap["Database bootstrap<br/>operational scripts<br/>[setup.py]"]
end

subgraph group_data["Persistence"]
  node_schema["Relational schema<br/>schema and constraints<br/>[schema.py]"]
  node_postgres[("PostgreSQL<br/>local database")]
end

node_react_boot -->|"renders"| node_spa_app
node_spa_app -->|"composes"| node_site_chrome
node_spa_app -->|"shows"| node_auth_ui
node_spa_app -->|"shows"| node_catalog_ui
node_spa_app -->|"shows"| node_booking_ui
node_spa_app -->|"shows"| node_admin_doctors_ui
node_catalog_ui -->|"opens"| node_doctor_details_ui
node_doctor_details_ui -->|"selects doctor"| node_booking_ui
node_static_doctors -.->|"display source"| node_catalog_ui
node_auth_ui -->|"/api authentication"| node_auth_api
node_catalog_ui -->|"/api catalog"| node_doctor_api
node_booking_ui -->|"/api bookings"| node_appointments_api
node_admin_doctors_ui -->|"/api administration"| node_doctor_api
node_flask_app -->|"registers"| node_auth_api
node_flask_app -->|"registers"| node_doctor_api
node_flask_app -->|"registers"| node_appointments_api
node_doctor_api -->|"reads and manages"| node_database_access
node_appointments_api -->|"persists bookings"| node_database_access
node_database_access -->|"queries"| node_postgres
node_schema -->|"defines"| node_postgres
node_bootstrap -.->|"initializes"| node_schema

click node_react_boot "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/main.jsx"
click node_spa_app "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/App.jsx"
click node_site_chrome "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/components/layout/Navbar.jsx"
click node_auth_ui "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/components/sections/LoginPage.jsx"
click node_catalog_ui "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/components/pages/DoctorsPage.jsx"
click node_doctor_details_ui "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/components/sections/DoctorDetails.jsx"
click node_booking_ui "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/components/sections/AppointmentPage.jsx"
click node_admin_doctors_ui "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/components/sections/AdminDoctors.jsx"
click node_static_doctors "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/data/doctors.js"
click node_flask_app "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/app.py"
click node_auth_api "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/auth.py"
click node_doctor_api "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/doctor.py"
click node_appointments_api "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/appointments.py"
click node_database_access "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/db.py"
click node_schema "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/schema.py"
click node_bootstrap "https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/setup.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_react_boot,node_spa_app,node_site_chrome,node_auth_ui,node_catalog_ui,node_doctor_details_ui,node_booking_ui,node_admin_doctors_ui,node_static_doctors toneBlue
class node_flask_app,node_auth_api,node_doctor_api,node_appointments_api,node_database_access,node_bootstrap toneAmber
class node_schema,node_postgres toneMint
```

## Components

### React frontend

Browser SPA built with Vite.

- [React bootstrap](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/main.jsx): Vite entry · `frontend/src/main.jsx`
- [Application shell](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/App.jsx): React composition · Coordinates navigation and shared UI state. · `frontend/src/App.jsx`
- [Site framing](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/components/layout/Navbar.jsx): layout components · `frontend/src/components/layout/Navbar.jsx`
- [Authentication UI](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/components/sections/LoginPage.jsx): login and signup · `frontend/src/components/sections/LoginPage.jsx`
- [Doctor catalog](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/components/pages/DoctorsPage.jsx): catalog views · `frontend/src/components/pages/DoctorsPage.jsx`
- [Doctor details](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/components/sections/DoctorDetails.jsx): detail and booking handoff · `frontend/src/components/sections/DoctorDetails.jsx`
- [Appointment UI](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/components/sections/AppointmentPage.jsx): patient booking · `frontend/src/components/sections/AppointmentPage.jsx`
- [Admin doctor controls](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/components/sections/AdminDoctors.jsx): administration UI · `frontend/src/components/sections/AdminDoctors.jsx`
- [Static doctor data](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/frontend/src/data/doctors.js): display data · Separate from the API-backed catalog. · `frontend/src/data/doctors.js`

### Flask API

HTTP API and domain workflows.

- [Flask application](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/app.py): API composition · Registers routes, configuration, and request handling. · `backend/app.py`
- [Authentication API](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/auth.py): JWT routes · Registers users and issues JWTs. · `backend/auth.py`
- [Doctor API](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/doctor.py): catalog and admin routes · `backend/doctor.py`
- [Appointment API](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/appointments.py): protected booking routes · Lists, creates, and cancels patient appointments. · `backend/appointments.py`
- [Database access](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/db.py): PostgreSQL adapter · `backend/db.py`
- [Database bootstrap](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/setup.py): operational scripts · Initial schema, admin, and database validation setup. · `backend/setup.py`

### Persistence

Local PostgreSQL system of record.

- [Relational schema](https://github.com/aswinram312004-droid/doctor-appointment-booking-system/blob/main/backend/schema.py): schema and constraints · Enforces appointment-conflict rejection. · `backend/schema.py`
- **PostgreSQL**: local database · Configured through DATABASE_URL.

## Connections

- React bootstrap → Application shell: renders
- Application shell → Site framing: composes
- Application shell → Authentication UI: shows
- Application shell → Doctor catalog: shows
- Application shell → Appointment UI: shows
- Application shell → Admin doctor controls: shows
- Doctor catalog → Doctor details: opens
- Doctor details → Appointment UI: selects doctor
- Static doctor data → Doctor catalog: display source
- Authentication UI → Authentication API: /api authentication
- Doctor catalog → Doctor API: /api catalog
- Appointment UI → Appointment API: /api bookings · JWT-protected actions.
- Admin doctor controls → Doctor API: /api administration · JWT-protected actions.
- Flask application → Authentication API: registers
- Flask application → Doctor API: registers
- Flask application → Appointment API: registers
- Doctor API → Database access: reads and manages
- Appointment API → Database access: persists bookings
- Database access → PostgreSQL: queries
- Relational schema → PostgreSQL: defines
- Database bootstrap → Relational schema: initializes