๐Ÿ“ System Design Document

Physiotherapy Clinic
Appointment System

A comprehensive Laravel-based platform for patient booking, payment processing, WhatsApp notifications, and clinic administration.

10
System Flowcharts
18+
Core Features
4
User Roles
18
WhatsApp Triggers
01

System Architecture Overview

High-level view of all system modules and how they connect.

graph TB subgraph PUBLIC["๐ŸŒ Public Facing"] LP["๐Ÿ  Landing Page"] BA["๐Ÿ“… Book Appointment"] AUTH["๐Ÿ” WhatsApp OTP / SMS Auth"] PAY["๐Ÿ’ณ Razorpay Payment"] DF["๐Ÿ“‹ Detailed Form + Uploads"] end subgraph PATIENT["๐Ÿ‘ค Patient Portal"] PD["Patient Dashboard"] AH["Appointment History"] UP["Upload Records"] PF["Profile Management"] end subgraph ADMIN["๐Ÿ–ฅ๏ธ Admin Panel"] AD["Admin Dashboard"] LM["Lead Management"] PM["Patient Management"] SM["Schedule Management"] FM["Fee Management"] WA["WhatsApp API"] RP["Reports & Analytics"] end subgraph SERVICES["โš™๏ธ Background Services"] NS["๐Ÿ”” Notification Service"] CS["โฒ๏ธ Cron Scheduler"] PS["๐Ÿ’ณ Payment Webhooks"] end LP --> BA --> AUTH --> PAY --> DF DF --> PD PD --> AH PD --> UP PD --> PF AD --> LM AD --> PM AD --> SM AD --> FM AD --> WA AD --> RP CS --> NS PS --> NS
02

Patient Booking Flow

Complete journey from landing page to confirmed appointment.

flowchart TD A["๐Ÿ  Landing Page"] --> B{"Visitor Action"} B -->|"Book Appointment"| C["๐Ÿ“… Select Consultation Type"] B -->|"Learn More"| A1["โ„น๏ธ Services / About / Contact"] A1 --> B C -->|"Online - Video"| D["๐Ÿ“… Select Date"] C -->|"Offline - In-Clinic"| D D --> D1["โฐ Select Available Time Slot"] D1 --> E["๐Ÿ“ฑ Enter Mobile Number"] E --> F{"Existing Patient?"} F -->|"Yes"| G["Send OTP via WhatsApp / SMS"] F -->|"No - New Lead Created"| G G --> H["โœ… Verify OTP"] H -->|"OTP Valid"| I["๐Ÿ“ Basic Details Form"] H -->|"OTP Invalid / Expired"| H1["๐Ÿ”„ Resend OTP - max 3 attempts"] H1 --> H H -->|"Max Attempts Exceeded"| H2["โŒ Blocked - Try After 30 min"] I --> I1["Enter: Name, Age, Gender,\nBrief Complaint, Preferred Language"] I1 --> J["๐Ÿ’ณ Razorpay Payment Page"] J --> K{"Payment Status"} K -->|"โœ… Success"| L["๐Ÿ“‹ Detailed Health Form"] K -->|"โŒ Failed"| K1["๐Ÿ”„ Retry Payment"] K -->|"โณ Abandoned"| K2["๐Ÿ“ฑ Lead marked Abandoned"] K1 --> J K2 --> K3["๐Ÿ”” Auto WhatsApp:\nComplete your booking"] L --> L1["Fill: Medical History,\nMedications, Pain Scale,\nAffected Body Area"] L1 --> L2["๐Ÿ“Ž Attach Records - Optional\nX-Ray / MRI / Prescriptions / Photos"] L2 --> L3["๐ŸŽค Voice Note - Optional\nDescribe your condition"] L3 --> M["โœ… Appointment Confirmed"] M --> N["๐Ÿ“ฑ WhatsApp Notifications Sent"] N --> N1["Patient: Confirmation + Receipt"] N --> N2["Doctor: New Appointment Alert"] N --> N3["Staff: Dashboard Updated"] M --> O["๐Ÿ‘ค Patient Dashboard Access"]
03

Appointment Lifecycle & Notifications

From booking to completion โ€” reminders, no-shows, and follow-ups.

