Appointment Booking - Domenicko/medical-booking-system GitHub Wiki

Appointment Booking

1. Module Overview

The Appointment Booking module allows patients to search for available doctors, select an available date and time, and create an appointment.

The module is responsible for:

  • Selecting a doctor.
  • Selecting an available date.
  • Selecting an available time slot.
  • Selecting the appointment type.
  • Providing optional information about the reason for the visit.
  • Validating the selected appointment.
  • Preventing conflicting or duplicate appointments.
  • Creating and managing appointment records.
  • Managing appointment statuses.

Only authenticated patients can create appointments.

2. Appointment Form Fields

Doctor

  • Type: ID / Reference
  • Required: Yes
  • Validation: The selected doctor must exist in the system and have an active account.
  • The doctor must be available for appointments.

The patient should select a doctor through the user interface. The doctor ID should be validated by the backend before creating the appointment.

Specialty

  • Type: ID / Reference
  • Required: Yes
  • Validation: The selected specialty must exist and must correspond to the selected doctor.

The specialty can be automatically determined from the selected doctor's profile rather than manually entered by the patient.

For example:

Selected Doctor:
Dr. John Smith

Specialty:
Cardiology

The system should ensure that the patient cannot manually assign an unrelated specialty to a doctor.

Appointment Date

  • Type: Date

  • Required: Yes

  • Validation:

    • The date must use a valid date format.
    • The selected date must not be in the past.
    • The doctor must have available working hours on the selected date.
    • The doctor must not be unavailable on the selected date.

Appointment Time

  • Type: Time

  • Required: Yes

  • Validation:

    • The selected time must be within the doctor's available working hours.
    • The selected time slot must still be available.
    • The time must not conflict with another appointment.
    • The appointment duration must fit within the doctor's working schedule.

The available time slots should preferably be provided by the system rather than allowing the patient to enter an arbitrary time manually.

Example:

09:00 — Available
09:30 — Available
10:00 — Booked
10:30 — Available
11:00 — Available

Appointment Type

  • Type: Enum

  • Required: Yes

  • Allowed values:

    • in-person
    • online

The selected appointment type must be supported by the selected doctor.

For example, if a doctor does not provide online consultations, the online option should not be available.

Reason for Visit

  • Type: String
  • Required: No
  • Validation: If provided, the text should have a reasonable maximum length, for example 500 characters.

This field allows the patient to provide additional information about the purpose of the appointment.

Example:

Reason for visit:
"I have been experiencing headaches for the past two weeks."

The reason for the visit should not be used as a replacement for a medical diagnosis.

Patient

  • Type: ID / Reference
  • Required: Automatically assigned
  • Validation: The patient must be authenticated.

The patient should not manually enter their own patient ID.

The system should obtain the patient identity from the authenticated session.

Example:

Authenticated User
       ↓
Current User ID
       ↓
Patient ID
       ↓
Create Appointment

This prevents a patient from creating an appointment on behalf of another user by simply changing an ID.

3. Appointment Creation Business Logic

The appointment creation process follows these steps:

  1. The patient must be authenticated.
  2. The patient selects a doctor.
  3. The system verifies that the doctor exists and has an active account.
  4. The system determines the doctor's specialty.
  5. The patient selects an available date.
  6. The system checks whether the doctor works on the selected date.
  7. The system displays available time slots.
  8. The patient selects an available time.
  9. The patient selects the appointment type.
  10. The patient may optionally provide a reason for the visit.
  11. The system validates all submitted information.
  12. The system checks whether the selected time slot is still available.
  13. The system checks for conflicting appointments.
  14. If all validation rules pass, a new appointment is created.
  15. The appointment receives an initial status.
  16. The appointment is associated with the authenticated patient and selected doctor.

4. Appointment Validation Rules

Doctor Validation

The selected doctor must:

  • Exist in the database.
  • Have an active account.
  • Be available for appointments.
  • Support the selected appointment type.

Date Validation

The appointment date:

  • Must be valid.
  • Must not be in the past.
  • Must fall within the doctor's available schedule.
  • Must not fall on a date when the doctor is unavailable.

Time Validation

The selected time:

  • Must be a valid time.
  • Must be within the doctor's working hours.
  • Must correspond to an available appointment slot.
  • Must not overlap with another appointment.

Appointment Conflict Validation

Before creating an appointment, the system must check whether:

  • The doctor already has an appointment at the selected time.
  • The patient already has another appointment at the same time.
  • The selected time slot has become unavailable since it was displayed to the patient.

If a conflict exists, the appointment must not be created.

The user should receive a clear message such as:

The selected time slot is no longer available.
Please choose another available time.

5. Double Booking Prevention

Preventing double bookings is an important business rule of the Appointment Booking module.

A time slot must not be assigned to two different appointments for the same doctor.

For example:

Doctor: Dr. John Smith
Date: 2026-10-15
Time: 10:00

Patient A → Booked
Patient B → Not allowed

If two patients attempt to book the same time slot at approximately the same time, the backend must perform the final availability check before creating the appointment.

The availability check must therefore be performed on the backend and must not rely only on frontend validation.

6. Patient Appointment Conflict

A patient should also not be able to have two appointments at the same time.

For example:

Patient: Jane Doe

10:00 — Dr. Smith
10:00 — Dr. Brown → Not allowed

The system should reject the second appointment because the patient already has an appointment during that time.

7. Appointment Statuses

Appointments can have different statuses during their lifecycle.

The initial status can be:

pending

After confirmation:

confirmed

After the appointment has taken place:

completed

If the appointment is cancelled:

cancelled

The general lifecycle is:

Pending
   ↓
Confirmed
   ↓
Completed

An appointment can also be cancelled before completion:

Pending ─────→ Cancelled
   │
   ↓
