Patient Management Module
Relevant source files
The following files were used as context for generating this wiki page:
The Patient Management Module is a core component of the Care Ops Frontend, built using Backbone, Marionette, and Handlebars. It serves as the primary interface for clinicians to manage patient lifecycles, clinical workflows (flows), and individual tasks (actions). The module facilitates patient registration, real-time status monitoring through dashboards, and historical review via an archive system.
The module is architected to handle complex data relationships between patients, the clinicians who own their care, and the programs that define their clinical paths. It utilizes a centralized data access layer via the entities-service and provides real-time updates through a WebSocket-based notification system.
Sources: CLAUDE.md:12-16, README.md:95-103, test/integration/patients/patient/dashboard.js
Core Module Components
The module is divided into several high-level functional areas that manage specific aspects of the patient record and clinical workflow.
Patient Dashboard
The dashboard provides a consolidated view of a patient's active care. It primarily lists "Workflows" (Flows) and "Actions" (Tasks) that are currently in progress or pending. It allows clinicians to quickly update the state of actions, assign owners (clinicians or teams), and modify due dates.
Sources: test/integration/patients/patient/dashboard.js:46-52, src/js/i18n/en-US.yml:256-265
Patient Sidebar
A persistent UI component that displays critical patient metadata and configurable widgets. It includes:
- Demographics: Name, Date of Birth, Age, and Sex.
- Status Widgets: Displays if a patient is Active, Inactive, or Archived.
- Dynamic Widgets: Configurable sections such as MRN identifiers, form links, and custom Handlebars templates.
- Management Menu: Options to edit patient details, activate/inactivate, or archive the patient.
Sources: test/integration/patients/patient/sidebar.js:33-80, src/js/i18n/en-US.yml:267-279
Patient Archive
The archive section maintains a record of completed or terminated clinical activities. It lists actions and flows set to terminal states like "Done," "Unable to Complete," or "Transferred."
Sources: test/integration/patients/patient/archive.js:101-105, src/js/i18n/en-US.yml:251-255
Data Architecture and Relationships
The module manages three primary entities: Patients, Flows, and Actions.
- Flows: Represent clinical programs or workflows (e.g., "Health Risk Assessment").
- Actions: Specific tasks within a flow or standalone tasks (e.g., "Call Patient").
Entity Relationship Diagram
This diagram shows how clinical tasks and workflows are organized under a patient and assigned to clinical staff.
Clinical Operations and Workflow
Clinicians interact with the module to move patients through clinical pathways. This involves creating new actions, completing forms, and managing ownership.
Patient Creation Flow
New patients can be added manually through a modal interface, provided the workspace settings allow it (manual_patient_creation: true).
State Management
Actions and flows move through a lifecycle defined by states. Common states include:
- Todo: Task pending.
- In Progress / Started: Task active.
- Done: Task completed.
- Unable to Complete: Terminal state for failed tasks.
Sources: src/js/i18n/en-US.yml:345-350, test/integration/patients/patient/dashboard.js:101-110
Technical Implementation Details
Real-time Synchronization
The module uses WebSockets to maintain UI consistency across different clinician sessions. When a resource is modified (e.g., an action name is changed or a comment is added), a WebSocket notification is broadcast.
| Category | Description | Resource Type |
|---|---|---|
NameChanged | Updates the name of a flow or action | Flows, Actions |
StateChanged | Updates the status (e.g., to Done) | Flows, Actions |
OwnerChanged | Changes the clinician or team owner | Flows, Actions |
AttachmentAdded | Notifies that a file was uploaded | Actions |
ResourceDeleted | Removes the item from the list | Flows, Actions |
Sources: test/integration/patients/patient/patient-flow.js:108-250, test/integration/patients/patient/dashboard.js:460-550
Security and Permissions
The module enforces granular permissions for management actions:
work:owned:manage: Allows clinicians to manage actions they personally own.work:team:manage: Allows managers to manage actions owned by their team.- Read-only Views: When permissions are insufficient, UI elements like "Save" buttons and dropdowns are disabled or hidden.
Sources: test/integration/patients/patient/patient-flow.js:525-560, src/js/i18n/en-US.yml:118-121
Summary
The Patient Management Module provides a Backbone/Marionette-driven environment for clinical coordination. By integrating demographic data, program-driven workflows, and real-time state synchronization, it enables clinicians to manage patient care efficiently within the Care Ops ecosystem.
Sources: README.md:95-110, CLAUDE.md:5-15