Remedium HMS

Enterprise Hospital Management System

An open-source, HIPAA-ready modular monolith built for modern healthcare teams.

---

Live Demo  •  Quick Start  •  Features  •  Architecture  •  API Docs  •  Deployment  •  Contributing

---

Engineering Highlights

• Modular Monolith Architecture: Decoupled 15-app domain-driven design for superior maintainability, testability, and scalability.
• Security-First Engineering: HIPAA-ready design implementing Fernet encryption for PHI at rest, immutable audit trails, and granular Role-Based Access Control (RBAC).
• Production-Grade Infrastructure: Full lifecycle management using Docker (non-root), Gunicorn, WhiteNoise, and robust GitHub Actions CI/CD pipelines. Deployed and live on Railway.
• Clinical-Grade Complexity: Implements conflict-aware appointment scheduling, real-time patient monitoring, and ledger-based financial billing systems.
• API-First Strategy: Comprehensive OpenAPI 3.0 documentation via Swagger/ReDoc, supporting enterprise-grade integrations.

---

Overview

Remedium HMS is a full-featured hospital management platform designed to handle the real complexities of healthcare operations — from patient admission to discharge, pharmacy dispensing, lab testing, surgery scheduling, and revenue tracking.

What makes it different:

• Security-first — PHI encrypted at rest with Fernet, immutable audit trails, granular RBAC across 13 roles
• Clinical-grade — Conflict-aware scheduling, vital signs monitoring, OpenFDA drug lookup
• Production-ready — Dockerized, PostgreSQL-compatible, JWT auth, OpenAPI docs
• Live in production — Deployed on Railway with PostgreSQL and Gunicorn
• Beautiful UI — Glassmorphic design system with dark mode, animations, and mobile-first responsive layout

---

🚀 Live Demo

The application is live and running — no setup required.

🌐 Open Remedium HMS →

URL	https://remedium-hms.up.railway.app
Status	🟢 Live
Hosting	Railway
Database	PostgreSQL
WSGI Server	Gunicorn
HTTPS	Enforced

Demo credentials

The public instance runs a single, deliberately read-only demo account. It is not a Django superuser or staff user, so it cannot reach /admin/, and it holds no add/change/delete permission on anything.

Role	Username	Password
Read-only viewer	demo	demo1234

Shared instance. The password above is public by design, so treat this as a read-mostly sandbox: anyone can sign in and browse, but every create, edit and delete request is rejected with 403. Do not enter real patient information — this is not a HIPAA-compliant production environment. Data is reset on redeploy.

Access is curtailed twice over, because either control alone would leak: the account's staff role is VIEWER, which appears in none of the role allow-lists in core/permissions.py so every role-gated API endpoint rejects it; and its group carries only *_view_* permissions, so the view layer permits reads and denies writes.

The account is created automatically by the deploy hook via create_demo_user --if-enabled, and is skipped entirely unless DEMO_ACCOUNT_ENABLED=true is set. Redeploying also demotes an account created by an earlier version, so tightening the role takes effect on the next deploy.

Try these first (requires login):

1. Explore the Revenue Analytics dashboard for charts and trend data
2. Try appointments scheduling to see the conflict-detection engine in action
3. Hit the API docs at /api/v1/docs/ to explore the REST API — no login required
4. Browse the Audit Logs to see the immutable trail in action

Prefer to run it yourself? See Quick Start below.

---

Features

Patient Management Full lifecycle from admission to discharge Encrypted PHI (phone, email, medical history) Insurance tracking and emergency contacts Smart Scheduling Conflict-aware appointment engine Prevents double-booking automatically Respects doctor shifts and availability Pharmacy & Inventory Real-time stock tracking with reorder alerts OpenFDA drug information integration Prescription queue with dispense tracking

Revenue Analytics Immutable ledger-based billing system Revenue dashboards with trend charts Unpaid invoice tracking and reporting Care Monitoring Vital signs visualization with charts BMI calculation and critical flagging Real-time patient status dashboard Laboratory Test queue management with priority Critical range flagging on results Automated lab order processing

