# neoastra303/remedium-hms architecture

> Architecture diagram of the GitHub repository neoastra303/remedium-hms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neoastra303/remedium-hms
- Repository: https://github.com/neoastra303/remedium-hms

## Overview

1. **System shape: a Django modular monolith**
   Remedium HMS is a single Django project (`remedium_hms`) composed of many domain apps. Each app owns its own models, migrations, templates, URLs, serializers, and tests, but they all run inside one process and one shared database. The architecture is intentionally modular rather than microservice-based.

2. **Shared platform layer lives in `core`**
   `core` provides cross-cutting concerns: RBAC/permissions, dashboard selection, audit-log UI, shared serializer helpers, context processors, and template tags. It also contains management commands that initialize groups and seed role-based demo users, which makes it the foundation for authorization and first-run setup.

3. **Patients are the primary domain anchor**
   The `patients` app is the central clinical record. Other domains reference patients for appointments, encounters, vitals, prescriptions, invoices, and admissions. The README emphasizes PHI encryption for sensitive patient fields, and the models/migrations show historical tracking, so patient data is treated as a regulated, auditable core entity.

4. **Clinical workflow spans multiple apps**
   - `appointments` handles scheduling, queueing, and conflict-aware bookings.
   - `medical_records` stores encounters and patient documents.
   - `care_monitoring` captures patient care notes and vital trends.
   - `laboratory` manages lab tests and result entry.
   - `surgery` tracks surgical cases.
   These apps form the clinical workflow from intake through treatment and follow-up, with each domain keeping its own CRUD views and APIs while linking back to patients and staff.

5. **Operations and revenue are separate but connected**
   - `billing` owns invoices, payments, and invoice numbering.
   - `pharmacy` manages prescriptions and dispense workflows.
   - `inventory` tracks stock items and costs.
   - `hospital` manages wards, rooms, services, and occupancy.
   - `staff` manages personnel, shifts, and availability.
   These apps support the operational side of the hospital and consume data from the clinical layer to generate charges, allocate resources, and schedule staff.

6. **Notifications and integrations are event-driven support layers**
   `notifications` stores user notifications and uses signals to generate them. `integration` stores external integration metadata and API keys, acting as the system’s boundary for third-party connections. `pharmacy/openfda_service.py` is the clearest external service touchpoint, calling the FDA API for drug-related data.

7. **Two delivery surfaces: server-rendered UI and REST API**
   Every major app includes Django views and HTML templates for the staff-facing UI, plus `api_views.py` and `serializers.py` for REST access. The API is versioned under `/api/v1/`, documented by `openapi-schema.yml`, and surfaced through Swagger/ReDoc. This means the same business models are exposed through both page-based workflows and programmatic clients.

8. **Role-based dashboards are a major navigation boundary**
   The `templates/dashboards` folder contains separate experiences for admin, doctor, nurse, pharmacist, receptionist, lab tech, and surgeon roles. Access control is enforced by `core.permissions` and role groups, so dashboard routing is not just cosmetic—it is the primary presentation boundary between different hospital user types.

9. **Data integrity and auditability are built into the model layer**
   Many apps include historical migrations and soft-delete fields, indicating a strong audit trail approach. `simple-history`-style historical models and delete markers appear across domains like patients, billing, pharmacy, appointments, and more. This means the system preserves record lineage instead of hard-deleting clinical and financial data.

10. **Frontend structure is shared and template-driven**
   The main UI uses a common `templates/base.html`, partials for pagination/cards/forms, and app-specific templates for list/detail/form pages. Static assets in `static/js` and `static/css` provide shared UI behavior and styling. The `design/prototypes` directory appears to be mockups/reference material rather than runtime code.

11. **Deployment and runtime are conventional but production-oriented**
   The stack is Django 5.2 on Python 3.13, with SQLite for development and PostgreSQL for production. Containerization is provided via Docker and `docker-compose.yml`, with `gunicorn`/`Procfile` for app serving and `nginx.conf` for reverse-proxy/static delivery. `WhiteNoise` and GitHub Actions CI round out the deployment and validation story.

12. **Main request flow**
   A typical request enters through Django routing in `remedium_hms/urls.py`, hits an app’s HTML view or API view, uses models/serializers/forms to validate and persist data, and may trigger signals or external calls. The response then renders a role-specific dashboard or returns JSON. In diagram terms, the most important boundaries are: browser/API client → Django core/auth → domain app → database, with selected side paths to notifications, billing, and OpenFDA.