flowchart TD BOOKED["โœ… Appointment Booked"] --> T1{"โฐ Time Checks via Cron"} T1 -->|"24 hours before"| R1["๐Ÿ“ฑ Reminder to Patient"] T1 -->|"1 hour before"| R2["๐Ÿ”” Reminder to ALL:\nPatient + Doctor + Staff"] T1 -->|"15 min before if Online"| R3["๐Ÿ“ฑ Send Video Call Link"] R2 --> APPT{"๐Ÿ“… Appointment Time"} APPT -->|"Patient Shows Up"| ONGOING["๐Ÿฅ Consultation In Progress"] APPT -->|"No-Show after 15 min"| NS1["โŒ Marked No-Show"] ONGOING --> POST["๐Ÿ“ Post-Consultation"] POST --> POST1["Doctor Adds:\nDiagnosis Notes\nTreatment Plan\nExercises Prescribed\nNext Visit Date"] POST1 --> POST2{"Follow-up Needed?"} POST2 -->|"Yes"| FU["๐Ÿ“… Schedule Follow-up"] POST2 -->|"No"| DONE["โœ… Consultation Completed"] FU --> FU1["๐Ÿ“ฑ WhatsApp: Follow-up Scheduled"] FU --> BOOKED DONE --> FB["โญ Feedback Request via WhatsApp"] DONE --> HIST["๐Ÿ“œ Added to Patient History"] NS1 --> NS2{"Reschedule?"} NS2 -->|"Yes"| RESC["๐Ÿ“… Pick New Slot"] NS2 -->|"No Response in 48h"| LOST["๐Ÿ“Š Marked as Lost Lead"] RESC --> BOOKED
04

Admin Panel โ€” Module Map

All backend management modules and their sub-features.

flowchart LR subgraph DASHBOARD["๐Ÿ–ฅ๏ธ Admin Dashboard"] direction TB STATS["๐Ÿ“Š Todays Overview\nAppointments | Revenue\nPending Payments\nAbandoned Leads"] end DASHBOARD --> LEAD DASHBOARD --> PATIENT DASHBOARD --> SCHEDULE DASHBOARD --> FEE DASHBOARD --> WHATSAPP DASHBOARD --> REPORTS subgraph LEAD["๐Ÿ“‹ Lead Management"] direction TB L1["๐ŸŸก Abandoned Leads"] L2["๐Ÿ”ด Lost Leads"] L3["๐ŸŸข Converted Leads"] L4["๐Ÿ”„ Follow-up Queue"] L5["๐Ÿ“ฑ Bulk WhatsApp"] end subgraph PATIENT["๐Ÿ‘ฅ Patient Management"] direction TB P1["Add / Delete Patient"] P2["Search and Filter"] P3["Upcoming Consultations"] P4["Completed Consultations"] P5["Patient History"] P6["Add Notes"] P7["View Records"] P8["Postpone Appointment"] P9["Re-consultancy Booking"] end subgraph SCHEDULE["โฐ Schedule Management"] direction TB S1["Doctor Availability"] S2["Block Dates / Holidays"] S3["Slot Duration Config"] S4["Calendar View"] S5["Drag and Reschedule"] S6["Multi-Doctor Support"] end subgraph FEE["๐Ÿ’ฐ Fee Management"] direction TB F1["Dynamic Fee Setting"] F2["Coupon / Discount Codes"] F3["Payment Reports"] F4["Refund Management"] F5["Invoice Generation"] end subgraph WHATSAPP["๐Ÿ“ฑ WhatsApp Hub"] direction TB W1["Template Messages"] W2["Notification Logs"] W3["Quick Reply Templates"] W4["Delivery Reports"] W5["Retry Failed Messages"] end subgraph REPORTS["๐Ÿ“ˆ Reports"] direction TB R1["Revenue Analytics"] R2["Patient Demographics"] R3["Consultation Stats"] R4["Lead Conversion Rate"] end
05

Payment & Refund Flow

Razorpay integration with webhook handling and refund processing.

