👨‍⚕️PH Healthcare System

🎯 Overview

PH Healthcare System is a healthcare platform that enables seamless online consultations between patients and doctors. The system handles the complete lifecycle of healthcare appointments: from doctor registration and approval, schedule management, patient booking, payment processing, video consultations, to digital prescriptions.

Key Capabilities

• Multi-role Authentication: Patient, Doctor, Admin, Super Admin with role-based access control
• Doctor Onboarding: Application, verification, and approval workflow
• Schedule Management: Doctors create and publish availability schedules
• Appointment Booking: Real-time slot booking with payment integration
• Payment Processing: bKash integration for secure payments
• Video Consultations: Meet link integration for online sessions
• Digital Prescriptions: PDF generation and email delivery
• Analytics Dashboard: Role-specific analytics for patients, doctors, and admins
• Email Notifications: Automated emails for registration, appointments, prescriptions, and more

---

🛠 Tech Stack

Backend

Technology	Version	Purpose
Node.js	20+	Runtime environment
Express.js	5.x	Web framework
TypeScript	7.x	Type-safe development
Prisma ORM	7.x	Database ORM
PostgreSQL	15+	Primary database
Redis	7+	Caching & sessions
JWT	9.x	Authentication tokens
Zod	4.x	Schema validation
bcryptjs	3.x	Password hashing

Services & Integrations

Service	Purpose
bKash	Payment gateway (Bangladesh)
Cloudinary	Image/file storage
Nodemailer	Email delivery
Google Auth	OAuth2 login for patients
PDFKit	PDF generation for prescriptions/invoices
node-cron	Scheduled jobs (cleanup tasks)

🗄 Database Schema

The data model centers on a User that owns either a Patient or Doctor profile. Doctors publish Schedules, patients book Appointments against those schedules, and each appointment has an associated Payment and, once completed, a Prescription.

User ─┬─ Patient ─── Appointment ─┬─ Payment
      └─ Doctor ──── Schedule ────┴─ Prescription

Full schema definitions go to Document.md

🔌 API Endpoints

All endpoints are prefixed with /api/v1

Authentication (/auth)

Method	Path	Auth	Body	Description
POST	/register	❌	{name, email, password}	Register new patient
POST	/verify-email	❌	{email, otp}	Verify email with OTP
POST	/login	❌	{email, password}	User login (all roles)
GET	/me	✅ (All)	-	Get current user profile
POST	/refresh-token	❌	-	Refresh access token
POST	/google	❌	{credential}	Google OAuth login (patients only)
POST	/forgot-password	❌	{email}	Request password reset OTP
POST	/reset-password	❌	{email, otp, newPassword}	Reset password with OTP

User (/user)

Method	Path	Auth	Body	Description
PATCH	/profile-image	✅ (All)	multipart/form-data	Upload profile image

Doctor (/doctor)

Method	Path	Auth	Body	Description
POST	/apply-doctor	❌	multipart/form-data	Apply to become a doctor (resume, files)
POST	/apply-doctor/email-verify	❌	{email, otp}	Verify doctor application email
POST	/approved-doctor	✅ (Admin, Super Admin)	{doctorId, status, rejectionReason?}	Approve/reject doctor application
GET	/all-doctors	✅ (Admin, Super Admin)	Query params	Get all doctors (paginated)
PATCH	/update-profile	✅ (Doctor)	{specialization, bio, fee, etc.}	Update doctor profile
GET	/public/available-today	❌	-	Get doctors available today
GET	/public/all-doctors	❌	Query params	Get all approved doctors list
GET	/public/:doctorId	❌	-	Get single doctor public profile

Schedule (/schedule)

Method	Path	Auth	Body	Description
POST	/	✅ (Doctor)	{startDateTime, endDateTime, meetLink}	Create schedule (draft)
GET	/my-schedule	✅ (Doctor)	Query params	Get doctor's own schedules
GET	/all-schedule	✅ (Admin, Super Admin)	Query params	Get all schedules
GET	/todays-schedule	❌	-	Get today's published schedules
PUT	/:scheduleId	✅ (Doctor)	{startDateTime?, endDateTime?, meetLink?}	Update schedule
PATCH	/publish-schedule/:scheduleId	✅ (Doctor)	-	Publish draft schedule
PUT	/delete/:scheduleId	✅ (Doctor)	-	Soft delete schedule