---

Architecture

Remedium follows a Modular Monolith pattern with strict domain boundaries across 15 specialized apps.

graph LR
    subgraph Core ["Foundation"]
        A[Core & RBAC]
        B[Staff & Auth]
    end

    subgraph Clinical ["Clinical"]
        C1[Patients]
        C2[Medical Records]
        C3[Laboratory]
        C4[Care Monitoring]
    end

    subgraph Operations ["Operations"]
        D1[Appointments]
        D2[Billing]
        D3[Pharmacy]
        D4[Surgery]
    end

    subgraph Infrastructure ["Infrastructure"]
        E1[Inventory]
        E2[Reporting]
        E3[Integration]
        E4[Hospital Units]
        E5[Notifications]
    end

    A --> Clinical
    A --> Operations
    A --> Infrastructure

    style Core fill:#f0f0ff,stroke:#6366f1,stroke-width:2px
    style Clinical fill:#eff6ff,stroke:#3b82f6,stroke-width:2px
    style Operations fill:#f0fdf4,stroke:#22c55e,stroke-width:2px
    style Infrastructure fill:#fefce8,stroke:#eab308,stroke-width:2px

Loading

The Patient Journey

sequenceDiagram
    autonumber
    participant P as Patient
    participant R as Reception
    participant D as Doctor
    participant L as Lab / Pharmacy
    participant B as Billing

    P->>R: Registration & Triage
    R->>D: Queue Assignment
    D->>P: Consultation & Vitals
    D->>L: Lab Order / Prescription
    L-->>D: Results / Dispense
    D->>B: Finalize Encounter
    B->>P: Invoice Generated

Loading

Security Lifecycle

stateDiagram-v2
    [*] --> Input: Form Submission
    Input --> Encrypted: Fernet Encryption
    Encrypted --> Stored: Database Write
    Stored --> Audit: History Tracked
    Stored --> SoftDeleted: User Deletes
    SoftDeleted --> Stored: Admin Restores
    Stored --> Output: Transparent Decryption
    Output --> [*]

Loading

---

Role Dashboards

Each role gets a purpose-built interface with the data and tools they need.

Role	Dashboard	What You See
Admin	Revenue charts, department load, staff management, audit logs
Doctor	Daily schedule, patient vitals, prescriptions, surgery tracking
Nurse	Ward overview, critical patients, vitals logging, bed map
Surgeon	Surgery schedule, pre-op count, upcoming procedures
Pharmacist	Rx queue, stock alerts, OpenFDA lookup, dispense tracking
Lab Tech	Test queue, result entry, critical flagging, completed tests
Receptionist	Check-in queue, billing, doctor availability, registration

---

Tech Stack

Layer	Technology
Backend	Django 5.2, Python 3.13, Django REST Framework 3.16
Database	PostgreSQL (prod) / SQLite (dev)
Auth	JWT tokens, token blacklist, role-based access control
Frontend	Bootstrap 5.3, custom glassmorphism CSS, Chart.js, vanilla JS
Security	Fernet PHI encryption, CSRF protection, login throttling
DevOps	Docker (non-root), Gunicorn, WhiteNoise, GitHub Actions, Railway (live)
API	OpenAPI 3.0 with Swagger UI and ReDoc

---

Quick Start

Just want to look around? Skip this and use the Live Demo instead.

1. Clone & Install

git clone https://github.com/A0x0k/Remedium-HMS.git
cd Remedium-HMS
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Initialize

python manage.py migrate
python manage.py create_groups       # RBAC roles
python manage.py create_role_users   # Demo accounts (optional)

To create a single scoped demo account like the public instance uses:

python manage.py create_demo_user --force

3. Run

python manage.py runserver

Open http://localhost:8000 and sign in with the credentials printed by create_role_users (it generates a random password per run and prints it once). To use a known local password instead:

