A comprehensive, full-stack platform for managing patient records, appointments, and medical billing — built with modern web technologies and enterprise-grade security features.
- Features
- Screenshots
- Tech Stack
- Getting Started
- Default Login Credentials
- MongoDB Atlas Setup
- API Documentation
- Security Features
- Project Structure
- Troubleshooting
- Changelog
- Contributing
- Contributors
- License
| 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 |
Clean, minimal authentication interface with username/password fields and registration link.
Admin dashboard displaying real-time statistics, quick actions, upcoming appointments, and recent patients.
View all scheduled appointments with patient details, dates, status badges, and inline edit/delete actions.
Tabular patient records with search by name/contact. Supports full CRUD with add, edit, and delete actions.
Detailed patient registration form capturing full name, age, gender, contact, address, and medical history.
Appointment booking with patient/doctor dropdowns, date-time picker, and reason field.
Invoice creation with dynamic line items, auto-calculated total, and patient selection.
Invoice management dashboard with summary cards (Total, Pending, Paid) and status tracking per patient.
Individual invoice record showing patient name, amount, status badge, date, and action buttons.
Patient collection with structured columns: Name, Age, Gender, Contact, and CRUD actions.
Complete appointments view with all scheduled check-ups, dates, and status badges.
Fresh dashboard with single patient record and no appointments — demonstrating clean initial state.
| 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 |
- Node.js (v18+)
- MongoDB Atlas account (or local MongoDB)
- npm or yarn
# Clone repository
git clone <repository-url>
cd Healthcare-management-system
# Install server dependencies
cd server && npm install
# Install client dependencies
cd ../client && npm installCreate server/.env:
PORT=5000
MONGO_URI=mongodb+srv://<username>:<password>@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:
VITE_API_URL=http://localhost:5000/api
⚠️ Important: Both.envfiles are excluded from version control via.gitignore.
cd server
node seed.js| Terminal | Command | Directory |
|---|---|---|
| 1️⃣ Server | npm run dev |
/server |
| 2️⃣ Client | npm run dev |
/client |
| Service | URL |
|---|---|
| 🖥️ Frontend | http://localhost:5173 |
| ⚡ Backend API | http://localhost:5000 |
| Username | Password | Role |
|---|---|---|
admin |
password123 |
👑 Admin |
doctor |
password123 |
🩺 Doctor |
staff |
password123 |
👤 Staff |
💡 Run
node seed.jsin the server folder to create these users.
- 🌐 Create account at mongodb.com/cloud/atlas
- 🗄️ Create a free M0 cluster
- 👤 Database Access: Add a database user with read/write permissions
- 🌍 Network Access: Whitelist your IP (or
0.0.0.0/0for development) - 🔗 Connect: Get connection string and update
server/.env
⚠️ Important: Add/hms_dbto the connection string before the?to specify the database name.
| 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) |
| 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 |
| 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 |
| 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 |
| 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_TOKENonly with authorized personnel who need to create new user accounts.
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
| 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 |
- 🔒 Security
- Implemented admin token authentication gate for user registration (
x-admin-tokenheader) - Added
express-rate-limitfor login (10 req/15 min) and registration (5 req/15 min) - Created comprehensive input validation with
express-validatorfor all API endpoints
- Implemented admin token authentication gate for user registration (
- ✨ 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
- Environment-based API URL configuration with
- 🔧 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
- New:
- 📝 Configuration
- Added
ADMIN_REGISTER_TOKENto server environment variables - Added
VITE_API_URLto client environment variables
- Added
- 🗄️ 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
- 💄 Design
- Implemented modern dark sidebar theme (
Slate-900) to reduce eye strain - Added
Teal-400accents for active navigation states - Updated main content background to
Slate-50for better contrast
- Implemented modern dark sidebar theme (
- 🔧 Fixes
- Resolved UI brightness uniformity issues
- Improved navigation link visibility and hover states
- Reference: User Feedback — "Left side is too bright"
- 🎉 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
Contributions are welcome!
- 🍴 Fork the repository
- 🌿 Create a feature branch (
git checkout -b feature/AmazingFeature) - 💾 Commit your changes (
git commit -m 'Add AmazingFeature') - 📤 Push to the branch (
git push origin feature/AmazingFeature) - 🔃 Open a Pull Request
-
😎 Jay Arre Talosig - Machine Learning Engineer | Blockchain Developer | Bioinformatics Scientist
-
🕵️ Alexander Castilo - Penetration Tester | Software Engineer | Threat Researcher
-
🧑💻 Mark Jhoshua Taberna - Digital Forensics Analyst | UI Specialist | Full Stack Engineer
-
🧑💻 Charles Medio - Machine Learning Engineer | Software Engineer
-
🕵️ Tristan Jhay Salamat - Full Stack Engineer | Forensics Analyst | QA Engineer
-
🕵️♀️ Rinoah Venedict Dela Rama - Forensic Analyst | QA Engineer | Data Engineer
-
🥷 Nicko Nehcterg Dalida - Digital Forensics Analyst | QA Engineer | Smart Contract Auditor
This project is licensed under the MIT 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
Made with ❤️ by flexycode
