MediQueue solves two real-world healthcare problems in a single platform:

• CareQueue — eliminates physical waiting rooms with a real-time digital queue. Patients join remotely, track their position live, and get notified when it's their turn.
• Health-Vault — gives patients full ownership of their medical records with consent-based sharing, AES-256-GCM encryption at rest, and an immutable audit trail for every access.

Three user roles — Patient, Doctor, Admin — each with their own dashboard, workflows, and permission boundary.

• Register with email/SMS OTP verification (two-step flow)
• Book appointments and join a live queue remotely
• Real-time queue position tracking with estimated wait time
• Upload, view, and delete medical records (encrypted)
• Grant / revoke per-doctor consent to individual records
• View prescriptions from completed consultations
• In-app notification centre with real-time push

• Live queue dashboard — call next patient, manage consultation flow
• Access patient records (consent-gated or emergency override with justification)
• Write and manage prescriptions
• View shared records and appointment history
• Receive real-time notifications for queue events

• Full user management (create, suspend, promote, delete)
• Analytics dashboard — appointments, queue throughput, system usage
• Audit log explorer with filtering (who accessed what, when, why)
• Emergency access review — approve / reject doctor override requests
• Real-time system activity monitoring

• ES Modules throughout the backend ("type": "module") — native import/export, all relative imports require .js extensions.
• API versioning — all routes mounted at /api/v1/; health check available at /health, /api/health, and /api/v1/health.
• Redis-backed caching & rate limiting — ioredis with lazyConnect: true; user auth cache (60s TTL), analytics cache (5 min TTL), all rate limiters share the same Redis instance.
• Stateless auth — protect() middleware verifies the JWT then calls getCachedUser() (Redis → DB fallback); no full DB hit on hot paths.
• io shared via app.set('io', io) — controllers emit real-time events without coupling to the Socket layer.
• Tokens in memory only — access tokens live in a module-level variable inside api.js (Axios interceptor). The Zustand auth-storage persists only non-sensitive user info (name, role, avatar) — never tokens.
• File proxy — GET /api/v1/records/:id/view-file fetches the file from Cloudinary server-side and streams it to the client with Content-Type: application/pdf and Content-Disposition: inline. The raw Cloudinary URL is never given to the browser.

Backend: Node.js 18 · Express · MongoDB (Mongoose) · Redis (ioredis) · Socket.io v4 · JWT · bcrypt · Multer · Cloudinary · Winston · node-cron · Nodemailer · Twilio

Frontend: React 18 · Vite · Tailwind CSS · Zustand · React Query · Axios · Socket.io-client · React Router v6

Security: AES-256-GCM (medical records) · JWT dual-token + MFA (TOTP) · OTP via SMS + email · RBAC · Helmet (default-src 'none') · Redis rate limiting · Immutable audit log · CORS origin allowlist

• Option 1 (Docker): Docker & Docker Compose
• Option 2 (Manual): Node.js v18+, MongoDB, Redis, npm

# 1. Clone the repo
git clone https://github.com/piyushkumar0707/MediQueue.git
cd MediQueue

# 2. Configure environment
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
# Edit both .env files with your values (see table below)

# 3. Start all services
docker-compose up --build

# App is now running at:
# - Frontend: http://localhost:80
# - Backend API: http://localhost:5000
# - MongoDB: localhost:27017
# - Redis: localhost:6379

Use shell environment variables to override frontend build-time endpoints and backend CORS origin without editing the compose file.

# PowerShell example
$env:VITE_API_URL="http://localhost:5000/api/v1"
$env:VITE_SOCKET_URL="http://localhost:5000"
$env:FRONTEND_URL="http://localhost"
docker-compose up --build

# Bash example
VITE_API_URL=http://localhost:5000/api/v1 \
VITE_SOCKET_URL=http://localhost:5000 \
FRONTEND_URL=http://localhost \
docker-compose up --build

• If compose fails before startup, ensure backend/.env exists:
  • cp backend/.env.example backend/.env
• Backend validates required variables at boot. Confirm these are set in backend/.env:
  • MONGODB_URI, REDIS_URL, JWT_ACCESS_SECRET, JWT_REFRESH_SECRET, JWT_MFA_SECRET, ENCRYPTION_KEY
• ENCRYPTION_KEY must be exactly 32 characters in production mode.

# 1. Clone
git clone https://github.com/piyushkumar0707/MediQueue.git
cd MediQueue

# 2. Backend
cd backend
cp .env.example .env        # fill in all required vars (see table below)
npm install
npm run dev                 # → http://localhost:5000

# 3. Frontend (new terminal)
cd frontend
cp .env.example .env        # set VITE_API_URL and VITE_SOCKET_URL
npm install
npm run dev                 # → http://localhost:5173

⚠️ Never change ENCRYPTION_KEY after records are stored — existing records become permanently unreadable.

GitHub Actions workflow is configured at .github/workflows/ci.yml.

• Push to main
• Pull request targeting main
• Manual run (workflow_dispatch)

• Backend Lint and Test

  • Starts MongoDB and Redis service containers
  • Installs backend dependencies
  • Runs npm run lint
  • Runs npm test -- --passWithNoTests