python manage.py create_role_users --use-default-password   # sets every role to "password123"

Or create a superuser interactively with python manage.py createsuperuser.

---

API

All endpoints are versioned under /api/v1/.

Endpoint	Description
/api/v1/patients/	Patient demographics and management
/api/v1/appointments/	Scheduling and conflict detection
/api/v1/prescriptions/	Rx management with OpenFDA lookup
/api/v1/invoices/	Ledger-based billing
/api/v1/staff/	Staff profiles and role management
/api/v1/lab-tests/	Laboratory test orders and results
/api/v1/surgeries/	Surgery scheduling and tracking
/api/v1/inventory/	Pharmacy and supply inventory

Interactive docs:

• Swagger UI: /api/v1/docs/ — or live at remedium-hms.up.railway.app/api/v1/docs/
• ReDoc: /api/v1/redoc/ — or live at remedium-hms.up.railway.app/api/v1/redoc/

Try it against the live instance:

# Public — the OpenAPI schema is served without auth
curl https://remedium-hms.up.railway.app/api/v1/docs/

# Protected — clinical data requires a JWT (returns 401 without one)
curl -i https://remedium-hms.up.railway.app/api/v1/patients/

Obtain a token from /api/v1/token/, then pass it as Authorization: Bearer <token>.

---

Testing

# Run all tests
python manage.py test

# With coverage
pip install pytest-cov
pytest --cov=. --cov-report=term-missing

Current status: 203 tests passing, 87% coverage, zero failures.

---

Project Structure

Remedium-HMS/
├── core/                   # Platform foundation, RBAC, API utilities
├── patients/               # Patient lifecycle and demographics
├── appointments/           # Scheduling engine with conflict detection
├── billing/                # Ledger-based invoicing and payments
├── pharmacy/               # Prescriptions and OpenFDA integration
├── laboratory/             # Test orders, results, critical flagging
├── care_monitoring/        # Vital signs and patient monitoring
├── surgery/                # Surgery scheduling and tracking
├── inventory/              # Supply chain and stock management
├── staff/                  # Staff profiles, shifts, and roles
├── medical_records/        # Encounters and clinical documents
├── reporting/              # Analytics and custom reports
├── integration/            # Third-party API integrations
├── hospital/               # Wards, rooms, beds, and services
├── notifications/          # SMS, Email, WhatsApp notifications
├── templates/              # Shared templates and partials
├── static/                 # CSS, JS, and assets
├── remedium_hms/           # Project settings and configuration
├── docs/                   # Documentation
└── design/                 # Logo and prototypes

---

Deployment

The live instance runs on Railway using the included Procfile and production requirements.

Component	Detail
Platform	Railway (PaaS)
WSGI	gunicorn remedium_hms.wsgi
Release hook	migrate && create_groups && create_demo_user --if-enabled
Database	PostgreSQL
Static files	WhiteNoise
Env template	.env.example

Deploy your own instance

# 1. Fork or clone this repo
git clone https://github.com/A0x0k/Remedium-HMS.git

# 2. Create a new Railway project from the repo
# 3. Add a PostgreSQL plugin and link it to the service
# 4. Copy .env.example to .env and fill in the secrets
# 5. Set DJANGO_SETTINGS_MODULE=remedium_hms.settings
# 6. (Optional) Set DEMO_ACCOUNT_ENABLED=true to seed the public demo account
# 7. Deploy — the Procfile release hook runs migrations automatically

The release hook runs create_demo_user --if-enabled, which exits cleanly when DEMO_ACCOUNT_ENABLED is unset, so deployments without a demo account are unaffected.

Live URL: https://remedium-hms.up.railway.app

---

Contributing

Contributions are welcome! Please read:

• Contributing Guide
• Security Policy
• Changelog

---

License

This project is licensed under the MIT License — see LICENSE for details.

---

Built with Django & Python

🌐 Live Demo  •  A0x0k