🌐 Live Demo

Patient Appointment Booking

Staff & Management Portal

Full Project Details & Contribution

💬 Feedback is warmly welcomed! Found a bug? Have a feature idea? Open an issue or reach out directly.

---

📋 Table of Contents

Click to expand

• ✨ Overview
• 🎯 Key Features
• 🏗️ Architecture Diagram
• 👥 User Role Access Matrix
• 🛠️ Tech Stack
• 📁 Project Structure
• 🚀 Getting Started
• ⚙️ Environment Variables
• 🔑 Test Credentials
• 📡 API Endpoints
• 🔒 Security Features
• 🛣️ Roadmap
• 🤝 Contributing
• 🐛 Reporting Issues
• 📜 Pull Request Rules
• ⭐ Show Your Support
• 📄 License
• 👨‍💻 Developer

---

✨ Overview

Hospital Management System (HMS) is a comprehensive, full-stack, open-source healthcare management platform designed to streamline hospital operations. It features role-based access control with dedicated portals for Admins, Receptionists, and Doctors, along with a public-facing site for patients to book appointments online.

🏥 One Platform — Three Powerful Portals — Infinite Possibilities

🌐 Public Site	🔐 Admin Portal	👩‍⚕️ Receptionist Portal	🩺 Doctor Portal
Appointment Booking	Full System Control	Operations & Billing	Clinical Management
Department Browsing	User & Role Management	Patient Records	Appointment Handling
Doctor Discovery	Analytics Dashboard	Invoice Generation	Profile & Availability

---

🎯 Key Features

🔐 Authentication & Security ✅ Login via Email or Phone Number ✅ JWT Token-based authentication ✅ Role-Based Access Control (RBAC) ✅ bcrypt password hashing (salt rounds: 10) ✅ Protected routes with automatic role redirection ✅ Helmet.js HTTP security headers ✅ Google reCAPTCHA integration (Public site)	👑 Admin Portal ✅ Dashboard with real-time analytics & charts ✅ Admin / Doctor / Receptionist Management ✅ Department & Service Management ✅ Appointment Control & Slot Configuration ✅ Billing & Custom Invoice Templates ✅ Announcements & Site Updates (CMS) ✅ Support Ticket Management
👩‍⚕️ Receptionist Portal ✅ Dashboard with today's appointments & alerts ✅ Create / Confirm / Cancel Appointments ✅ Patient Management & Record Updates ✅ Billing & Invoicing (taxes, discounts) ✅ Slot Management for doctors ✅ Profile Management & Settings	🩺 Doctor Portal ✅ Dashboard with schedule & pending tasks ✅ View Assigned Appointments ✅ Patient History & Records access ✅ Profile Management & Availability ✅ Settings & Preferences ✅ Read-only Billing visibility
🌐 Public Patient Site ✅ Online Appointment Booking with date & slot selection ✅ Browse Departments and Doctors ✅ Appointment Confirmation page with details ✅ Google reCAPTCHA spam protection ✅ Responsive & mobile-friendly design

---

🏗️ Architecture Diagram

graph TB
    subgraph Frontend["Frontend - Vercel"]
        A["Public Site\nReact + Vite\nhms.gu-saurabh.site"]
        B["Admin Panel\nReact 19 + Vite + Tailwind\nhms-admin.gu-saurabh.site"]
    end

    subgraph Backend["Backend - Node.js Server"]
        C["Express.js API\nREST Endpoints"]
        D["Auth Middleware\nJWT Verification"]
        E["Controllers\nBusiness Logic"]
    end

    subgraph Services["Data and Services"]
        F[("MongoDB Atlas\nDatabase")]
        G["AWS S3\nFile Storage"]
        H["AWS SES\nEmail Service"]
        I["Google reCAPTCHA\nBot Protection"]
    end

    A -->|"API Calls"| C
    B -->|"API Calls"| C
    C --> D
    D --> E
    E --> F
    E --> G
    E --> H
    A --> I

    style A fill:#0d9488,stroke:#0d9488,color:#fff
    style B fill:#6366f1,stroke:#6366f1,color:#fff
    style C fill:#f59e0b,stroke:#f59e0b,color:#fff
    style D fill:#ef4444,stroke:#ef4444,color:#fff
    style E fill:#8b5cf6,stroke:#8b5cf6,color:#fff
    style F fill:#47A248,stroke:#47A248,color:#fff
    style G fill:#FF9900,stroke:#FF9900,color:#fff
    style H fill:#FF9900,stroke:#FF9900,color:#fff
    style I fill:#4285F4,stroke:#4285F4,color:#fff

