NeuroSim — Hospital Records Management System

A multi-role hospital records management system for Namulundu Hospital, rebuilt as a modern FastAPI + React application. It replaces the legacy single-admin Flask prototype with a secure, role-based system covering the full patient journey: registration → appointment → check-in → triage → consultation → prescriptions → lab → billing.

Table of Contents

• Features
• User Roles
• Tech Stack
• Project Structure
• Getting Started
• Demo Accounts
• Clinical Workflow
• Security
• API Overview
• Deployment
• Legacy Code
• License

---

Features

Clinical Workflow

• Reception: register patients (with next-of-kin & insurance details), book appointments, check patients in
• Triage (nurse): vital signs (BP, temperature, pulse, SpO2, weight, height), triage levels (non-urgent / urgent / emergency)
• Consultation (doctor): structured SOAP-style notes, diagnosis, treatment plan
• Prescriptions: medication, dosage, frequency, duration, instructions
• Laboratory: test catalog, lab orders, result entry, pending/in-progress/completed status flow
• Patient portal: view appointments, medical records, prescriptions, lab results and bills

Administration & Finance

• Staff management (admin): create staff accounts with roles, activate/deactivate, reset passwords
• Billing (accountant): services catalog, invoices with line items, discounts & tax, payments (cash/card/mobile money/bank)
• Financial reporting: total billed, collected, outstanding, breakdown by payment method
• Audit log: full trail of every action with user, entity, IP and timestamp

Security & UX

• JWT-based authentication with role-based access control (RBAC) enforced on every endpoint
• Passwords hashed with PBKDF2-SHA256 (Werkzeug), forced password change on first login
• Patient self-registration; staff accounts created and approved by admin
• Role-aware navigation, responsive Bootstrap 5 UI, live search

---

User Roles

Role	What they can do
Admin	Everything: manage staff, audit log, reports, all clinical & billing
Doctor	Consultations, prescriptions, lab orders, view results, complete visits
Receptionist	Register patients, book appointments, check in patients
Nurse	Triage patients, record vitals, monitor queue
Lab Technician	Enter lab results, manage order status
Accountant	Create invoices, record payments, financial reports, services catalog
Patient	Self-register, book appointments, view own records, prescriptions, labs and bills

---

Tech Stack

Component	Technology
Backend	Python 3.10+, FastAPI, SQLAlchemy ORM
Database	SQLite (dev) / PostgreSQL (production)
Auth	JWT (PyJWT), PBKDF2-SHA256 password hashing
Frontend	React 18, Vite, React Router, Bootstrap 5 (CDN)
Reports	ReportLab (PDF), csv (CSV)

---

Project Structure

NeuroSim/
├── backend/                 # FastAPI application
│   ├── app/
│   │   ├── main.py          # App factory, CORS, router registration
│   │   ├── config.py        # Settings & role permission matrix
│   │   ├── database.py      # SQLAlchemy engine/session
│   │   ├── models.py        # All ORM models
│   │   ├── schemas.py       # Pydantic request/response models
│   │   ├── security.py      # Password hashing + JWT
│   │   ├── deps.py          # Auth & role-guard dependencies
│   │   ├── serializers.py   # Response serializers
│   │   ├── audit.py         # Audit logging helper
│   │   └── routers/         # auth, users, patients, appointments,
│   │                        # visits, consultations, lab, billing, reports
│   ├── seed.py              # Schema + demo data (run once)
│   └── requirements.txt
│
├── frontend/                # React SPA
│   ├── index.html
│   ├── vite.config.js       # Dev proxy → /api → :8000
│   ├── package.json
│   └── src/
│       ├── main.jsx / App.jsx      # Entry & routing
│       ├── api.js                  # Fetch client + auth token
│       ├── auth.jsx                # Auth context (login/logout)
│       ├── nav.js                  # Role-based navigation config
│       ├── components/             # Layout, guards, shared UI
│       └── pages/                  # 20+ role-specific pages
│
├── app.py, auth.py, engine/       # LEGACY v1 code (kept for reference)
└── README.md

---

Getting Started

Prerequisites

• Python 3.10+ and pip
• Node.js 18+ and npm

1. Backend

cd backend

# (Windows) use the project virtual environment
..\.venv\Scripts\python.exe -m pip install -r requirements.txt

# Create the schema and demo data (run once)
..\.venv\Scripts\python.exe seed.py