Confirmed ───→ Cancelled

8. Appointment Status Rules

Pending

The appointment has been created but has not yet been confirmed.

Depending on the final system design, this status may be used when doctor confirmation is required.

Confirmed

The appointment has been accepted and the selected time is reserved.

Completed

The appointment has taken place successfully.

Cancelled

The appointment has been cancelled by the patient, doctor, or administrator according to the system's cancellation rules.

9. Appointment Cancellation

Patients should be able to cancel their own appointments according to the system's cancellation policy.

Before allowing cancellation, the system should verify:

  • The appointment belongs to the authenticated patient.
  • The appointment exists.
  • The appointment has not already been completed.
  • The appointment has not already been cancelled.
  • The cancellation is permitted according to the system's time restrictions.

For example, the system may require cancellation at least a certain number of hours before the appointment.

The exact cancellation period should be defined as part of the final business requirements.

10. Doctor Appointment Management

Doctors can view appointments associated with their account.

A doctor should be able to:

  • View upcoming appointments.
  • View appointment dates and times.
  • View the associated patient.
  • View the appointment type.
  • View the patient's reason for the visit, if provided.
  • Confirm appointments when confirmation is required.
  • Cancel appointments according to the system rules.
  • Mark completed appointments as completed.

Doctors must not be able to access appointments belonging to other doctors unless they have appropriate administrative permissions.

11. Patient Appointment Management

Patients can view and manage their own appointments.

A patient should be able to:

  • View upcoming appointments.
  • View past appointments.
  • View appointment details.
  • View the selected doctor.
  • View the appointment date and time.
  • View the appointment type.
  • Cancel eligible appointments.

A patient must not be able to view or modify another patient's appointments.

12. Appointment Data

An appointment record should contain information similar to the following:

Appointment
│
├── id
├── patientId
├── doctorId
├── specialtyId
├── appointmentDate
├── appointmentTime
├── appointmentType
├── reason
├── status
├── createdAt
└── updatedAt

Required appointment data

The following information is required to create an appointment:

  • patientId
  • doctorId
  • specialtyId
  • appointmentDate
  • appointmentTime
  • appointmentType
  • status

Optional appointment data

The following information is optional:

  • reason

The patientId should be obtained from the authenticated user rather than being manually supplied by the patient.

The status should be assigned by the system rather than manually selected by the patient.

13. Appointment Type Rules

The system supports two appointment types:

In-person

The patient visits the doctor's clinic or specified medical facility.

Online

The consultation is performed remotely.

The selected doctor must support the selected appointment type.

If online appointments are supported, the system may later generate or associate an online meeting link with the appointment.

14. Error Handling

The system should provide clear error messages when an appointment cannot be created.

Possible errors include:

  • User is not authenticated.
  • Selected doctor does not exist.
  • Doctor account is not active.
  • Selected specialty does not match the doctor.
  • Selected date is in the past.
  • Doctor is not available on the selected date.
  • Selected time is outside the doctor's working hours.
  • Selected time slot is already booked.
  • Patient already has an appointment at the selected time.
  • Selected appointment type is not supported by the doctor.
  • Required appointment information is missing.
  • Appointment has already been cancelled or completed.

15. Appointment Booking Flow

The overall booking process can be represented as:

Patient Login
     ↓
Search / Select Doctor
     ↓
View Doctor Availability
     ↓
Select Date
     ↓
Select Available Time
     ↓
Select Appointment Type
     ↓
Add Optional Reason
     ↓
Validate Booking
     ↓
Check Doctor Availability
     ↓
Check Patient Conflicts
     ↓
Create Appointment
     ↓
Pending / Confirmed

16. Security and Access Rules

The Appointment Booking module must enforce role-based access control.

  • Only authenticated patients can create appointments.
  • Patients can only view and manage their own appointments.
  • Doctors can only manage appointments associated with their account.
  • Admins can access appointment information according to their administrative permissions.
  • The backend must validate ownership before allowing an appointment to be viewed, modified, or cancelled.
  • Appointment IDs must not be sufficient on their own to grant access to appointment data.
  • Final availability and conflict checks must always be performed on the backend.

#17 Cancellation Rules

Patients can cancel their appointments at least 24 hours before the scheduled appointment time.

For example:

Appointment: October 10, 15:00 Cancellation deadline: October 9, 15:00

If the patient attempts to cancel the appointment less than 24 hours before the scheduled time, the normal cancellation action should not be allowed.

The system should display an appropriate message explaining that appointments must be cancelled at least 24 hours in advance.

Cancellation Logic

When a patient attempts to cancel an appointment, the system should:

Verify that the appointment belongs to the authenticated patient. Verify that the appointment can still be cancelled. Calculate the time remaining until the appointment. Check whether at least 24 hours remain. If 24 hours or more remain, allow the cancellation. Change the appointment status to cancelled. Make the appointment slot available again. If less than 24 hours remain, reject the normal cancellation request.

The 24-hour rule is intended to give the medical provider enough notice to make the appointment slot available to another patient. Similar 24-hour cancellation requirements are used by healthcare providers and clinics.

Exceptions

The system may allow exceptions for emergencies or other exceptional circumstances. The exact exception-handling process can be defined later as a business requirement.

18. Expected Module Outcome

After successful implementation of the Appointment Booking module:

  • Patients can find available doctors.
  • Patients can view available appointment slots.
  • Patients can create appointments.
  • The system prevents invalid dates and times.
  • The system prevents doctor double booking.
  • The system prevents patient scheduling conflicts.
  • Appointments are associated with the correct patient and doctor.
  • Appointment statuses can change according to the defined business rules.
  • Patients can manage their own appointments.
  • Doctors can manage their associated appointments.
  • Unauthorized users cannot access appointment data.