Main entry points: [`remedium_hms/urls.py`](https://github.com/neoastra303/remedium-hms/blob/main/remedium_hms/urls.py) (Root routing), [`patients`](https://github.com/neoastra303/remedium-hms/tree/main/patients) (Patients), [`staff`](https://github.com/neoastra303/remedium-hms/tree/main/staff) (Staff), [`templates`](https://github.com/neoastra303/remedium-hms/tree/main/templates) (Shared UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_platform["Platform"]
  node_n_project["Django app<br/>[settings.py]"]
  node_n_urls["Root routing<br/>[urls.py]"]
  node_n_core[("Core platform<br/>shared platform")]
  node_n_notifications["Notifications<br/>event alerts"]
  node_n_integration[("Integrations<br/>external boundary")]
end

subgraph group_grp_clinical["Clinical"]
  node_n_patients[("Patients<br/>clinical core")]
  node_n_appointments[("Appointments<br/>scheduling")]
  node_n_records[("Medical records<br/>encounters")]
  node_n_monitoring[("Care monitoring<br/>vitals")]
  node_n_lab[("Laboratory<br/>lab workflow")]
  node_n_surgery[("Surgery<br/>surgical cases")]
end

subgraph group_grp_ops["Operations"]
  node_n_billing[("Billing<br/>invoicing")]
  node_n_pharmacy[("Pharmacy<br/>dispensing")]
  node_n_inventory[("Inventory<br/>stock control")]
  node_n_hospital[("Hospital ops<br/>wards and rooms")]
  node_n_staff[("Staff<br/>personnel")]
  node_n_openfda(("OpenFDA<br/>external service<br/>[openfda_service.py]"))
end

subgraph group_grp_surfaces["Delivery"]
  node_n_templates["Shared UI<br/>templates"]
  node_n_static["Static assets<br/>frontend assets"]
  node_n_api["REST API<br/>api surface<br/>[openapi-schema.yml]"]
end

node_n_urls -->|"routes"| node_n_patients
node_n_urls -->|"routes"| node_n_appointments
node_n_urls -->|"routes"| node_n_records
node_n_urls -->|"routes"| node_n_monitoring
node_n_urls -->|"routes"| node_n_lab
node_n_urls -->|"routes"| node_n_surgery
node_n_urls -->|"routes"| node_n_billing
node_n_urls -->|"routes"| node_n_pharmacy
node_n_urls -->|"routes"| node_n_inventory
node_n_urls -->|"routes"| node_n_hospital
node_n_urls -->|"routes"| node_n_staff
node_n_urls -->|"routes"| node_n_notifications
node_n_urls -->|"routes"| node_n_integration
node_n_core -->|"renders"| node_n_templates
node_n_core -->|"authz"| node_n_patients
node_n_core -->|"roles"| node_n_staff
node_n_templates -->|"UI"| node_n_patients
node_n_templates -->|"UI"| node_n_appointments
node_n_templates -->|"UI"| node_n_billing
node_n_static -->|"assets"| node_n_templates
node_n_api -->|"serializes"| node_n_core
node_n_patients -->|"linked by"| node_n_appointments
node_n_patients -->|"linked by"| node_n_records
node_n_patients -->|"linked by"| node_n_monitoring
node_n_patients -->|"linked by"| node_n_lab
node_n_patients -->|"linked by"| node_n_surgery
node_n_patients -->|"charges"| node_n_billing
node_n_patients -->|"prescribes"| node_n_pharmacy
node_n_patients -->|"admit"| node_n_hospital
node_n_patients -->|"schedule"| node_n_appointments
node_n_staff -->|"availability"| node_n_appointments
node_n_staff -->|"assigns"| node_n_surgery
node_n_staff -->|"operates"| node_n_hospital
node_n_staff -.->|"administers"| node_n_billing
node_n_billing -.->|"costs"| node_n_inventory
node_n_pharmacy -->|"calls"| node_n_openfda
node_n_notifications -.->|"signals"| node_n_core
node_n_integration -.->|"boundary"| node_n_pharmacy

click node_n_project "https://github.com/neoastra303/remedium-hms/blob/main/remedium_hms/settings.py"
click node_n_urls "https://github.com/neoastra303/remedium-hms/blob/main/remedium_hms/urls.py"
click node_n_core "https://github.com/neoastra303/remedium-hms/tree/main/core"
click node_n_templates "https://github.com/neoastra303/remedium-hms/tree/main/templates"
click node_n_static "https://github.com/neoastra303/remedium-hms/tree/main/static"
click node_n_api "https://github.com/neoastra303/remedium-hms/blob/main/openapi-schema.yml"
click node_n_patients "https://github.com/neoastra303/remedium-hms/tree/main/patients"
click node_n_appointments "https://github.com/neoastra303/remedium-hms/tree/main/appointments"
click node_n_records "https://github.com/neoastra303/remedium-hms/tree/main/medical_records"
click node_n_monitoring "https://github.com/neoastra303/remedium-hms/tree/main/care_monitoring"
click node_n_lab "https://github.com/neoastra303/remedium-hms/tree/main/laboratory"
click node_n_surgery "https://github.com/neoastra303/remedium-hms/tree/main/surgery"
click node_n_billing "https://github.com/neoastra303/remedium-hms/tree/main/billing"
click node_n_pharmacy "https://github.com/neoastra303/remedium-hms/tree/main/pharmacy"
click node_n_inventory "https://github.com/neoastra303/remedium-hms/tree/main/inventory"
click node_n_hospital "https://github.com/neoastra303/remedium-hms/tree/main/hospital"
click node_n_staff "https://github.com/neoastra303/remedium-hms/tree/main/staff"
click node_n_notifications "https://github.com/neoastra303/remedium-hms/tree/main/notifications"
click node_n_integration "https://github.com/neoastra303/remedium-hms/tree/main/integration"
click node_n_openfda "https://github.com/neoastra303/remedium-hms/blob/main/pharmacy/openfda_service.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_project,node_n_urls,node_n_core,node_n_notifications,node_n_integration toneBlue
class node_n_patients,node_n_appointments,node_n_records,node_n_monitoring,node_n_lab,node_n_surgery toneAmber
class node_n_billing,node_n_pharmacy,node_n_inventory,node_n_hospital,node_n_staff,node_n_openfda toneMint
class node_n_templates,node_n_static,node_n_api toneRose
```

## Components

### Platform

Shared Django foundation, auth, routing, and presentation plumbing.

- [Django app](https://github.com/neoastra303/remedium-hms/blob/main/remedium_hms/settings.py): project · Single Django monolith running all hospital domains in one process and database. · `remedium_hms/settings.py`
- [Root routing](https://github.com/neoastra303/remedium-hms/blob/main/remedium_hms/urls.py): routing · Central URL dispatcher that fans requests into app-specific views and APIs. · `remedium_hms/urls.py`
- [Core platform](https://github.com/neoastra303/remedium-hms/tree/main/core): shared platform · RBAC, dashboards, audit UI, serializer helpers, context processors, and setup commands. · `core`
- [Notifications](https://github.com/neoastra303/remedium-hms/tree/main/notifications): event alerts · User notifications generated from signals and workflow events. · `notifications`
- [Integrations](https://github.com/neoastra303/remedium-hms/tree/main/integration): external boundary · External integration metadata and API keys for third-party connections. · `integration`

### Clinical

Patient-centered care workflow and clinical records.

- [Patients](https://github.com/neoastra303/remedium-hms/tree/main/patients): clinical core · Primary clinical record and anchor entity for downstream workflows. · `patients`
- [Appointments](https://github.com/neoastra303/remedium-hms/tree/main/appointments): scheduling · Scheduling, queueing, and conflict-aware booking workflow. · `appointments`
- [Medical records](https://github.com/neoastra303/remedium-hms/tree/main/medical_records): encounters · Encounters and patient documents that capture care history. · `medical_records`
- [Care monitoring](https://github.com/neoastra303/remedium-hms/tree/main/care_monitoring): vitals · Care notes and vital trends used for ongoing observation. · `care_monitoring`
- [Laboratory](https://github.com/neoastra303/remedium-hms/tree/main/laboratory): lab workflow · Lab tests and result entry for diagnostic workflows. · `laboratory`
- [Surgery](https://github.com/neoastra303/remedium-hms/tree/main/surgery): surgical cases · Surgical case tracking and procedure workflow. · `surgery`

### Operations

Revenue, pharmacy, inventory, facilities, and staff operations.

- [Billing](https://github.com/neoastra303/remedium-hms/tree/main/billing): invoicing · Invoices, payments, and invoice numbering. · `billing`
- [Pharmacy](https://github.com/neoastra303/remedium-hms/tree/main/pharmacy): dispensing · Prescriptions and dispense workflow, including external drug lookup. · `pharmacy`
- [Inventory](https://github.com/neoastra303/remedium-hms/tree/main/inventory): stock control · Stock items and cost tracking for operational supplies. · `inventory`
- [Hospital ops](https://github.com/neoastra303/remedium-hms/tree/main/hospital): wards and rooms · Wards, rooms, services, and occupancy management. · `hospital`
- [Staff](https://github.com/neoastra303/remedium-hms/tree/main/staff): personnel · Personnel, shifts, availability, and user-linked staffing data. · `staff`
- [OpenFDA](https://github.com/neoastra303/remedium-hms/blob/main/pharmacy/openfda_service.py): external service · Drug-data lookup used by pharmacy through an outbound API call. · `pharmacy/openfda_service.py`

### Delivery

Primary user-facing and API delivery surfaces.

- [Shared UI](https://github.com/neoastra303/remedium-hms/tree/main/templates): templates · Base templates, dashboards, partials, and auth pages shared across the app. · `templates`
- [Static assets](https://github.com/neoastra303/remedium-hms/tree/main/static): frontend assets · Shared CSS and JavaScript used by the server-rendered UI. · `static`
- [REST API](https://github.com/neoastra303/remedium-hms/blob/main/openapi-schema.yml): api surface · Versioned API exposure documented in the OpenAPI schema. · `openapi-schema.yml`

## Connections

- Root routing → Patients: routes · Root URLs dispatch into patient workflows.
- Root routing → Appointments: routes · Root URLs dispatch into scheduling workflows.
- Root routing → Medical records: routes · Root URLs dispatch into record workflows.
- Root routing → Care monitoring: routes · Root URLs dispatch into monitoring workflows.
- Root routing → Laboratory: routes · Root URLs dispatch into lab workflows.
- Root routing → Surgery: routes · Root URLs dispatch into surgical workflows.
- Root routing → Billing: routes · Root URLs dispatch into billing workflows.
- Root routing → Pharmacy: routes · Root URLs dispatch into pharmacy workflows.
- Root routing → Inventory: routes · Root URLs dispatch into inventory workflows.
- Root routing → Hospital ops: routes · Root URLs dispatch into hospital operations workflows.
- Root routing → Staff: routes · Root URLs dispatch into staffing workflows.
- Root routing → Notifications: routes · Root URLs dispatch into notification views.
- Root routing → Integrations: routes · Root URLs dispatch into integration administration.
- Core platform → Shared UI: renders · Core provides shared dashboard and audit templates.
- Core platform → Patients: authz · Core permissions and role groups govern access to patient data.
- Core platform → Staff: roles · Core setup commands seed role-based users and groups.
- Shared UI → Patients: UI · Shared templates frame patient-facing screens.
- Shared UI → Appointments: UI · Shared templates frame scheduling screens.
- Shared UI → Billing: UI · Shared templates frame billing screens.
- Static assets → Shared UI: assets · Static JavaScript and CSS support the shared template UI.
- REST API → Core platform: serializes · API layer relies on shared serializer helpers and auth boundary.
- Patients → Appointments: linked by · Appointments reference patients as the primary clinical subject.
- Patients → Medical records: linked by · Encounters and documents are organized around patients.
- Patients → Care monitoring: linked by · Care notes and vital trends are tracked per patient.
- Patients → Laboratory: linked by · Lab orders and results are associated with patients.
- Patients → Surgery: linked by · Surgical cases are tied back to patients.
- Patients → Billing: charges · Billing records use patient context for invoices and payments.
- Patients → Pharmacy: prescribes · Prescriptions are created in the context of patient care.
- Patients → Hospital ops: admit · Admissions and occupancy connect patients to wards and rooms.
- Patients → Appointments: schedule · Scheduling workflows begin from patient records.
- Staff → Appointments: availability · Staff availability influences appointment booking and queues.
- Staff → Surgery: assigns · Surgeons and support staff are assigned to surgical cases.
- Staff → Hospital ops: operates · Staff manage wards, rooms, and service operations.
- Staff → Billing: administers · Staff roles support billing and operational workflows.
- Billing → Inventory: costs · Operational consumption and supply costs inform revenue work.
- Pharmacy → OpenFDA: calls · Pharmacy reaches out to OpenFDA for drug-related data.
- Notifications → Core platform: signals · Notification generation is driven by application events and shared authorization context.
- Integrations → Pharmacy: boundary · Integration metadata supports external service touchpoints.