# Start the API server
..\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000

The API documentation is available at http://127.0.0.1:8000/docs.

2. Frontend

cd frontend
npm install
npm run dev

Open http://127.0.0.1:5173 in your browser. The Vite dev server proxies /api requests to the backend, so no CORS issues in development.

Tip: the backend allows cross-origin requests from http://localhost:5173 too, in case you serve the built frontend separately.

---

Demo Accounts

All demo staff accounts use the password Password123!. The default admin account must change its password on first login.

Username	Role	Department
admin	Administrator	Administration
dr.mukasa	Doctor	Internal Medicine
dr.namutebi	Doctor	Pediatrics
reception.jane	Receptionist	Front Desk
nurse.peter	Nurse	General Ward
lab.rita	Lab Technician	Laboratory
acc.kato	Accountant	Finance

⚠️ Change all demo passwords before using in production.

---

Clinical Workflow

1. Receptionist registers the patient → books an appointment → checks the patient in (creates a visit).
2. Nurse triages the visit: vital signs + triage level.
3. Doctor opens the visit in Consultations, records findings & diagnosis, writes prescriptions, and orders lab tests.
4. Lab Technician sees the pending order in Laboratory, records results and completes it.
5. Doctor reviews results and completes the visit.
6. Accountant creates an invoice (pulling services from the catalog) and records the payment.
7. Patient follows everything from their portal.

---

Security

• Authentication: stateless JWT access tokens (HS256, configurable expiry).
• Passwords: PBKDF2-SHA256 with per-user salts; never stored in plaintext.
• Authorization: every API endpoint enforces role guards (require_roles); frontend nav is filtered by role as a second layer.
• Account lifecycle: staff must change the temporary password on first login; admin can disable/delete accounts; deactivated accounts cannot log in.
• Audit trail: logins, record creation/update/deletion, and financial actions are logged with user, IP, entity and timestamp.

Configuration (environment variables)

Variable	Default	Description
DATABASE_URL	sqlite:///neurosim.db	SQLAlchemy connection string
SECRET_KEY	neurosim-dev-secret-change-in-production	JWT signing secret
ACCESS_TOKEN_EXPIRE_MINUTES	720	Token lifetime
CORS_ORIGINS	http://localhost:5173,http://127.0.0.1:5173	Allowed origins

For production, set DATABASE_URL=postgresql://user:pass@host/db and a strong SECRET_KEY.

---

API Overview

All endpoints live under /api and (except login/register/health) require a Bearer token.

Method	Endpoint	Roles	Description
POST	/auth/login	public	Sign in, returns JWT
POST	/auth/register	public	Patient self-registration
POST	/auth/change-password	all	Change / force-change password
GET	/users · POST /users	admin	Manage staff accounts
GET	/patients · POST /patients	staff	Search / register patients
GET	/patients/{id}/record	staff	Full medical record
GET	/appointments · POST	staff	Manage appointments
POST	/visits · PATCH /visits/{id}/triage	reception / nurse	Check-in & triage
POST	/consultations · /prescriptions	doctor/admin	Clinical notes & medication
POST	/lab/orders · /lab/orders/{id}/results	doctor / lab tech	Lab workflow
GET	/invoices · POST /invoices/{id}/payments	accountant/admin	Billing
GET	/reports/patients/csv · /pdf	staff	Patient register exports
GET	/reports/financial	accountant/admin	Revenue summary
GET	/audit-logs	admin	Audit trail
GET	/dashboard	all (role-aware)	Per-role statistics

Interactive docs: http://127.0.0.1:8000/docs

---

Deployment

The app is fully container-ready. For production:

1. Set DATABASE_URL to PostgreSQL and run seed.py (or your own provisioning) on the new DB.
2. Serve the built frontend (cd frontend && npm run build) from any static host / nginx, pointing /api to the backend.
3. Run the backend with a production ASGI server, e.g. uvicorn app.main:app --workers 4.
4. Set a strong SECRET_KEY and restrict CORS_ORIGINS to your domain.

---

Legacy Code

The files app.py, auth.py, backup.py, engine/, utils/, templates/, Procfile, runtime.txt and requirements.txt are the v1 prototype and are kept for reference only. The redesigned system lives entirely in backend/ and frontend/.

---

License

MIT — see LICENSE.

---

Namulundu Hospital — "Comprehensive Care for All"