flows; playbooks;

deployments/hmis/playbooks/billing-and-payment.mdx

@@ -0,0 +1,76 @@
+---
+sidebar_position: 3
+---
+
+# Billing and payment
+
+Turn the services a patient received into a priced invoice and a collected payment. This playbook combines the **service request**, **charge item**, and **discount** flows with the **billing → invoice → payment** flow run by front-desk and billing staff.
+
+## Flows involved
+
+| Order | Flow | Purpose |
+| --- | --- | --- |
+| 1 | Add a service request *(coming soon)* | Capture the billable service rendered |
+| 2 | Link a charge item to a schedule *(coming soon)* | Attach the priced item to the appointment/service |
+| 3 | Create a discount code & component *(coming soon)* | Apply staff or scheme concessions |
+| 4 | Build billing, create invoice, collect payment *(coming soon)* | Generate and settle the invoice |
+
+## Happy path
+
+1. As services are delivered, **service requests** are raised against the patient's encounter or appointment.
+2. Each chargeable service has a **charge item** linked so a price is attached.
+3. Billing **assembles the open charges** for the encounter into a draft invoice.
+4. Any applicable **discount component** (staff, scheme, camp) is applied.
+5. The **invoice is generated**, payment is collected, and a receipt is issued.
+
+## Edge cases
+
+### Discount or concession applies
+
+**Symptom:** Patient is staff, or covered by a scheme/camp rate.
+
+**Action:**
+
+1. Apply the relevant **discount code / component** before finalising.
+2. Record the authorisation/reason where the facility requires it; the applied discount is retained on the invoice.
+
+### Partial payment / instalment
+
+**Symptom:** Patient cannot settle the full amount at once.
+
+**Action:**
+
+1. Collect the partial amount against the invoice; the balance remains outstanding.
+2. Subsequent collections are recorded against the same invoice until settled.
+
+### Charge added after invoicing
+
+**Symptom:** A late service (e.g. an add-on test) lands after the invoice was raised.
+
+**Action:**
+
+1. Raise a supplementary charge / invoice rather than reopening a settled one.
+2. Reconcile both invoices on the patient's account.
+
+### Refund or cancellation
+
+**Symptom:** A billed service is cancelled or overcharged.
+
+**Action:**
+
+1. Process the reversal against the original invoice with a reason.
+2. Keep the original and reversal entries for audit.
+
+## Roles
+
+| Role | Can |
+| --- | --- |
+| Service desk / nurse | Raise service requests |
+| Billing clerk | Build invoices, apply charge items, collect payment |
+| Billing supervisor | Approve discounts, process refunds |
+
+## Related
+
+- Flow: Add a service request *(coming soon)*
+- Flow: Building staff billing, invoice creation, and payment collection *(coming soon)*
+- Playbook: [Pharmacy dispensing](./pharmacy-dispensing) and [Lab diagnostics](./lab-diagnostics) — common sources of billable charges

deployments/hmis/playbooks/facility-setup.mdx

@@ -0,0 +1,79 @@
+---
+sidebar_position: 5
+---
+
+# Facility setup
+
+Stand up a new health facility in Care from an empty shell to ready-to-admit. This playbook sequences the facility, location, department, bed, user, and ABDM linking flows that an administrator runs once per site.
+
+## Flows involved
+
+| Order | Flow | Purpose |
+| --- | --- | --- |
+| 1 | Create & configure a new health facility *(coming soon)* | Register the facility and its core settings |
+| 2 | Add and organize facility locations *(coming soon)* | Build the location hierarchy (wards, rooms) |
+| 3 | Link multiple departments to a location *(coming soon)* | Map departments onto locations |
+| 4 | Create multiple beds in a location *(coming soon)* | Add bed capacity to wards/rooms |
+| 5 | Create a department & link users *(coming soon)* | Set up departments and staff access |
+| 6 | Link HFID for ABDM & generate QR *(coming soon)* | Register the facility with ABDM |
+
+## Happy path
+
+1. Administrator **creates and configures the facility** (name, type, address, core settings).
+2. The **location hierarchy** is built out — buildings, wards, rooms.
+3. **Departments are created** and **linked to locations**.
+4. **Beds are added** to the relevant locations to establish capacity.
+5. **Users are created and linked** to their departments with appropriate roles.
+6. The facility's **HFID is linked for ABDM** and its **QR code generated** for national-network interoperability.
+
+## Edge cases
+
+### Phased go-live
+
+**Symptom:** Only some wards open initially.
+
+**Action:**
+
+1. Configure live locations/beds first; leave the rest inactive.
+2. Activate additional capacity as it comes online — no need to re-create the facility.
+
+### Department spans multiple locations
+
+**Symptom:** One department operates across several wards/floors.
+
+**Action:**
+
+1. Link the department to **each** location it serves.
+2. Assign users once at the department level rather than per location.
+
+### Bed re-numbering / re-org
+
+**Symptom:** Wards are renumbered after go-live.
+
+**Action:**
+
+1. Update the location/bed labels in place.
+2. Avoid deleting occupied beds; move patients first to preserve encounter history.
+
+### ABDM not yet provisioned
+
+**Symptom:** HFID/QR step blocked pending ABDM registration.
+
+**Action:**
+
+1. Complete clinical setup (steps 1–5) so the facility is operational.
+2. Return to **HFID linking and QR generation** once ABDM credentials are available.
+
+## Roles
+
+| Role | Can |
+| --- | --- |
+| Facility administrator | Create facility, locations, departments, beds |
+| User administrator | Create and link users, assign roles |
+| Integrations admin | Link HFID, generate ABDM QR |
+
+## Related
+
+- Flow: Create and configure a new health facility *(coming soon)*
+- Flow: Add and organize facility locations *(coming soon)*
+- Flow: Link HFID in Care for ABDM and generate QR *(coming soon)*

