|
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.
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
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 |
|
|
|
|
|
|
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
| 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 | ✅ | ✅ | ✅ | ❌ |
📦 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 |
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
| Requirement | Minimum Version | Recommended |
|---|---|---|
| v18+ | v20 LTS | |
| v6+ | Atlas (Cloud) | |
| v9+ | Latest | |
| v2+ | Latest |
1️⃣ Clone the Repository
git clone https://github.com/Saurabhtbj1201/Hospital-Management-System.git
cd Hospital-Management-System2️⃣ Install Server Dependencies
cd server
npm install3️⃣ Install Admin Panel Dependencies
cd ../Admin
npm install4️⃣ Install Client Site Dependencies
cd ../Client
npm install5️⃣ Configure Environment Variables (see Environment Variables section)
6️⃣ Seed the Database (creates test users)
cd ../server
node seed.jsOpen 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.
# 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_keyVITE_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=falseVITE_API_URL=http://localhost:5000/api
⚠️ Never commit.envfiles to version control. Use the.env.examplefiles as reference.
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.jsThis creates the default Admin, Receptionist, and Doctor accounts in your local MongoDB.
| 👑 Admin | 👩⚕️ Receptionist | 🩺 Doctor | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
|
🔐 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) |
| 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 |
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
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. 🎉
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-System3️⃣ 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-docs4️⃣ 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 featurefix:— Bug fixdocs:— Documentation changesstyle:— Code formatting (no logic change)refactor:— Code restructuringtest:— Adding/updating tests
6️⃣ Push to Your Fork
git push origin feature/your-feature-name7️⃣ 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!
Found a bug? Help us improve by reporting it!
- 🔍 Search Existing Issues — Check if the issue has already been reported in Issues
- 📋 Create a New Issue — Click New Issue
- 📝 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.
- 🏷️ Add Labels — Use appropriate labels like
bug,enhancement,documentation, etc. - 📤 Submit — Click "Submit new issue"
💡 Tip: The more details you provide, the faster we can fix it!
To keep the codebase clean and maintainable, please follow these PR guidelines:
| ✅ Do | ❌ Don't |
|---|---|
|
|
Submit PR → Auto Checks → Code Review → Changes Requested? → Approved → Merged! 🎉
↓
Make Changes
↓
Push Updates → Re-Review → Merged! 🎉
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!
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.