Appointment (/appointment)

Method	Path	Auth	Body	Description
POST	/book-appointment	✅ (Patient)	{scheduleId}	Book appointment & initiate payment
POST	/cancel-appointment	✅ (Patient)	{appointmentId}	Cancel appointment
GET	/book-appointment/payment/callback	❌	Query params	bKash payment callback
GET	/my-appointment	✅ (Patient)	Query params	Get patient's appointments
GET	/my-appointments	✅ (Doctor)	Query params	Get doctor's appointments
PATCH	/update	✅ (Doctor)	{appointmentId, status}	Update appointment status (ongoing/completed)
GET	/all-appointments	✅ (Admin, Super Admin)	Query params	Get all appointments
GET	/:appointmentId	✅ (All)	-	Get single appointment details

Payment (/payment)

Method	Path	Auth	Body	Description
POST	/	✅ (Patient)	{appointmentId}	Create payment for appointment
GET	/my-payment	✅ (Patient)	Query params	Get patient's payment history
GET	/doctor-payment	✅ (Doctor)	Query params	Get doctor's payment history
GET	/all-payment	✅ (Admin, Super Admin)	Query params	Get all payments

Prescription (/prescription)

Method	Path	Auth	Body	Description
POST	/	✅ (Doctor)	{appointmentId, findings, medicines}	Create prescription
GET	/:appointmentId	✅ (All)	-	Get prescription for appointment

Analytics (/analytical)

Method	Path	Auth	Body	Description
GET	/patient-analytics	✅ (Patient)	-	Patient dashboard analytics
GET	/doctor-analytics	✅ (Doctor)	-	Doctor dashboard analytics
GET	/admin-analytics	✅ (Admin, Super Admin)	-	Admin dashboard analytics

---

✨ Features

Authentication & Authorization

• JWT-based auth with access + refresh tokens (httpOnly cookies)
• Role-based access control (RBAC) for all endpoints
• Google OAuth for patient registration/login
• Email OTP verification for self-registration (patient & doctor)
• Forgot/Reset password flow with OTP
• Password change for logged-in users
• Set password for Google-only patients

Appointment Booking

• Today-only visibility for patients
• Real-time slot availability
• Upfront payment required
• Serial number assignment
• Invoice PDF emailed on booking
• Cancellation with refund rules (>1hr before = refund)

Appointment Lifecycle

PENDING → CONFIRMED (paid) → ONGOING → COMPLETED
                ↓
            CANCELLED

Background Jobs

• Auto-delete unverified doctor applications
• Auto-delete rejected doctors
• Seed data for development

---

👤 Patient Flow

1. Registration & Login

Register (email/password or Google)
    ↓
Email OTP Verification (if credential)
    ↓
Auto-login + Welcome Email
    ↓
Access Dashboard

---

👨‍⚕️ Doctor Flow

1. Application & Onboarding

POST /api/v1/doctor/apply-doctor (multipart: resume, certificates)
    ↓
Email OTP Verification (POST /apply-doctor/email-verify)
    ↓
Application Status: PENDING
    ↓
Admin Review → APPROVED / REJECTED
    ↓
If APPROVED: Welcome Email + Account Activated
    ↓
Login with credentials

---

👑 Admin & Super Admin Flow

1. Platform Oversight

GET /api/v1/appointment/all-appointments
GET /api/v1/payment/all-payment
GET /api/v1/schedule/all-schedule
GET /api/v1/analytical/admin-analytics
- Revenue reports
- User growth
- Appointment statistics
- Doctor approval queue

2. Admin Creation (Super Admin only)

Create Admin/Super Admin accounts programmatically
- Organization email (login)
- Personal email (welcome credentials)
- Auto-generated password
- Force password change on first login