Loading

---

👥 User Role Access Matrix

Feature	👑 Admin	👩‍⚕️ Receptionist	🩺 Doctor	🌐 Public
Dashboard & Analytics	✅	✅	✅	❌
User Management (CRUD)	✅	❌	❌	❌
Doctor Management	✅	❌	❌	❌
Receptionist Management	✅	❌	❌	❌
Department Management	✅	❌	❌	❌
Appointment Management	✅	✅	👁️ View	✅ Book
Patient Management	✅	✅	👁️ View	❌
Billing & Invoicing	✅	✅	👁️ Read-only	❌
Slot Configuration	✅	✅	❌	❌
Invoice Template Design	✅	❌	❌	❌
Announcements (CMS)	✅	❌	❌	❌
Site Updates (CMS)	✅	❌	❌	❌
Support Tickets	✅	❌	❌	❌
Profile Management	✅	✅	✅	❌
Settings	✅	✅	✅	❌

---

🛠️ Tech Stack

Frontend

Backend

Cloud & DevOps

📦 Full Dependency List

Package	Version	Purpose
Backend
express	5.x	Web framework
mongoose	9.x	MongoDB ODM
jsonwebtoken	9.x	JWT authentication
bcryptjs	3.x	Password hashing
helmet	8.x	Security headers
cors	2.x	Cross-origin support
morgan	1.x	HTTP request logging
multer	2.x	File upload handling
@aws-sdk/client-s3	3.x	AWS S3 integration
@aws-sdk/client-ses	3.x	AWS SES email
axios	1.x	HTTP client
dotenv	17.x	Environment variables
Admin Panel
react	19.x	UI framework
react-router-dom	7.x	Client-side routing
recharts	3.x	Charts & visualization
lucide-react	0.56x	Modern icons
react-icons	5.x	Additional icons
react-hot-toast / sonner	latest	Toast notifications
react-quill-new	3.x	Rich text editor
react-easy-crop	5.x	Image cropping
qrcode	1.x	QR code generation
@headlessui/react	2.x	Accessible UI components
tailwindcss	3.x	Utility-first CSS
Client Site
react	18.x	UI framework
react-router-dom	6.x	Client-side routing
react-google-recaptcha	3.x	Bot protection
html2pdf.js	0.14	PDF generation

---

📁 Project Structure

Hospital-Management-System/
│
├── 📂 server/                          # ⚙️ Backend API (Node.js + Express)
│   ├── 📄 package.json
│   ├── 📄 seed.js                      # 🌱 Database seeding script
│   ├── 📄 .env                         # 🔒 Server environment variables
│   └── 📂 src/
│       ├── 📄 app.js                   # Express app configuration
│       ├── 📄 server.js                # Server entry point
│       ├── 📂 config/
│       │   ├── 📄 db.js                # MongoDB connection
│       │   └── 📄 s3.js                # AWS S3 config
│       ├── 📂 controllers/             # 📋 Route handlers
│       │   ├── 📄 authController.js
│       │   ├── 📄 appointmentController.js
│       │   └── ... more controllers
│       ├── 📂 middleware/
│       │   └── 📄 authMiddleware.js    # 🛡️ JWT auth middleware
│       ├── 📂 models/                  # 🍃 Mongoose schemas
│       │   ├── 📄 User.js
│       │   ├── 📄 Admin.js
│       │   ├── 📄 Doctor.js
│       │   └── ... more models
│       ├── 📂 routes/                  # 🛤️ API route definitions
│       │   ├── 📄 authRoutes.js
│       │   ├── 📄 appointmentRoutes.js
│       │   └── ... more routes
│       ├── 📂 services/                # ☁️ External service integrations
│       │   ├── 📄 awsSesService.js     # Email via AWS SES
│       │   ├── 📄 captchaService.js    # reCAPTCHA verification
│       │   └── 📄 s3Service.js         # File upload via AWS S3
│       └── 📂 utils/                   # 🔧 Utility functions
│
├── 📂 Admin/                           # 🔐 Admin Panel (React 19 + Tailwind)
│   ├── 📄 package.json
│   ├── 📄 vite.config.js
│   ├── 📄 tailwind.config.js
│   ├── 📄 vercel.json
│   ├── 📄 .env
│   └── 📂 src/
│       ├── 📄 App.jsx                  # App router & route config
│       ├── 📄 main.jsx                 # Entry point
│       ├── 📂 components/              # 🧩 Reusable components
│       │   ├── 📄 ProtectedRoute.jsx
│       │   └── ... more components
│       ├── 📂 context/
│       │   └── 📄 AuthContext.jsx      # 🔑 Auth state management
│       ├── 📂 layouts/
│       │   └── 📄 AdminLayout.jsx      # 📐 Main layout wrapper
│       ├── 📂 pages/                   # 📄 Page components
│       │   ├── 📄 Login.jsx
│       │   ├── 📄 Dashboard.jsx            # Admin dashboard
│       │   ├── 📄 ReceptionistDashboard.jsx
│       │   └── 📄 *Profile.jsx         # Role-specific profiles
│       │   └── ... more pages
│       ├── 📂 services/
│       │   └── 📄 api.js               # 🌐 Axios API client
│       ├── 📂 styles/
│       │   └── 📄 action-buttons.css
│       └── 📂 utils/
│           └── 📄 helpers.js           # 🔧 Utility functions
│
├── 📂 Client/                          # 🌐 Public Patient Site (React 18)
│   ├── 📄 package.json
│   ├── 📄 vite.config.js
│   ├── 📄 vercel.json
│   ├── 📄 .env
│   └── 📂 src/
│       ├── 📄 App.jsx
│       ├── 📄 main.jsx
│       ├── 📂 pages/
│       │   ├── 📄 Home.jsx             # Landing page
│       │   ├── 📄 AppointmentBooking.jsx
│       │   └── 📄 AppointmentConfirmation.jsx
│       └── 📂 services/
│           └── 📄 api.js               # 🌐 API client
│
├── 📄 README.md                        # 📖 You are here!
└── 📄 .gitignore

