Invinceible Core HMS is a multi-facility hospital management system for real clinical, billing, pharmacy, laboratory, inpatient, reporting, and platform administration workflows.

The project is built as critical healthcare software. Facility and branch scoping, role-based permissions, auditability, payment safety, resilient APIs, and operational monitoring are treated as core system behavior, not optional extras.

• Strong authentication with lockout, session tracking, password reset token hashing, and production secret validation.
• Facility and branch isolation across clinical, billing, pharmacy, lab, reports, users, settings, and platform operations.
• M-Pesa/Daraja duplicate-prompt protection, status checks, idempotent callbacks, and reconciliation foundations.
• Short-TTL caching, request coalescing, pagination, scoped search, and indexed database access for high traffic.
• Audit logs for critical hospital, payment, pharmacy, clinical, and administrative actions.
• Official PDF/printout foundations for invoices, receipts, medical summaries, reports, and SHA workflows.
• Patient portal, AI assistant, communication, reporting, and data warehouse foundations behind safe feature flags.

The system connects the main hospital flow:

Reception -> Triage -> Doctor -> Lab -> Pharmacy -> Billing -> Payment -> Reports

It supports patient registration, triage, doctor consultation, structured prescribing, lab orders and results, pharmacy dispensing, IPD/admissions, billing, invoices, receipts, SHA claims, M-Pesa/Daraja payments, branches, users, roles, audit logs, reports, stock control, and platform administration.

• Patient registration, search, duplicate warning foundation, and visit history.
• Triage with vitals, urgency, priority, clinic routing, and doctor routing.
• Doctor queue and consultation workspace with structured prescribing.
• Laboratory requests, results, verification, attachments, and doctor review.
• Pharmacy catalog, branch stock, stock-aware prescribing, partial dispensing, low stock, and reorder foundations.
• IPD admissions, wards, beds, treatment charts, progress notes, and discharge summaries.
• Billing, invoices, discounts, payments, receipts, cashier close, M-Pesa, SHA coverage, and revenue tracking.
• Reports, audit logs, user management, facility settings, subscriptions, and platform controls.
• Patient portal and public verification foundations.
• AI assistance foundations for drafting and workflow support, disabled by default unless configured.

1. Reception registers or finds the patient.
2. Triage captures vitals, urgency, and routing details.
3. Doctor opens the patient from the doctor queue.
4. Doctor records consultation notes, diagnosis, lab requests, prescriptions, admission, referral, or discharge decisions.
5. Lab enters and verifies results.
6. Pharmacy dispenses structured prescription items and updates branch stock.
7. Billing creates or updates the invoice and receives payment.
8. Cashier issues receipt.
9. Admins and managers review reports, audit logs, stock, payments, and operational performance.

Backend:

• NestJS
• Prisma ORM
• MySQL
• JWT authentication
• PDFKit and QR utilities
• Redis optional cache, rate-limit, and queue foundation with in-memory fallback

Frontend:

• Next.js
• React
• TypeScript
• TanStack Query
• Tailwind-style component system

Repository:

backend/      NestJS API, Prisma, auth, billing, lab, pharmacy, IPD, users
frontend/     Next.js/React dashboard, platform pages, public pages, workflows
docs/         Security, setup, deployment, scaling, workflow, and operations guides
load-tests/   k6/autocannon load testing starting points
services/     Future worker/service foundations

Clone:

git clone https://github.com/Owinovative/invinceible_core_hms_v2.git
cd invinceible_core_hms_v2

Backend:

cd backend
npm install
cp .env.example .env
npm run prisma:generate
npm run start:dev

Frontend:

cd frontend
npm install
cp .env.example .env.local
npm run dev

Default local URLs:

• Backend: http://localhost:3000
• Frontend: http://localhost:3001

Use the examples in .env.example, backend/.env.example, and frontend/.env.example.

Production must use:

• a strong JWT_SECRET of at least 48 high-entropy characters,
• a private DATABASE_URL,
• strict FRONTEND_URL or FRONTEND_ORIGINS,
• Redis where possible for cache, rate limiting, queues, and request coalescing,
• secure M-Pesa credentials stored only in backend or facility-level protected settings,
• HTTPS-only public URLs for deployed frontend, backend, and callback endpoints.

Never commit .env files or secrets.

Backend:

cd backend
npm run prisma:generate
npm run build
npm run test
npm run prisma:migrate:deploy

Frontend:

cd frontend
npm run build
npm run lint

Dependency audit:

cd backend
npm audit --audit-level=moderate --omit=dev

cd ../frontend
npm audit --audit-level=moderate --omit=dev

• Run database backups before production migrations.
• Deploy backend and frontend through their configured platforms.
• Configure Railway backend environment variables securely.
• Configure Vercel frontend NEXT_PUBLIC_API_BASE_URL to the Railway backend URL.
• Configure Daraja callback URLs to point to the deployed backend.
• Run queue workers when queue-backed jobs are enabled.
• Check /health/live, /health/ready, and /health/deep after deployment.

Start with docs/README.md.

Important guides:

• Performance and scalability
• Production security checklist
• HMS benchmark gap analysis
• Repository audit
• Prescriptions and pharmacy workflow
• Reports and printouts
• Multi-tenant facility isolation
• M-Pesa reconciliation
• SHA and insurance workflow
• Load testing
• Security testing

Report security concerns privately. See SECURITY.md.

Security basics:

• Never commit .env files.
• Rotate any exposed local or development secret.
• Use a strong production JWT_SECRET.
• Keep Daraja credentials out of frontend payloads and logs.
• Guard report exports, payment changes, user management, and facility settings.
• Keep audit logging enabled for critical actions.

MIT. See LICENSE.