---

🚀 Setup & Installation

Prerequisites

• Node.js 20+
• PostgreSQL 15+
• Redis 7+
• bKash Developer Account (for payments)
• Cloudinary Account (for file storage)
• Gmail/App Password (for emails)
• Google Cloud Console (for OAuth)

Installation

# Clone repository
git clone <repository-url>
cd PH-Healthcare-System

# Install dependencies
npm install

# Setup environment variables
cp .env.example .env
# Edit .env with your configuration

# Generate Prisma Client
npx prisma generate

# Run migrations
npx prisma migrate dev

# (Optional) Seed database
npm run dev  # Seeds run on server start

# Start development server
npm run dev

Production Build

npm run build
npm start

---

🔧 Environment Variables

# Server
PORT=5000
NODE_ENV=development

# Database
DATABASE_URL="postgresql://user:pass@localhost:5432/ph_healthcare?schema=public"

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# JWT
JWT_ACCESS_SECRET=your-access-secret
JWT_REFRESH_SECRET=your-refresh-secret
JWT_ACCESS_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

# Frontend
FRONTEND_URL=http://localhost:3000

# Email (Nodemailer)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
EMAIL_FROM="PH Healthcare <noreply@phhealthcare.com>"

# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_CALLBACK_URL=http://localhost:5000/api/v1/auth/google/callback

# Cloudinary
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

# bKash
BKASH_USERNAME=your-bkash-username
BKASH_PASSWORD=your-bkash-password
BKASH_APP_KEY=your-app-key
BKASH_APP_SECRET=your-app-secret
BKASH_BASE_URL=https://tokenized.sandbox.bka.sh/v1.2.0-beta
BKASH_CALLBACK_URL=http://localhost:5000/api/v1/appointment/book-appointment/payment/callback

# App
BCRYPT_SALT_ROUNDS=12

---

📜 Scripts

Command	Description
npm run dev	Start development server with hot reload
npm run build	Build for production (tsup)
npm start	Run production build
npm run format:check	Check code formatting
npm run format:fix	Fix code formatting
npm run lint:check	Check linting
npm run lint:fix	Fix linting issues

---

📁 Project Structure

src/
├── app.ts                 # Express app setup
├── server.ts              # Entry point
├── app/
│   ├── config/
│   │   └── env.ts         # Environment config
│   ├── controller/        # Route controllers (deprecated)
│   ├── interface/         # TypeScript interfaces
│   ├── lib/
│   │   ├── bkash.ts       # bKash payment integration
│   │   ├── cloudinary.ts  # File upload
│   │   ├── cron.ts        # Scheduled jobs
│   │   ├── googleAuth.ts  # Google OAuth
│   │   ├── nodemailer.ts  # Email service
│   │   ├── prisma.ts      # Prisma client
│   │   └── redis.ts       # Redis client
│   ├── middleware/
│   │   ├── checkAuth.ts   # JWT authentication
│   │   ├── globalErrorHandler.ts
│   │   ├── notFound.ts    # 404 handler
│   │   └── zodValidation.ts
│   ├── module/
│   │   ├── analytics/     # Analytics endpoints
│   │   ├── appointment/   # Appointment management
│   │   ├── auth/          # Authentication
│   │   ├── doctor/        # Doctor management
│   │   ├── payment/       # Payment processing
│   │   ├── prescription/  # Prescription system
│   │   ├── schedule/      # Schedule management
│   │   └── user/          # User profile
│   ├── template/          # Email templates (EJS)
│   └── utils/
│       ├── appError.ts    # Custom error class
│       ├── catchAsync.ts  # Async error wrapper
│       ├── jwt.ts         # JWT utilities
│       ├── seed.ts        # Database seeding
│       └── sendResponse.ts

---

🔐 Security Considerations

• Passwords: Bcrypted with 12 rounds
• Tokens: httpOnly, secure, sameSite cookies
• Validation: Zod schemas on all inputs
• Rate Limiting: Implement at reverse proxy (nginx)
• CORS: Configured for specific frontend origin

---