---

🚀 Getting Started

📋 Prerequisites

Requirement	Minimum Version	Recommended
	v18+	v20 LTS
	v6+	Atlas (Cloud)
	v9+	Latest
	v2+	Latest

📥 Installation

1️⃣ Clone the Repository

git clone https://github.com/Saurabhtbj1201/Hospital-Management-System.git
cd Hospital-Management-System

2️⃣ Install Server Dependencies

cd server
npm install

3️⃣ Install Admin Panel Dependencies

cd ../Admin
npm install

4️⃣ Install Client Site Dependencies

cd ../Client
npm install

5️⃣ Configure Environment Variables (see Environment Variables section)

6️⃣ Seed the Database (creates test users)

cd ../server
node seed.js

▶️ Running Locally

Open three terminals and run:

Terminal	Command	URL
🟢 Server	cd server && npm run dev	http://localhost:5000
🔵 Admin Panel	cd Admin && npm run dev	http://localhost:5173
🟣 Client Site	cd Client && npm run dev	http://localhost:5174

💡 The server runs on port 5000 by default. Admin and Client panels will auto-assign available ports via Vite.

---

⚙️ Environment Variables

Server (server/.env)

# Server Configuration
PORT=5000
NODE_ENV=development

# Database
MONGO_URI=your_mongodb_connection_string_here

# Authentication
JWT_SECRET=your_super_secret_jwt_key_here

# AWS SES (Email Service)
AWS_REGION=your_aws_region
AWS_ACCESS_KEY_ID=your_aws_access_key
AWS_SECRET_ACCESS_KEY=your_aws_secret_key
AWS_SES_FROM_EMAIL=noreply@yourhospital.com

# AWS S3 (File Storage)
AWS_S3_BUCKET_NAME=your_s3_bucket_name

# Google reCAPTCHA
RECAPTCHA_SECRET_KEY=your_recaptcha_secret_key

Admin Panel (Admin/.env)

VITE_API_URL=http://localhost:5000/api
VITE_APP_NAME=HMS Admin Portal
VITE_APP_VERSION=1.0.0
VITE_ENABLE_NOTIFICATIONS=true
VITE_ENABLE_ANALYTICS=false

Client Site (Client/.env)

VITE_API_URL=http://localhost:5000/api

⚠️ Never commit .env files to version control. Use the .env.example files as reference.

---

🔑 Test Credentials

Use these credentials on the Admin Panel to explore different roles.

Note

These test credentials only work when running the project locally (localhost). You must seed the database first by running:

cd server
node seed.js

This creates the default Admin, Receptionist, and Doctor accounts in your local MongoDB.

👑 Admin	👩‍⚕️ Receptionist	🩺 Doctor
Field Value 📧 Email admin@hospital.com 📱 Phone 1234567890 🔒 Password admin123	Field Value 📧 Email receptionist@hospital.com 📱 Phone 1234567891 🔒 Password receptionist123	Field Value 📧 Email doctor@hospital.com 📱 Phone 1234567892 🔒 Password doctor123

---

📡 API Endpoints