flowchart TD PAY_START["๐Ÿ’ณ Initiate Razorpay Payment"] --> PAY_PAGE["Razorpay Checkout\nUPI / Card / Net Banking / Wallet"] PAY_PAGE --> WEBHOOK{"Razorpay Webhook Response"} WEBHOOK -->|"payment.captured"| SUCCESS["โœ… Payment Success"] WEBHOOK -->|"payment.failed"| FAILED["โŒ Payment Failed"] WEBHOOK -->|"authorized but not captured"| PENDING["โณ Payment Pending"] SUCCESS --> RECEIPT["๐Ÿงพ Generate Invoice/Receipt"] RECEIPT --> WA_PAY["๐Ÿ“ฑ WhatsApp: Payment Confirmation + Receipt PDF"] SUCCESS --> DB_UPDATE["๐Ÿ’พ Update Database"] SUCCESS --> NEXT["Continue to Detailed Form"] FAILED --> RETRY["๐Ÿ”„ Show Retry Option"] RETRY --> PAY_PAGE PENDING --> VERIFY["๐Ÿ” Auto-verify after 5 min"] VERIFY -->|"Captured"| SUCCESS VERIFY -->|"Still Pending"| MANUAL["๐Ÿ“‹ Flag for Manual Review"] subgraph REFUND["๐Ÿ’ธ Refund Flow"] direction TB REF_INIT["Admin Initiates Refund"] --> REF_TYPE{"Refund Type"} REF_TYPE -->|"Full"| REF_FULL["Full Refund via Razorpay API"] REF_TYPE -->|"Partial"| REF_PARTIAL["Partial Refund"] REF_FULL --> REF_PROCESS["โณ Processing 3-7 days"] REF_PARTIAL --> REF_PROCESS REF_PROCESS --> REF_WA["๐Ÿ“ฑ WhatsApp: Refund Initiated"] REF_PROCESS --> REF_DONE["โœ… Refund Completed"] REF_DONE --> REF_WA2["๐Ÿ“ฑ WhatsApp: Refund Credited"] end
06

Role-Based Access Control

Four distinct user roles with specific permissions and capabilities.

๐Ÿ”‘

Super Admin

  • Full system access
  • User & role management
  • Fee configuration
  • Analytics & reports
  • WhatsApp template management
  • Coupon & discount management
  • Refund processing
๐Ÿ‘จโ€โš•๏ธ

Doctor

  • View own schedule
  • Patient history & records
  • Add consultation notes
  • Prescribe exercises
  • Schedule follow-ups
  • Block dates / set availability
๐Ÿ‘ฉโ€๐Ÿ’ผ

Receptionist / Staff

  • Manage appointments
  • Patient check-in
  • Lead follow-up
  • Send WhatsApp messages
  • Reschedule & postpone
  • View daily calendar
๐Ÿ‘ค

Patient

  • Book appointments
  • View own history
  • Upload medical records
  • Make payments
  • Submit feedback
  • Download invoices
07

WhatsApp Notification Triggers

All 18 automated notification events in the system.

# Trigger Event Recipient Message Type
1OTP VerificationPatientOTP Code
2Payment SuccessfulPatientConfirmation + Receipt
3Appointment ConfirmedPatient, Doctor, StaffAppointment Details
424h Before AppointmentPatientReminder
51h Before AppointmentPatient, Doctor, StaffFinal Reminder
615min Before (Online Only)Patient, DoctorVideo Call Link
7Patient No-ShowPatientReschedule Prompt
8Consultation CompletedPatientSummary + Follow-up
9Follow-up ScheduledPatientNew Appointment Details
10Appointment PostponedPatient, DoctorUpdated Schedule
11Appointment CancelledPatient, Doctor, StaffCancellation + Refund Info
12Abandoned Lead (30 min)Patient"Complete your booking"
13Abandoned Lead (24h)PatientDiscount Offer / Reminder
14Refund InitiatedPatientRefund Details
15Refund CompletedPatientCredit Confirmation
16Feedback Request (2h post)PatientRating Link
17Re-consultation DuePatientBook Again Prompt
18Doctor Schedule ChangeAffected PatientsReschedule Options
08

Database Entity Relationships

High-level ER diagram showing all entities and their relationships.