deployments/hmis/playbooks/ip-rounds.mdx

@@ -0,0 +1,75 @@
+---
+sidebar_position: 6
+---
+
+# IP rounds
+
+Run a ward round on an admitted patient: open the active encounter, explore the patient's record, and document findings through clinical forms. This playbook covers **accessing**, **exploring**, and **form filling** on an existing inpatient encounter — it does not create or close the encounter.
+
+## Flows involved
+
+| Order | Flow | Purpose |
+| --- | --- | --- |
+| 1 | Access a patient encounter *(coming soon)* | Open the patient's active admission |
+| 2 | View symptoms, diagnosis, prescriptions & previous encounters *(coming soon)* | Explore the clinical picture before deciding |
+| 3 | Submit clinical forms *(coming soon)* | Record round findings and assessments |
+
+## Happy path
+
+1. On the round, the clinician **accesses the patient's active encounter** from the ward/bed list.
+2. They **explore the record** — current symptoms, diagnoses, active prescriptions, allergies, recent results, and previous encounters — to build the picture.
+3. They **submit the relevant clinical form(s)** to document the day's assessment, observations, and plan.
+4. New orders (medication, lab) flow out to the [pharmacy](./pharmacy-dispensing) and [lab](./lab-diagnostics) playbooks; the encounter stays open for the next round.
+
+## Edge cases
+
+### Patient transferred between beds/wards
+
+**Symptom:** Bed or location changed since the last round.
+
+**Action:**
+
+1. The encounter follows the patient; confirm the **current bed/location** before documenting.
+2. If the assignment looks stale, update it before charting.
+
+### Information from a prior admission needed
+
+**Symptom:** History lives in an earlier encounter.
+
+**Action:**
+
+1. Open **previous encounters** read-only to review.
+2. Document fresh findings on the **current** encounter — do not edit the closed one.
+
+### Form started but round interrupted
+
+**Symptom:** The clinician is pulled away mid-form.
+
+**Action:**
+
+1. Save progress; submit when complete so the record reflects a finished assessment.
+2. Avoid leaving partially-entered clinical data unsubmitted across shifts.
+
+### Multiple clinicians on the same patient
+
+**Symptom:** Consultant and resident both document.
+
+**Action:**
+
+1. Each submits their own form entry; authorship is retained per submission.
+2. Reconcile conflicting plans verbally, then record the agreed plan.
+
+## Roles
+
+| Role | Can |
+| --- | --- |
+| Clinician / consultant | Access encounter, explore record, submit clinical forms, place orders |
+| Nurse | View encounter, record observations and administration |
+| Read-only / allied staff | View the record without editing clinical data |
+
+## Related
+
+- Flow: Submit clinical forms *(coming soon)*
+- Flow: View previous patient encounters *(coming soon)*
+- Playbook: [OP consultation](./op-consultation) — the outpatient counterpart
+- Playbook: [Pharmacy dispensing](./pharmacy-dispensing), [Lab diagnostics](./lab-diagnostics) — where round orders go

deployments/hmis/playbooks/lab-diagnostics.mdx

