neoastra303/remedium-hms

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.