erDiagram USERS ||--o{ APPOINTMENTS : books USERS ||--o{ MEDICAL_RECORDS : uploads USERS ||--o{ PAYMENTS : makes USERS { int id PK string name string phone UK string email enum gender int age text address enum role } DOCTORS ||--o{ APPOINTMENTS : handles DOCTORS ||--o{ SCHEDULES : has DOCTORS { int id PK int user_id FK string specialization string qualification text bio } SCHEDULES { int id PK int doctor_id FK enum day_of_week time start_time time end_time int slot_duration_min } BLOCKED_DATES { int id PK int doctor_id FK date blocked_date string reason } APPOINTMENTS ||--|| PAYMENTS : requires APPOINTMENTS ||--o{ CONSULTATION_NOTES : has APPOINTMENTS { int id PK int patient_id FK int doctor_id FK enum type date appointment_date time appointment_time enum status text complaint } PAYMENTS { int id PK int appointment_id FK decimal amount string razorpay_id enum status string invoice_url } CONSULTATION_NOTES { int id PK int appointment_id FK text diagnosis text treatment_plan text exercises date next_visit } MEDICAL_RECORDS { int id PK int patient_id FK int appointment_id FK string file_path enum file_type } LEADS { int id PK string phone enum status int follow_up_count } NOTIFICATIONS { int id PK int user_id FK enum channel enum status text message } FEE_CONFIG { int id PK enum consultation_type decimal amount boolean is_active } COUPONS { int id PK string code UK enum discount_type decimal value date valid_until } FEEDBACK { int id PK int appointment_id FK int rating text review }
09

Additional Features Identified

18 essential features added beyond the original brief for a production-ready system.

๐Ÿ“…

Slot-Based Booking

Prevents double-booking; shows only available time slots to patients.

๐Ÿšซ

Doctor Availability / Blocked Dates

Doctors can mark holidays, leaves, and set recurring weekly schedules.

๐Ÿ’ธ

Refund Flow

Full and partial refund processing via Razorpay with automated notifications.

๐Ÿ‘ค

Patient Dashboard

Patients can view and manage their own appointments, records, and history.

โŒ

No-Show Handling

Track missed appointments, auto-send reschedule messages via WhatsApp.

๐Ÿ“

Post-Consultation Notes

Doctor records diagnosis, treatment plan, exercises, and next visit date.

โญ

Feedback / Rating System

Builds trust and helps improve service quality through patient reviews.

๐Ÿ”‘

Role-Based Access Control

Super Admin, Doctor, Staff, Patient โ€” each with distinct permissions.

๐Ÿงพ

Invoice / Receipt PDF

Auto-generated invoices for legal compliance and professional presentation.

๐Ÿท๏ธ

Coupon / Discount System

Marketing and patient retention tool with flexible discount options.

โฐ

24h Advance Reminder

Earlier reminder so patients can plan ahead โ€” 1h isn't always enough.

๐Ÿ“น

Video Call Link (Online)

Auto-generated meeting link for online consultations via Jitsi/Zoom.

๐Ÿ”„

Follow-up Appointment Flow

Doctor suggests next visit date, system auto-schedules and notifies.

๐Ÿ“ฑ

Lead Re-engagement (24h)

Second WhatsApp with discount offer if 30-min nudge doesn't convert.

๐Ÿ‘จโ€โš•๏ธ

Multi-Doctor Support

Clinic may have multiple physiotherapists with independent schedules.

๐Ÿ’ณ

Abandoned Payment Recovery

Auto WhatsApp follow-up to recover bookings lost at payment stage.

๐ŸŽค

Patient Voice Notes

Some conditions are easier to describe verbally โ€” audio upload option.

๐Ÿ“ข

Doctor Schedule Change Alert

If doctor reschedules, notify all affected patients automatically.

10

Recommended Tech Stack

Technology choices for each layer of the application.

Backend
Laravel 11 (PHP 8.3)
Frontend (Patient)
Blade + Livewire
Admin Panel
Filament PHP
Database
MySQL 8 / PostgreSQL
Cache / Queue
Redis
Payment
Razorpay PHP SDK
WhatsApp API
Gupshup / WATI / Twilio
SMS Fallback
Twilio / MSG91
File Storage
S3 / DigitalOcean Spaces
Video Calls
Jitsi Meet / Daily.co
Scheduler
Laravel Task Scheduling
Hosting
AWS / DigitalOcean / Forge