🔐 Authentication — /api/auth

Method	Endpoint	Description	Auth Required
POST	/api/auth/login	Login with email/phone & password	❌
POST	/api/auth/register	Register new user	❌
GET	/api/auth/profile	Get current user profile	✅

👥 User Management — /api/user-management

Method	Endpoint	Description	Auth Required
GET	/api/user-management	Get all users	✅ Admin
POST	/api/user-management	Create new user	✅ Admin
PUT	/api/user-management/:id	Update user	✅ Admin
DELETE	/api/user-management/:id	Delete user	✅ Admin

🩺 Doctors — /api/doctors

Method	Endpoint	Description	Auth Required
GET	/api/doctors	Get all doctors	✅
POST	/api/doctors	Create doctor	✅ Admin
PUT	/api/doctors/:id	Update doctor	✅ Admin
DELETE	/api/doctors/:id	Delete doctor	✅ Admin

📅 Appointments — /api/admin/appointments

Method	Endpoint	Description	Auth Required
GET	/api/admin/appointments	Get all appointments	✅
POST	/api/admin/appointments	Create appointment	✅
PUT	/api/admin/appointments/:id	Update appointment	✅
DELETE	/api/admin/appointments/:id	Delete appointment	✅ Admin

🌐 Public Appointments — /api/public-appointments

Method	Endpoint	Description	Auth Required
GET	/api/public-appointments/doctors	Get available doctors	❌
GET	/api/public-appointments/slots	Get available slots	❌
POST	/api/public-appointments	Book public appointment	❌

👤 Patients — /api/patients

Method	Endpoint	Description	Auth Required
GET	/api/patients	Get all patients	✅
POST	/api/patients	Create patient	✅
PUT	/api/patients/:id	Update patient	✅

💰 Billing — /api/bills

Method	Endpoint	Description	Auth Required
GET	/api/bills	Get all bills	✅
POST	/api/bills	Create bill	✅
PUT	/api/bills/:id	Update bill	✅

🏢 Departments — /api/departments

Method	Endpoint	Description	Auth Required
GET	/api/departments	Get all departments	✅
POST	/api/departments	Create department	✅ Admin
PUT	/api/departments/:id	Update department	✅ Admin
DELETE	/api/departments/:id	Delete department	✅ Admin

🔧 More Endpoints

Base Route	Description
/api/services	Hospital services management
/api/profile	User profile operations
/api/slot-config	Appointment slot configuration
/api/invoice-template	Invoice template management
/api/dashboard	Dashboard analytics data
/api/support	Support ticket management
/api/announcements	Announcement management (CMS)
/api/site-updates	Site update management (CMS)

---

🔒 Security Features

Feature	Implementation	Status
🔐 Password Hashing	bcrypt with salt rounds (10)	✅ Active
🎫 Token Authentication	JWT (JSON Web Tokens)	✅ Active
🛡️ HTTP Security Headers	Helmet.js	✅ Active
🌐 CORS Protection	Configurable origin whitelist	✅ Active
👮 Role-Based Access	Middleware-level RBAC	✅ Active
🤖 Bot Protection	Google reCAPTCHA v2	✅ Active
📝 Request Logging	Morgan HTTP logger	✅ Active
🔒 Environment Secrets	dotenv (never committed)	✅ Active
📤 Secure File Upload	Multer with size/type limits	✅ Active

---

🛣️ Roadmap

gantt
    title HMS Development Roadmap
    dateFormat  YYYY-MM
    axisFormat  %b %Y

    section ✅ Completed
    Core Authentication & RBAC          :done, 2025-01, 2025-03
    Admin Dashboard & Analytics         :done, 2025-02, 2025-04
    Appointment Management              :done, 2025-03, 2025-05
    Billing & Invoice System            :done, 2025-04, 2025-06
    Public Appointment Booking          :done, 2025-05, 2025-07
    AWS S3 & SES Integration            :done, 2025-06, 2025-08
    CMS (Announcements & Updates)       :done, 2025-07, 2025-09
    Slot Configuration System           :done, 2025-08, 2025-10

    section 🔄 In Progress
    Performance Optimization            :active, 2026-01, 2026-03
    Mobile Responsiveness Polish        :active, 2026-02, 2026-04

    section 📋 Planned
    SMS Notifications (Twilio)          : 2026-04, 2026-06
    Payment Gateway Integration         : 2026-05, 2026-07
    Advanced Reporting & Analytics      : 2026-06, 2026-08
    Multi-language Support (i18n)       : 2026-07, 2026-09
    Prescription PDF Generation         : 2026-08, 2026-10
    Patient Mobile App (React Native)   : 2026-09, 2026-12

