██╗  ██╗███████╗ █████╗ ██╗  ████████╗██╗  ██╗███╗   ██╗███████╗██╗  ██╗ █████╗
██║  ██║██╔════╝██╔══██╗██║  ╚══██╔══╝██║  ██║████╗  ██║██╔════╝╚██╗██╔╝██╔══██╗
███████║█████╗  ███████║██║     ██║   ███████║██╔██╗ ██║█████╗   ╚███╔╝ ███████║
██╔══██║██╔══╝  ██╔══██║██║     ██║   ██╔══██║██║╚██╗██║██╔══╝   ██╔██╗ ██╔══██║
██║  ██║███████╗██║  ██║███████╗██║   ██║  ██║██║ ╚████║███████╗██╔╝ ██╗██║  ██║
╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚══════╝╚═╝   ╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝

HealthNexa digitises the complete patient journey — from AI-powered symptom analysis and geo-based hospital/pharmacy discovery, through slot-based appointment booking, QR code check-in, and live queue tracking.

Six distinct user roles — each with their own isolated dashboard and API surface — make HealthNexa a complete ecosystem for patients, hospitals, and pharmacies alike.

• Secure authentication and profile management with image upload
• Book appointments with available doctors via smart slot scheduling
• View upcoming and historical appointments with unique QR code per booking
• AI-powered symptom checker (Google Gemini) with full history tracking
• Find nearest hospitals and pharmacies on an interactive map
• Real-time live queue token tracking

• Live queue dashboard — see today's patient list in real time
• Call next patient with one click — broadcasts instantly via Socket.IO
• Mark appointments as complete
• View patient and appointment details

• Hospital profile and image management
• Add, edit, and remove doctors (with Cloudinary image upload)
• Add and manage receptionists
• Operational dashboard with key stats

• QR code scanner — scan patient's appointment QR to instantly check in
• Insert checked-in patient into the priority queue
• Recall skipped patients
• Real-time queue workflow support

• Pharmacy profile and image management
• Medicine inventory management (add, edit, delete, stock, price)
• Submit new medicine listing requests to admin
• Pharmacy dashboard overview

• Google Gemini AI symptom analysis — possible conditions, emergency level, recommended departments, red flags, home-care advice
• Results cached in Redis by SHA-256 request hash — zero repeat API cost
• Full symptom history stored per patient

• Socket.IO room-based live queue updates (queue:{doctorId}:{date})
• Live token tracking — patients, receptionists, and doctors all see the same state
• No polling — all updates pushed via WebSocket broadcast

• JWT stored in HTTP-only cookies (XSS-safe)
• 6 role-based middleware guards — strict API isolation per role
• Redis-backed session verification (5-min TTL)
• Secure bcrypt password hashing
• OTP email verification via Brevo for registration and password reset
• Admin approval workflow — hospitals, pharmacies, and medicines require review before going live

┌─────────────────────────────────────────────────────────────┐
│                        CLIENT LAYER                          │
│           Next.js 16 (App Router) — port 3000                │
│    Redux Toolkit · React Hook Form · Socket.IO Client        │
│           Leaflet Maps · QR Scanner · Framer Motion          │
└──────────────────────────┬──────────────────────────────────┘
                           │  HTTP REST + WebSocket
┌──────────────────────────▼──────────────────────────────────┐
│                         API LAYER                            │
│            Express 5 + Socket.IO — port 5000                 │
│     protect → role guards → controllers → helpers            │
└──────┬──────────────────────────────┬────────────────────────┘
       │                              │
┌──────▼──────┐              ┌────────▼────────┐
│  MongoDB 7  │              │    Redis 7       │
│  Mongoose   │              │  Session cache   │
│  2dsphere   │              │  AI result cache │
│  geo-index  │              │  5-min TTL       │
└─────────────┘              └─────────────────┘

External Services:
  ├── Cloudinary     →  image storage & CDN
  ├── Brevo          →  OTP transactional email
  └── Google Gemini  →  AI symptom analysis

