Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/flexycode/healthcare-management-system

🤖 Heathcare Management System
https://github.com/flexycode/healthcare-management-system

express information-security javascript mern-stack mongodb nodejs software-engineering

Last synced: 16 days ago
JSON representation

🤖 Heathcare Management System

Awesome Lists containing this project

README 

          
# 🏥 Healthcare Management System





  React

  Node.js

  Express

  MongoDB

  Vite

  TailwindCSS






  A comprehensive, full-stack platform for managing patient records, appointments, and medical billing — built with modern web technologies and enterprise-grade security features.




---



## 📑 Table of Contents



- [Features](#-features)

- [Screenshots](#-screenshots)

  - [Frontend UI](#-frontend-ui)

  - [Backend — Data Management](#-backend--data-management)

  - [Database — MongoDB Atlas](#-database--mongodb-atlas)

- [Tech Stack](#️-tech-stack)

- [Getting Started](#-getting-started)

  - [Prerequisites](#-prerequisites)

  - [Installation](#-installation)

  - [Environment Setup](#️-environment-setup)

  - [Seed Database](#-seed-database)

  - [Run Application](#️-run-application)

  - [Access Points](#-access-points)

- [Default Login Credentials](#-default-login-credentials)

- [MongoDB Atlas Setup](#️-mongodb-atlas-setup)

- [API Documentation](#-api-documentation)

  - [Authentication](#-authentication)

  - [Patients](#-patients)

  - [Appointments](#-appointments)

  - [Billing](#-billing)

- [Security Features](#-security-features)

- [Project Structure](#-project-structure)

- [Troubleshooting](#-troubleshooting)

- [Changelog](#-changelog)

- [Contributing](#-contributing)

- [Contributors](#-contributors)

- [License](#-license)



---



## ✨ Features



| Feature | Description |

|---------|-------------|

| 👥 **Patient Management** | Full CRUD operations for patient records with search and filtering |

| 📅 **Appointment Scheduling** | Schedule, manage, and track appointments with doctor assignment |

| 💰 **Billing & Invoices** | Generate invoices with line items, track payment status (Pending/Paid) |

| 🔒 **Role-Based Access Control** | Granular permissions for Admin, Doctor, and Staff roles |

| 🎫 **JWT Authentication** | Secure token-based authentication with session management |

| 🛡️ **Admin Token Gate** | Registration requires a valid admin token to prevent unauthorized signups |

| ⏱️ **Rate Limiting** | Brute-force protection on login and registration endpoints |

| ✅ **Input Validation** | Server-side validation with detailed error messages on all endpoints |

| 🌐 **Environment Config** | Centralized API URL management via environment variables |

| 🎨 **Modern Dark UI** | Responsive dark sidebar with teal accents and smooth animations |



---



## 📸 Screenshots



### 🖥️ Frontend UI



#### Login Page

*Clean, minimal authentication interface with username/password fields and registration link.*





  Login Page




#### Dashboard Overview

*Admin dashboard displaying real-time statistics, quick actions, upcoming appointments, and recent patients.*





  Dashboard with Data




#### Appointments Management

*View all scheduled appointments with patient details, dates, status badges, and inline edit/delete actions.*





  Appointments List




---



### 📊 Backend — Data Management



#### Patient Management

*Tabular patient records with search by name/contact. Supports full CRUD with add, edit, and delete actions.*





  Patient Management — List View




#### Add New Patient Modal

*Detailed patient registration form capturing full name, age, gender, contact, address, and medical history.*





  Add Patient Modal




#### Schedule Appointment Modal

*Appointment booking with patient/doctor dropdowns, date-time picker, and reason field.*





  Schedule Appointment Modal




#### Create Invoice Modal

*Invoice creation with dynamic line items, auto-calculated total, and patient selection.*





  Create Invoice Modal




#### Billing & Invoices — List View

*Invoice management dashboard with summary cards (Total, Pending, Paid) and status tracking per patient.*





  Billing List View




---



### 🗄️ Database — MongoDB Atlas



#### Billing Record (Single Invoice)

*Individual invoice record showing patient name, amount, status badge, date, and action buttons.*





  Single Invoice Record




#### Patient Records (2 Entries)

*Patient collection with structured columns: Name, Age, Gender, Contact, and CRUD actions.*





  Patient Records Table




#### Appointments List (Full Data)

*Complete appointments view with all scheduled check-ups, dates, and status badges.*





  Appointments Full Data




#### Dashboard (Initial State)

*Fresh dashboard with single patient record and no appointments — demonstrating clean initial state.*





  Dashboard Initial State




---



## 🛠️ Tech Stack



| Layer | Technologies |  

|-------|-------------|

| **Frontend** | React, Vite, TailwindCSS, Framer Motion |

| **Backend** | Node.js, Express, MongoDB, Mongoose ODM |

| **Auth** | JWT, bcrypt, RBAC (Admin, Doctor, Staff) |

| **Security** | express-rate-limit, express-validator, Admin Token Gate |

| **Dev Tools** | nodemon, dotenv, cors |



---



## 🚀 Getting Started



### 📋 Prerequisites



- Node.js (v18+)

- MongoDB Atlas account (or local MongoDB)

- npm or yarn



### 📦 Installation



```bash

# Clone repository

git clone 

cd Healthcare-management-system



# Install server dependencies

cd server && npm install



# Install client dependencies

cd ../client && npm install

```



### ⚙️ Environment Setup



Create `server/.env`:

```env

PORT=5000

MONGO_URI=mongodb+srv://:@cluster0.xxxxx.mongodb.net/hms_db?appName=Cluster0

JWT_SECRET=your_jwt_secret_key_here

ADMIN_REGISTER_TOKEN=hms_admin_register_2024_!@#

```



Create `client/.env`:

```env

VITE_API_URL=http://localhost:5000/api

```



> ⚠️ **Important:** Both `.env` files are excluded from version control via `.gitignore`.



### 🌱 Seed Database



```bash

cd server

node seed.js

```



### ▶️ Run Application



| Terminal | Command | Directory |

|----------|---------|-----------|

| 1️⃣ Server | `npm run dev` | `/server` |

| 2️⃣ Client | `npm run dev` | `/client` |



### 🌐 Access Points



| Service | URL |

|---------|-----|

| 🖥️ Frontend | http://localhost:5173 |

| ⚡ Backend API | http://localhost:5000 |



---



## 🔐 Default Login Credentials



| Username | Password | Role |

|----------|----------|------|

| `admin` | `password123` | 👑 Admin |

| `doctor` | `password123` | 🩺 Doctor |

| `staff` | `password123` | 👤 Staff |



> 💡 Run `node seed.js` in the server folder to create these users.



---



## ☁️ MongoDB Atlas Setup



1. 🌐 Create account at [mongodb.com/cloud/atlas](https://www.mongodb.com/cloud/atlas)

2. 🗄️ Create a free M0 cluster

3. 👤 **Database Access**: Add a database user with read/write permissions

4. 🌍 **Network Access**: Whitelist your IP (or `0.0.0.0/0` for development)

5. 🔗 **Connect**: Get connection string and update `server/.env`



> ⚠️ **Important:** Add `/hms_db` to the connection string before the `?` to specify the database name.



---



## 📡 API Documentation



### 🔐 Authentication

| Method | Endpoint | Description |

|--------|----------|-------------|

| POST | `/api/auth/register` | Register new user *(requires `x-admin-token` header)* |

| POST | `/api/auth/login` | Login user *(rate-limited: 10 req/15 min)* |



### 👥 Patients

| Method | Endpoint | Description |

|--------|----------|-------------|

| GET | `/api/patients` | Get all patients |

| POST | `/api/patients` | Create patient *(validated: name, age, gender, contact)* |

| PUT | `/api/patients/:id` | Update patient |

| DELETE | `/api/patients/:id` | Delete patient |



### 📅 Appointments

| Method | Endpoint | Description |

|--------|----------|-------------|

| GET | `/api/appointments` | Get all appointments |

| POST | `/api/appointments` | Create appointment *(validated: patient, doctor, date)* |

| PUT | `/api/appointments/:id` | Update appointment |

| DELETE | `/api/appointments/:id` | Delete appointment |



### 💳 Billing

| Method | Endpoint | Description |

|--------|----------|-------------|

| GET | `/api/billing` | Get all invoices |

| POST | `/api/billing` | Create invoice *(validated: patient, amount, status)* |

| PUT | `/api/billing/:id` | Update invoice |

| DELETE | `/api/billing/:id` | Delete invoice |



---



## 🛡️ Security Features



| Feature | Description |

|---------|-------------|

| **Admin Token Registration** | User registration requires a valid `x-admin-token` header (configured in `server/.env`) |

| **Rate Limiting** | Login: 10 req/15 min · Registration: 5 req/15 min per IP |

| **Input Validation** | `express-validator` schemas on all endpoints with detailed error messages |

| **JWT Authentication** | Secure token-based auth with expiration |

| **Role-Based Access** | 3 roles (Admin, Doctor, Staff) with granular permissions |

| **Password Hashing** | bcrypt with salt rounds for secure password storage |

| **Environment Variables** | All secrets isolated in `.env` files (not committed to repo) |



> 💡 **Admin Token:** Share the `ADMIN_REGISTER_TOKEN` only with authorized personnel who need to create new user accounts.



---



## 📁 Project Structure



```

Healthcare-management-system/

├── client/                     # React + Vite frontend

│   ├── src/

│   │   ├── components/         # Reusable UI components (Sidebar, Layout)

│   │   ├── config/             # API URL configuration

│   │   ├── context/            # Auth context (login, register, token)

│   │   └── pages/              # Page components (Dashboard, Patients, etc.)

│   ├── .env                    # Client environment variables

│   └── package.json

├── server/                     # Node.js + Express backend

│   ├── controllers/            # Route handlers (auth, patients, etc.)

│   ├── middleware/              # Auth, rate limiting, validation

│   ├── models/                 # Mongoose schemas (User, Patient, etc.)

│   ├── routes/                 # API route definitions

│   ├── seed.js                 # Database seeder for default users

│   ├── .env                    # Server environment variables

│   └── package.json

├── assets/                     # Screenshots and design references

│   └── Web Application Screen Designs/

│       ├── Web Application UI/

│       └── Database Development/

└── README.md

```



---



## 🔧 Troubleshooting



| Error | Solution |

|-------|----------|

| `ECONNREFUSED` | MongoDB not running. Check Atlas connection or start local MongoDB |

| `Authentication failed` | Verify username/password in `server/.env` |

| `IP not whitelisted` | Add your IP in Atlas → Network Access |

| `User not found` | Run `node seed.js` to create default users |

| `403 - Registration requires admin token` | Provide valid `ADMIN_REGISTER_TOKEN` in the registration form |

| `429 - Too many requests` | Rate limit reached. Wait 15 minutes before retrying |

| `400 - Validation errors` | Check request body matches required field formats |



---



## 📝 Changelog



### v1.2.0 (2026-02-16) — Security Hardening & Input Validation

- **🔒 Security**

    - Implemented admin token authentication gate for user registration (`x-admin-token` header)

    - Added `express-rate-limit` for login (10 req/15 min) and registration (5 req/15 min)  

    - Created comprehensive input validation with `express-validator` for all API endpoints

- **✨ Features**  

    - Environment-based API URL configuration with `VITE_API_URL`

    - Centralized API config module at `client/src/config/api.js`

    - Admin Token field added to the registration UI form

- **🔧 Middleware**

    - New: `rateLimiter.js` — Rate limiting middleware for auth routes

    - New: `validators.js` — Schema validation for auth, patients, appointments, billing

    - New: `handleValidation.js` — Unified validation error response handler

- **📝 Configuration**

    - Added `ADMIN_REGISTER_TOKEN` to server environment variables

    - Added `VITE_API_URL` to client environment variables



---



### v1.1.0 (2026-01-30) — Database Integration & Full UI Implementation

- **🗄️ Database**

    - Connected MongoDB Atlas with production cluster configuration

    - Implemented 4 core collections: Users, Patients, Appointments, Invoices

    - Added seed script (`seed.js`) for default user accounts

- **📸 Documentation**

    - Captured frontend UI screenshots (Login, Dashboard, Appointments)

    - Captured database/backend screenshots (Patient Management, Billing, Modals)

    - Documented MongoDB Atlas setup process

- **🎨 UI Enhancements**

    - Finalized responsive design across all dashboard views

    - Implemented patient search functionality with real-time filtering

    - Enhanced billing invoice management with dynamic line items

    - Added appointment scheduling modal with doctor/patient dropdowns



---



### v1.0.1 (2026-01-12) — UI/UX Modernization

- **💄 Design**

    - Implemented modern dark sidebar theme (`Slate-900`) to reduce eye strain

    - Added `Teal-400` accents for active navigation states

    - Updated main content background to `Slate-50` for better contrast

- **🔧 Fixes**

    - Resolved UI brightness uniformity issues

    - Improved navigation link visibility and hover states

    - Reference: *User Feedback — "Left side is too bright"*



---



### v1.0.0 (2026-01-05) — Initial Release

- **🎉 Core Features**

    - Patient management with full CRUD operations

    - Appointment scheduling system with date/time and doctor assignment

    - Billing and invoice generation with line items

    - JWT-based authentication with token management

    - Role-based access control (Admin, Doctor, Staff)

- **🏗️ Architecture**

    - React frontend with Vite build tool and hot module replacement

    - Express backend with RESTful API design

    - MongoDB database with Mongoose ODM

    - TailwindCSS + Framer Motion for responsive UI animations

- **📦 Initial Setup**

    - Project structure, dependencies, and scripts

    - Development server with nodemon auto-restart

    - Basic README documentation



---



## ✨ Screenshots



---



## 🤝 Contributing



Contributions are welcome! 



1. 🍴 Fork the repository

2. 🌿 Create a feature branch (`git checkout -b feature/AmazingFeature`)

3. 💾 Commit your changes (`git commit -m 'Add AmazingFeature'`)

4. 📤 Push to the branch (`git push origin feature/AmazingFeature`)

5. 🔃 Open a Pull Request



### 👋 Contributors

### Special thanks to all my groupmates: 

 * ####  😎 [Jay Arre Talosig](https://github.com/flexycode) - Machine Learning Engineer | Blockchain Developer | Bioinformatics Scientist    

 * ####  🕵️ [Alexander Castilo](https://github.com/xandercastillo0305-dev) - Penetration Tester | Software Engineer | Threat Researcher

 * ####  🧑‍💻 [Mark Jhoshua Taberna](https://github.com/MjTaberna) - Digital Forensics Analyst | UI Specialist | Full Stack Engineer 

 * ####  🧑‍💻 [Charles Medio](https://github.com/charles41onlyy) - Machine Learning Engineer | Software Engineer

 * ####  🕵️ [Tristan Jhay Salamat](https://github.com/tristanjhay) - Full Stack Engineer | Forensics Analyst | QA Engineer



 * ####  🕵️‍♀️ [Rinoah Venedict Dela Rama](https://github.com/Noah-dev2217) - Forensic Analyst | QA Engineer | Data Engineer 

 * ####  🥷 [Nicko Nehcterg Dalida](https://github.com/nicknicndin) - Digital Forensics Analyst | QA Engineer | Smart Contract Auditor

---



## 📄 License



This project is licensed under the **[MIT License](LICENSE)**.



> The MIT License is a permissive license that is short and to the point. It lets people do anything they want with your code as long as they provide attribution back to you and don't hold you liable.



**Permissions**: ✅ Commercial use, ✅ Modification, ✅ Distribution, ✅ Private use

**Limitations**: ❌ Liability, ❌ Warranty



#### Git Commit Message: 🏥 Healthcare Management System

---





  Made with ❤️ by flexycode




---



mystreak















mystreak