@@ -0,0 +1,79 @@
+---
+sidebar_position: 2
+---
+
+# Lab diagnostics
+
+Take a lab investigation from the clinician's order all the way to a published, patient-visible report. This playbook chains the **lab test request** flow with the laboratory's **review → collect → result → publish** flow, and is owned jointly by clinicians and lab staff.
+
+## Flows involved
+
+| Order | Flow | Purpose |
+| --- | --- | --- |
+| 1 | Raise a lab test request *(coming soon)* | Clinician orders the investigation from the encounter |
+| 2 | Review service request *(coming soon)* | Lab triages and accepts the order |
+| 3 | Specimen collection *(coming soon)* | Sample is drawn, labelled, and logged |
+| 4 | Result entry *(coming soon)* | Technician records values against the test |
+| 5 | Report publication *(coming soon)* | Verified report is released to the record |
+
+## Happy path
+
+1. During an [encounter](/docs/flows/clinical/create-patient), the clinician raises a **lab test request** for the required panel.
+2. The order appears in the lab's service-request queue; lab staff **review and accept** it.
+3. **Specimen is collected**, labelled with the request identifier, and marked collected in Care.
+4. The technician performs the test and **enters results** against each parameter.
+5. A reviewer **verifies and publishes** the report; it becomes visible on the patient record and to the ordering clinician.
+
+## Edge cases
+
+### Sample rejected or insufficient
+
+**Symptom:** Specimen is haemolysed, clotted, or below required volume.
+
+**Action:**
+
+1. Mark the specimen rejected with a reason.
+2. Notify the ordering team to **re-collect**; the original request stays open or is re-issued per lab policy.
+3. Do not enter results against a rejected specimen.
+
+### STAT / urgent order
+
+**Symptom:** Clinician flags the order as urgent.
+
+**Action:**
+
+1. Order is prioritised in the review queue.
+2. Provisional results may be communicated verbally; the **published report remains the system of record**.
+
+### Result amendment after publication
+
+**Symptom:** An error is found in an already-published value.
+
+**Action:**
+
+1. Issue a corrected report rather than editing silently.
+2. The amendment is retained in history so the original and corrected values are both auditable.
+
+### Add-on test on an existing sample
+
+**Symptom:** Clinician wants another test on a sample already collected.
+
+**Action:**
+
+1. Raise a new lab test request and link it to the existing specimen where the analyte allows.
+2. If the sample type or stability does not permit it, a fresh collection is required.
+
+## Roles
+
+| Role | Can |
+| --- | --- |
+| Clinician | Raise requests, view published reports |
+| Lab reception / phlebotomist | Review requests, collect and log specimens |
+| Lab technician | Enter results |
+| Lab reviewer / pathologist | Verify and publish reports, issue amendments |
+
+## Related
+
+- Flow: Raise a lab test request *(coming soon)*
+- Flow: Laboratory review, collection, result entry, and publication *(coming soon)*
+- Playbook: [OP consultation](./op-consultation) — where most orders originate

deployments/hmis/playbooks/op-consultation.mdx

@@ -0,0 +1,77 @@
+---
+sidebar_position: 7
+---
+
+# OP consultation
+
+Run an outpatient consultation end to end: open a fresh encounter for the visit, document the consultation through clinical forms, and complete the encounter. This playbook covers **creating**, **form filling**, and **completing** an OP encounter.
+
+## Flows involved
+
+| Order | Flow | Purpose |
+| --- | --- | --- |
+| 1 | Create an encounter *(coming soon)* | Open today's OP visit for the patient |
+| 2 | Submit clinical forms *(coming soon)* | Document history, examination, and plan |
+| 3 | Update symptoms, diagnosis & prescribe *(coming soon)* | Record the clinical decision |
+| 4 | Mark the encounter complete *(coming soon)* | Close the visit and generate the summary |
+
+## Happy path
+
+1. The clinician **creates an OP encounter** for the patient at check-in (registering the patient first via [create patient](/docs/flows/clinical/create-patient) if they are new).
+2. They **submit the consultation form(s)** — presenting complaint, history, examination.
+3. They record the decision: **update symptoms and diagnosis**, and **prescribe** any medication or **order** labs.
+4. They **mark the encounter complete**; a treatment/visit summary can then be generated and printed for the patient.
+
+## Edge cases
+
+### Walk-in vs scheduled
+
+**Symptom:** Patient arrives without an appointment.
+
+**Action:**
+
+1. Create the encounter directly for a walk-in; link to the appointment if one exists.
+2. Scheduled patients are checked in first, then the encounter is opened.
+
+### Follow-up referencing a prior visit
+
+**Symptom:** This visit continues a previous problem.
+
+**Action:**
+
+1. Open **previous encounters** read-only for context.
+2. Document on the **new** encounter; carry forward the diagnosis rather than editing the old visit.
+
+### Referral / needs admission
+
+**Symptom:** The OP visit escalates to inpatient or specialist care.
+
+**Action:**
+
+1. Complete the OP encounter with the decision documented.
+2. Hand over to admission or referral; the IP stay is tracked under [IP rounds](./ip-rounds).
+
+### Completed in error
+
+**Symptom:** Encounter marked complete prematurely.
+
+**Action:**
+
+1. Reopen per facility policy to add the missing documentation, then re-complete.
+2. Avoid creating a duplicate encounter for the same visit.
+
+## Roles
+
+| Role | Can |
+| --- | --- |
+| Clinician | Create encounter, submit forms, diagnose, prescribe, complete |
+| Nurse | Record vitals/observations, assist documentation |
+| Front desk | Check-in, link appointment to encounter |
+
+## Related
+
+- Flow: Create an encounter *(coming soon)*
+- Flow: Submit clinical forms *(coming soon)*
+- Flow: Generate treatment summary *(coming soon)*
+- Playbook: [IP rounds](./ip-rounds) — the inpatient counterpart
+- Playbook: [Pharmacy dispensing](./pharmacy-dispensing), [Lab diagnostics](./lab-diagnostics) — where consultation orders go