• Frontend Build

  • Installs frontend dependencies
  • Runs npm run build

npm --prefix backend run lint
npm --prefix backend test -- --passWithNoTests
npm --prefix frontend run build

Require both checks before merge into main:

• Backend Lint and Test
• Frontend Build

Use this as the standard release flow for this repository.

• Confirm required production env vars are set (MONGODB_URI, REDIS_URL, JWT_ACCESS_SECRET, JWT_REFRESH_SECRET, JWT_MFA_SECRET, ENCRYPTION_KEY, FRONTEND_URL, and required provider keys)
• Ensure branch protection on main requires CI checks
• Ensure CI workflow is green on the release PR

# CI parity
npm --prefix backend run lint
npm --prefix backend test -- --passWithNoTests
npm --prefix frontend run build

# Container smoke test
docker-compose up -d --build
docker-compose ps

Health checks:

• Frontend: http://localhost/health
• Backend: http://localhost:5000/health

• Open PR to main
• Wait for both CI jobs to pass:
  • Backend Lint and Test
  • Frontend Build
• Merge PR
• Deploy using your target environment process (container platform, VM, or orchestration)

• Verify API health endpoint returns healthy status
• Verify frontend loads and authentication flow works
• Verify one core end-to-end flow (e.g. registration/login or queue join)
• Check logs for startup/runtime errors

• If health checks fail or critical paths break:
  • rollback to last known good image/commit
  • re-run health checks
  • investigate using CI logs + runtime logs before re-release

├── backend/src/
│   ├── server.js              # Entry: helmet→compression→cors→JSON→morgan → routes → Socket.io
│   ├── config/
│   │   ├── database.js        # Mongoose connection
│   │   ├── redis.js           # ioredis (lazyConnect: true)
│   │   ├── validateEnv.js     # Startup env validation — crashes fast if required vars missing
│   │   └── cloudinary.js      # Cloudinary SDK
│   ├── controllers/           # One controller per domain
│   ├── middleware/
│   │   ├── auth.js            # protect() + authorize(...roles) — Redis-cached user lookup
│   │   ├── auditLogger.js     # Wraps admin routes — writes AuditLog entries
│   │   └── errorHandler.js    # Global — masks 5xx messages in production
│   ├── models/                # 9 Mongoose schemas
│   ├── routes/                # Express routers (all at /api/v1/)
│   ├── services/              # notificationService, emailService, encryption.service
│   └── utils/
│       ├── userCache.js       # getCachedUser(), invalidateUserCache(), getOrSetCache()
│       ├── rateLimiter.js     # createRateLimiter() — Redis-backed factory
│       ├── logger.js          # Winston — stdout always; file transports dev-only
│       ├── jwt.js             # signAccessToken(), signRefreshToken(), verifyAccessToken()
│       └── pagination.js      # parsePagination(query, defaultLimit)
│
└── frontend/src/
    ├── App.jsx                # React Router v6 with ProtectedRoute role guards
    ├── store/
    │   ├── useAuthStore.js    # Zustand — tokens in memory only, non-sensitive fields persisted
    │   └── notificationStore.js
    ├── services/
    │   └── api.js             # Axios instance + auto token-refresh interceptor
    ├── pages/
    │   ├── patient/           # Dashboard, Queue, Appointments, HealthVault, Consent, Prescriptions
    │   ├── doctor/            # Dashboard, QueueManagement, PatientRecords, PrescriptionsList, SharedRecords
    │   └── admin/             # Dashboard, UserManagement, AuditLogs, Analytics, EmergencyReview
    └── components/            # Shared UI: layouts, navigation, NotificationBell

MediQueue integrates Groq LLaMA 3.1 for two advisory features. The design follows a strict human-in-the-loop model.

1. Patient types symptoms in the Join Queue form
2. "Suggest priority" button calls POST /api/v1/queue/triage (rate-limited: 5 req/min)
3. Groq returns { priority, reason, confidence } — pre-fills the priority selector
4. Patient can override — if they do, aiOverridden: true is stored on the queue entry
5. Non-dismissable disclaimer always shown: "AI suggests a priority level based on symptoms. This is not a medical diagnosis. A doctor will confirm."

1. Patient (or doctor with consent) opens a record and clicks "Summarize with AI"
2. Backend fetches the file from Cloudinary via server-side signed URL
3. PDF path: pdf-parse extracts text → PII stripped → sent to llama-3.1-8b-instant
4. Image path: file base64-encoded server-side → sent to meta-llama/llama-4-scout-17b-16e-instruct (multimodal)
5. Response: { summary, keyFindings, followUpNeeded, transcriptionConfidence } — displayed in UI, never stored
6. Per-user quota: max 10 requests/hour (Redis counter, shared across PDF + image)
7. Non-dismissable disclaimer: "AI-generated summary. Always consult your doctor for medical advice."

• GROQ_API_KEY missing → app starts normally, AI endpoints return 503 with a clear message
• Groq timeout (8 s) → one automatic retry, then fallback response
• AI_FEATURE_*=false → endpoint returns 503, no Groq call is made

This project is proprietary and confidential.