Loading

---

🤝 Contributing

We love contributions! This is an open-source project and every contribution counts — whether it's fixing a bug, improving docs, or building a new feature. 🎉

📌 Contribution Steps

Step 1  →  Step 2  →  Step 3  →  Step 4  →  Step 5  →  Step 6  →  Step 7
 Fork      Clone      Branch     Code       Commit     Push       PR + Form

1️⃣ Fork the Repository

Click the Fork button at the top-right of this repo to create your own copy.

2️⃣ Clone Your Fork

git clone https://github.com/<your-username>/Hospital-Management-System.git
cd Hospital-Management-System

3️⃣ Create a Feature Branch

git checkout -b feature/your-feature-name
# Examples:
# git checkout -b feature/add-prescription-module
# git checkout -b fix/login-validation-error
# git checkout -b docs/update-api-docs

4️⃣ Make Your Changes

• Follow existing code style and conventions
• Write clean, commented code
• Test your changes locally

5️⃣ Commit Your Changes

git add .
git commit -m "feat: add prescription generation module"

Use Conventional Commits format:

• feat: — New feature
• fix: — Bug fix
• docs: — Documentation changes
• style: — Code formatting (no logic change)
• refactor: — Code restructuring
• test: — Adding/updating tests

6️⃣ Push to Your Fork

git push origin feature/your-feature-name

7️⃣ Open a Pull Request & Submit Contribution Form

• Go to the original repository and click "New Pull Request"
• Provide a clear title and description of your changes
• Link any related issues using Fixes #issue-number

📝 Final Step: After opening your PR, please fill out the contribution form by clicking the "Contribute Now" button on the HMS Contribution Page. This helps us track and acknowledge your contribution!

---

🐛 Reporting Issues

Found a bug? Help us improve by reporting it!

📝 Steps to Report an Issue

1. 🔍 Search Existing Issues — Check if the issue has already been reported in Issues
2. 📋 Create a New Issue — Click New Issue
3. 📝 Fill in the Details:
   • Title: Short, descriptive title (e.g., "Login fails with phone number on mobile")
   • Description: Clear explanation of the issue
   • Steps to Reproduce: Numbered steps to recreate the problem
   • Expected Behavior: What should happen
   • Actual Behavior: What actually happens
   • Screenshots: Attach screenshots if applicable
   • Environment: Browser, OS, Node.js version, etc.
4. 🏷️ Add Labels — Use appropriate labels like bug, enhancement, documentation, etc.
5. 📤 Submit — Click "Submit new issue"

💡 Tip: The more details you provide, the faster we can fix it!

---

📜 Pull Request Rules

To keep the codebase clean and maintainable, please follow these PR guidelines:

✅ Do	❌ Don't
✅ Create feature branch from main ✅ One PR per feature/fix ✅ Write clear PR description ✅ Follow existing code style ✅ Test changes locally before PR ✅ Keep commits atomic and meaningful ✅ Use Conventional Commit messages ✅ Link related issues (Fixes #123) ✅ Update docs if changing behavior ✅ Keep PR scope focused and small	❌ Push directly to main ❌ Mix multiple features in one PR ❌ Submit untested code ❌ Include unrelated changes ❌ Commit .env or secrets ❌ Commit node_modules/ ❌ Use vague commit messages ❌ Ignore code review feedback ❌ Force push to shared branches ❌ Submit empty or WIP PRs

🔄 PR Review Process

Submit PR  →  Auto Checks  →  Code Review  →  Changes Requested?  →  Approved  →  Merged! 🎉
                                                    ↓
                                              Make Changes
                                                    ↓
                                              Push Updates  →  Re-Review  →  Merged! 🎉

---

⭐ Show Your Support

If you find this project helpful or learned something from it, please consider:

⭐ Star this repository — It helps others discover this project!

🍴 Fork it — And build something amazing!

📣 Share it — Spread the word on social media!

🐛 Report bugs — Help us make it better!

💡 Suggest features — We'd love to hear your ideas!

---

📄 License

This project is licensed under the MIT License — you are free to use, modify, and distribute this project.

MIT License

Copyright (c) 2026 Saurabh Kumar

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

---

👨‍💻 Developer

© Developed with ❤️ by Saurabh Kumar. All Rights Reserved 2026

Saurabh Kumar

🔗 Connect With Me

---

Made with ❤️ by Saurabh Kumar
⭐ Star this repo if you find it helpful!

---

💝 If you like this project, please give it a ⭐ and share it with others!

Happy Coding! 🚀