HealthNexa/
│
├── 📁 client/                        # Next.js 16 frontend
│   └── src/
│       ├── app/
│       │   ├── (auth)/               # Login, Register, Forget Password
│       │   ├── (patient)/            # Dashboard, Appointments, Symptoms
│       │   ├── admin/                # Registration request management
│       │   ├── hospital-admin/       # Doctor & receptionist management
│       │   ├── doctor/               # Live queue dashboard
│       │   ├── receptionist/         # Check-in & recall
│       │   ├── pharmacy/             # Inventory & profile
│       │   └── emergency/            # Emergency info
│       ├── components/               # Shared UI components
│       ├── store/slice/              # Redux slices (one per role)
│       ├── providers/                # Context providers (one per role)
│       ├── hooks/                    # useSocket, GetUser
│       └── Types/                    # TypeScript interfaces
│
├── 📁 server/                        # Node.js / Express backend
│   └── src/
│       ├── controller/               # Business logic (one per role)
│       ├── routes/                   # Express routers (one per role)
│       ├── models/                   # Mongoose schemas
│       ├── middlewares/              # protect, 6x role guards, upload
│       ├── config/                   # DB, Redis, Cloudinary, Gemini, Socket
│       └── helpers/                  # ApiErrors, ApiResponse, AsyncHandler
│
├── 🐳 docker-compose.yml
├── 📄 .env.docker
└── 📄 LICENCE

The entire stack is fully containerised. One command starts everything.

# Start all services (with build)
docker compose up --build

# Run in background
docker compose up -d --build

# Stop all services
docker compose down

• Node.js >= 18
• Docker + Docker Compose or local MongoDB + Redis

git clone https://github.com/Foridul35962/HealthNexa.git
cd HealthNexa

cd server
npm install
cp .env.example .env
# Fill in all environment variable values

cd ../client
npm install

Create server/.env:

# Server
CORS_ORIGIN=http://localhost:3000

# Authentication
TOKEN_SECRET=your_super_secret_jwt_key
TOKEN_EXPIRY=7d

# Database
MONGODB_URI=mongodb://localhost:27017/healthnexa

# Redis
REDIS_URL=redis://localhost:6379
REDIS_PREFIX=healthNexa

# Cloudinary
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# Brevo (Email OTP)
SENDER_EMAIL=your_sender@example.com
BREVO_API_KEY=your_brevo_api_key

# Google Gemini AI
GEMINI_API_KEY=your_gemini_api_key

cp .env.example .env.docker   # fill in values
docker compose up --build

# Terminal 1 — Backend
cd server && npm start

# Terminal 2 — Frontend
cd client && npm run dev

Base URL: http://localhost:5000/api
Protected routes require a valid JWT (set as HTTP-only cookie on login).

Request Body:

{
  "age": 28,
  "gender": "male",
  "symptoms": ["headache", "fever", "fatigue"],
  "duration": "3 days",
  "temperature": "38.5°C",
  "bloodPressure": "120/80",
  "conditions": [],
  "medications": [],
  "allergies": [],
  "notes": "Started after getting wet in the rain"
}

Client → POST /api/auth/login
       ← Set-Cookie: token=<JWT>; HttpOnly; Secure; SameSite=Strict

Every protected request:
  protect middleware
    → decode JWT
    → check Redis cache (5-min TTL)
    → fallback to MongoDB lookup
    → attach user to req.user
    → role guard middleware
    → controller

• ✅ JWT in HTTP-only cookies — XSS-safe, no JS access
• ✅ 6 role-based middleware guards — strict server-side isolation
• ✅ bcrypt password hashing
• ✅ express-validator input sanitisation
• ✅ OTP email verification via Brevo
• ✅ Admin approval workflow — no unverified entity enters production data
• ✅ Unique QR hash per appointment — cannot be guessed or reused

Home	Patient Dashboard	AI Symptom Checker

Doctor Queue	Receptionist Check-In	Admin Panel

• Video consultation (WebRTC / telemedicine)
• Online payment gateway for consultation fees
• E-prescriptions and digital medical records
• Push notifications for appointment reminders
• React Native mobile application
• Multi-language (i18n) support
• Automated test suite (Jest + Playwright)
• CI/CD pipeline (GitHub Actions)

Building HealthNexa was a deep dive into:

• Full-Stack Architecture — designing clean separation between client, API, and data layers
• Real-Time Systems — Socket.IO room-based queue broadcasting without polling
• Redis Caching — session caching and AI result deduplication using SHA-256 input hashing
• Geo-Spatial Queries — MongoDB 2dsphere indexes for efficient nearest-location discovery
• AI Integration — prompting Gemini for structured JSON clinical output
• Multi-Role RBAC — building scalable access control with discrete middleware guards
• Docker Containerisation — orchestrating a 5-service stack with Docker Compose
• Database Modelling — designing schemas with integrity constraints for healthcare workflows

Contributions, suggestions, and feedback are welcome!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -m 'Add your feature')
4. Push your branch (git push origin feature/your-feature)
5. Open a Pull Request

Foridul Ibne Qauser

Software Engineering Enthusiast · Full-Stack Developer

This project is licensed under the ISC License — see the LICENCE file for details.