diff --git a/docs/care/HMIS/Billing/Account.md b/docs/care/HMIS/Billing/Account.md new file mode 100644 index 0000000..4b3fec4 --- /dev/null +++ b/docs/care/HMIS/Billing/Account.md @@ -0,0 +1,172 @@ +# Account + +## Summary + +The **Account** module manages financial accounts that accumulate charges and payments for a patient or specific purpose (e.g. an inpatient stay or service request cost). An Account serves as a “billing bucket” or ledger for tracking healthcare costs over time. Charges (for services or items) are applied to an Account, and payments or adjustments credit the Account. In essence, it is a central record against which charges, payments, and adjustments are recorded. This allows the system to keep a running total of what a patient (or their insurance) owes. Accounts contain information about who the account is for (the patient or entity) and who is responsible for paying the balance (such as insurance or a guarantor). _For example, when a patient is admitted, an Account is opened to track all charges during that hospitalization, and later, an invoice will be generated from this account._ + +:::info Note for Developers +The Account concept aligns with the FHIR **Account** resource, providing a tool to track values accrued for a particular purpose in healthcare billing. While an account will have a running balance conceptually, it typically does **not** store a live balance field. Instead, the current balance is computed from all associated charges and payments and cached. The system will provide a function to calculate the balance on demand by summing charges minus payments, you can use the `calculated_at` field to track when the balance was last computed and ensure data consistency. +::: + +## Schema Definition + +```json +{ + "id": "", // Internal Identifier + "status": "", // active | inactive | entered-in-error | on-hold | unknown + "billing_status": "", // Bound to https://build.fhir.org/valueset-account-billing-status.html + "name": "", // Human-readable label + "patient": "", // The entity that caused the expenses + "facility": "", // Facility where this Account is created + "service_period": "Period", // Transaction window + "description": "", // Explanation of purpose/use + "balance": [ + { + "aggregate": "", // Patient or Insurer - Bound to https://build.fhir.org/valueset-account-aggregate.html + "amount": { + "value": "", // Numerical value (with implicit precision) + "currency": "" // ISO 4217 Currency Code + } // Calculated amount + } + ], + "calculated_at": "" // Time the balance amount was calculated +} +``` + +## Core Data Structure + +### Essential Fields + +| Field | Description | Technical Notes | +| ------------------ | ------------------------------------------------------------- | --------------------------------------------------------------------- | +| **id** | Internal system identifier for the Account | Primary key, auto-generated | +| **name** | Human-readable label (e.g., "John Doe – 2025 Inpatient Stay") | Helpful for staff identification | +| **patient** | Foreign key reference to the patient | Only charges for this patient should be applied to this Account | +| **facility** | Reference to the healthcare facility | Used for organizational tracking and reporting | +| **status** | Current lifecycle state of the Account | Controls available operations (see Status section) | +| **billing_status** | FHIR-compliant billing status code | Provides additional context beyond basic status | +| **service_period** | Date range covered by the Account | Typically maps to admission/discharge dates or specific billing cycle | +| **description** | Markdown-formatted explanation of purpose | Provides additional context for staff | +| **balance** | Array of calculated balances by payer type | Segmented by responsible party (patient vs. insurer) | +| **calculated_at** | Timestamp of last balance calculation | Ensures data freshness awareness | + +### Account Status Lifecycle + +| Status Value | Description | System Behavior | +| -------------------- | -------------------------------- | ---------------------------------------------------- | +| **active** | Account is open and operational | Allows new charges, payments, and invoice generation | +| **on_hold** | Account is temporarily suspended | Blocks new charges and invoices; requires resolution | +| **inactive** | Account is permanently closed | Prevents all new transactions; read-only mode | +| **entered_in_error** | Account was created by mistake | Excluded from billing processes and reporting | + +### Billing Status Values + +| Billing Status | Description | Typical Usage | +| -------------------------- | --------------------------------------------------- | ---------------------------------- | +| **open** | Account is actively receiving charges | Default for new accounts | +| **carecomplete_notbilled** | Care is complete but billing process hasn't started | Transitional state after discharge | +| **billing** | Invoicing and payment collection in progress | Active billing cycle | +| **closed_baddebt** | Account closed due to uncollectible debt | After collection attempts failed | +| **closed_voided** | Account canceled/voided | For erroneously created accounts | +| **closed_completed** | Account fully settled and closed | After full payment received | +| **closed_combined** | Account merged with another account | After account consolidation | + +### Balance Aggregate Types + +| Aggregate Type | Description | Purpose | +| -------------- | --------------------------------------------- | ----------------------------------------------- | +| **patient** | Portion of balance patient is responsible for | Track patient's direct financial responsibility | +| **insurance** | Portion of balance expected from insurance | Track expected insurance payments | +| **total** | Combined total balance | Overall account balance | + +## Business Logic Highlights + +- An account can accumulate many **Charge Items** (individual billed services) over time. Each Charge Item references the Account it belongs to. The Account itself does not list every charge internally; instead, charges “point” to the account. The system can retrieve all charges linked to a given account to compute the balance or prepare an invoice. +- **Adding Charges:** Only allowed on active accounts. If a user tries to add a charge to an inactive/on-hold account, the system should prevent it and alert the user. +- **Account Closure:** Typically done when the patient’s episode of care is complete and billing is finalized. The staff will mark the account as **inactive** (closed) after all invoices are issued and the balance is zero. The system might enforce that an account with outstanding balance cannot be closed. If closure is forced, it can only be done at managerial level. _(Developer note: implement a check that blocks closing an account if any unpaid invoices or unbilled charges exist.)_ +- **On-hold Behavior:** Placing an account on hold might be used if, for example, insurance eligibility is in question or a billing dispute arises. In this state, new charges can be collected in the background but not officially billed until hold is released. The UI should visibly flag held accounts, and possibly require a note or reason for hold. + +```mermaid +flowchart TD + A[Account Creation] --> B{Set Initial Status} + B -->|Default| C[Active] + + C --> D{Account Management Options} + D -->|Add Charge| E[Validate Charge] + D -->|Record Payment| F[Process Payment] + D -->|Generate Invoice| G[Create Invoice] + D -->|Change Status| H{New Status} + + E --> E1{Is Account Active?} + E1 -->|Yes| E2[Create Charge Record] + E1 -->|No| E3[Error: Cannot add charge] + E2 --> E4[Update Account Balance] + + F --> F1[Create Payment Record] + F1 --> F2[Update Account Balance] + + G --> G1{Is Account Active?} + G1 -->|Yes| G2[Generate Invoice from Charges] + G1 -->|No| G3[Error: Cannot invoice] + + H -->|On-Hold| I[Verify Permission] + H -->|Inactive| J[Validate for Closure] + H -->|Entered-in-Error| K[Verify Admin Permission] + + I --> I1[Require Reason Note] + I1 --> I2[Update Status to On-Hold] + I2 --> I3[Disable Billing Actions] + + J --> J1{Is Balance Zero?} + J1 -->|Yes| J2[Update Status to Inactive] + J1 -->|No| J3{Manager Override?} + J3 -->|Yes| J4[Update with Override Note] + J3 -->|No| J5[Error: Cannot close with balance] + + K --> K1[Mark as Error] + K1 --> K2[Remove from Billing] + + J2 --> L[Account Closed] + J4 --> L + + classDef status fill:#f9f,stroke:#333,stroke-width:2px + classDef error fill:#f66,stroke:#333,stroke-width:2px + classDef success fill:#6f6,stroke:#333,stroke-width:2px + + class C,I2,J2,J4,K1 status + class E3,G3,J5 error + class E4,F2,G2,L success +``` + +**Creating a New Account** + +Accounts can be created in two ways: + +1. Manual Creation from Patient Page +2. Automatic Creation on First Charge + +In both cases, the account becomes immediately available for billing operations once created. + +**Handling Account Holds:** + +- If an account is on hold, the UI should prominently indicate this (e.g., a banner “On Hold”). While on hold, typical billing actions might be disabled or require override: + - The “Add Charge” button might be hidden or greyed out with a tooltip “Account is on hold – cannot add charges.” + - The “Generate Invoice” action might be disabled as well. +- To remove a hold, a staff user (often with appropriate permission) would edit the account and change status back to **active**. The system might log who removed the hold and when. + +**Closing an Account (End of Cycle):** + +- When all charges have been billed and paid, or the patient’s treatment cycle is over, the account should be closed. To do this, staff edits the account and sets **Status = Inactive**. +- The system will prompt “Are you sure you want to close this account? This action will mark the account as closed and no further charges can be added.” If confirmed, and validation passes (balance is zero, etc.), the status updates to inactive. +- Once inactive, the account is essentially archived for that episode. The UI might label it as **Closed**. Staff can still view details and history, but cannot add new entries. If somehow a late charge comes in after closure, typically a new account is needed. + +**Account Balance Inquiry:** + +- At any point, staff might need to inform a patient of their current balance. The account screen’s balance is calculated from charges and payments. If the patient or billing staff want a detailed statement, they can generate an **Account Statement** (which is essentially an on-demand invoice or report of all transactions). This is usually separate from the official Invoice process, but it gives a breakdown of charges, payments, and remaining due. + +**Status Transitions:** + +- Enforce rules when updating account status: + - Only allow **inactive** if balance is 0 and no pending charges. If there is a balance, return a clear error to the UI. + - Only allow **on-hold** or **active** transitions for appropriate user roles. Possibly log these changes for audit. + - **entered-in-error** should only be used shortly after creation or if truly needed, and might require admin privileges, since it essentially invalidates the account. diff --git a/docs/care/HMIS/Billing/Billing.md b/docs/care/HMIS/Billing/Billing.md new file mode 100644 index 0000000..83a34cb --- /dev/null +++ b/docs/care/HMIS/Billing/Billing.md @@ -0,0 +1,36 @@ +# Billing + +This overview provides a **big-picture** look at how billing data and workflows are organized, from recording healthcare services to collecting payments. The subsequent pages detail each component and its usage. + +## Key Billing Concepts + +| **Concept** | **Description** | +| -------------------------- | ------------------------------------------------------------------------------------ | +| **Charge Item Definition** | Specifies billing rules and pricing for services or products. | +| **Charge Item** | Represents a specific billable service or product provided to a patient. | +| **Account** | Aggregates all financial transactions for a patient, including charges and payments. | +| **Invoice** | Formal document summarizing charges and payments, issued to request payment. | +| **Payment Reconciliation** | Process of matching received payments with billed charges to ensure accuracy. | + +## High-Level Billing Flow + +Below is a simplified look at how these pieces fit together: + +```mermaid +flowchart LR + A[Charge Item Definition
Price Catalog] --> B[Charge Item
Specific Billable Service] + B --> C[Account
Ledger for Charges/Payments] + C --> D[Invoice
Formal Bill Summarizing Charges] + D --> E[Payment Reconciliation
Payments Applied to Invoice] + E --> F[Account Updated
Balance Reduced ] +``` + +1. **Charge Item Definition**: Administrators configure pricing rules and codes. +2. **Charge Item**: When a service is provided, a charge is created for the patient's **Account**, with cost details derived from the definition. +3. **Account**: Aggregates all patient charges and payments. +4. **Invoice**: Groups outstanding charges into a final bill. Once issued, the charges become billed. +5. **Payment Reconciliation**: Records any incoming payment, updating the invoice and account balances accordingly. + +## Concept Diagram + +![Billing Concept Diagram](../../../../static/img/care/HMIS/Billing/Billing%20Concept%20Diagram.svg) diff --git a/docs/care/HMIS/Billing/ChargeItem.md b/docs/care/HMIS/Billing/ChargeItem.md new file mode 100644 index 0000000..b6ef9a1 --- /dev/null +++ b/docs/care/HMIS/Billing/ChargeItem.md @@ -0,0 +1,82 @@ +# Charge Item +A **Charge Item** is the actual **instance** of billing for a specific service or product provided to a patient. It references a **Charge Item Definition** (i.e., the priced “catalog entry”) to derive the cost, plus actual usage details (quantity, date, any overrides). Each Charge Item links to a specific **Account** (which accumulates charges for a patient or episode of care) and often to an **Encounter** (the clinical context). + +For example, if a nurse administers 2 doses of an expensive medication, the system may create a Charge Item for “Medication: XYZ” with quantity=2, referencing the relevant charge definition for medication pricing. Once a Charge Item is **billable**, it can appear on an **Invoice**. + + +## Schema Definition +```json +{ + "id": "", // Internal Identifier + "definition": "", // Definition pointing to Charge Definition + "status": "", // planned | billable | not-billable | aborted | billed | entered-in-error | unknown + "code": "", // A code that identifies the charge, like a billing code + "patient": "", // Patient Associated with the charge + "encounter": "", // Encounter associated with this ChargeItem + "facility": "", // Facility where this Charge Item is created + "quantity": "", // Quantity of which the charge item has been serviced + "unitPriceComponent": [ + "MonetaryComponent" // Unit price components + ], + "totalPriceComponent": [ + "MonetaryComponent" // Total price components + ], + "total_price": { // Total Price in Amount + "Money" + }, + "overrideReason": { // Reason for overriding the list price/factor + "text": "", + "code": "" + }, + "service": { // Why was the charged service rendered? + "resource": "", + "id": "id" + }, + "account": "", // Account to place this charge + "note": "", // Comments made about the ChargeItem + "supportingInformation": [ + { "Reference(Any)" } // Further information supporting this charge + ] +} +``` + +## Core Data Structure + +### Essential Fields + +| Field | Description | Technical Notes | +|-------|-------------|----------------| +| **id** | Internal system identifier | Primary key, auto-generated | +| **definition** | Reference to the Charge Item Definition | Links to the catalog entry for this service/item | +| **status** | Current state in the billing lifecycle | Controls whether the item can be invoiced | +| **code** | Billing code for the service | Often derived from the definition | +| **patient** | Reference to the patient | Person receiving the service | +| **encounter** | Reference to the healthcare encounter | Links to the clinical context | +| **facility** | Reference to the healthcare facility | Location where service was provided | +| **quantity** | Number of units provided | Default is 1 for most services | +| **unitPriceComponent** | Price breakdown per unit | Includes base, surcharges, discounts, taxes | +| **totalPriceComponent** | Price breakdown for all units | Unit price × quantity with all components | +| **total_price** | Final calculated amount | Sum of all price components | +| **account** | Reference to the billing account | Where this charge accumulates | + +### Status Lifecycle + +| Status Value | Description | System Behavior | +|--------------|-------------|----------------| +| **planned** | Service is scheduled but not yet provided | Not counted in account balance; not billable | +| **billable** | Service provided and ready to bill | Included in account balance; can be invoiced | +| **not-billable** | Service provided but won't be billed | Not included in account balance; excluded from invoices | +| **aborted** | Service was not completed | Not included in account balance; excluded from invoices | +| **billed** | Charge included on an invoice | Included in account balance; cannot be invoiced again | +| **entered-in-error** | Charge was created by mistake | Excluded from all calculations and invoices | + + +## User Workflows + +### Editing or Canceling a Charge +- If a charge is still **billable** (and not on an issued invoice), staff can adjust quantity, override price, or mark it **not-billable**. +- If it is **billed** (already invoiced), any correction typically requires reversing that invoice or adding a credit note. +- Marking **entered-in-error** will remove it from the account’s balance. Log who performed this action. + +### Automatic Charge Creation +- The system will automatically create charges when certain clinical events occur (e.g., lab test result posted). Staff can still review them before they become “billable.” \ No newline at end of file diff --git a/docs/care/HMIS/Billing/ChargeItemDefinition.md b/docs/care/HMIS/Billing/ChargeItemDefinition.md new file mode 100644 index 0000000..0599778 --- /dev/null +++ b/docs/care/HMIS/Billing/ChargeItemDefinition.md @@ -0,0 +1,124 @@ + +# Charge Item Definition + +A **Charge Item Definition** specifies **what** items/services can be billed and **how** pricing or conditions are applied. Think of it as the **price catalog** plus rule engine for your billing system. Each definition includes a billing code, base price or rate, plus optional surcharges, discounts, or taxes. It can also contain rules about when to apply these pricing components—for example, a certain code might only apply to patients of a specific age group, or only for inpatient encounters. + +This resource allows your HMIS to automatically derive the appropriate cost of a service or product by referencing the relevant **Charge Item Definition**. If you later update your official price list, that change is made once in the definition, and all future charges referencing it will use the updated pricing logic. Complex logic (like time-of-day surcharges, tax rules, or special discounts) can also be embedded here. + +## Schema Definition + +```json +{ + "id": "", // Internal Identifier + "version": "", // Version + "title": "", // Name for this charge item definition + "slug": "", // URL-friendly identifier + "derivedFromUri": "", // Was this from a URL + "status": "", // draft | active | retired | unknown + "facility": "", // Facility where this Charge Item Definition is created + "description": "", // Natural language description of the charge item definition + "purpose": "", // Why this charge item definition is defined + "code": "", // Billing code or product type this definition applies to + "instance": [ + { "ActivityDefinition|Medication" } // Resources this definition can apply to + ], + "propertyGroup": [{ // Group of properties which are applicable under the same conditions + "applicability": [{ // Whether or not the billing code is applicable + "condition": { "Expression" } // Boolean-valued expression + }], + "priceComponent": [{ "MonetaryComponent" }] // Components of total line item price + }] +} +``` + +### Monetary Component Definition +```json +{ + "type": "", // base | surcharge | discount | tax | informational + "code": "", // Codes to differentiate taxes, surcharges, discounts etc. + "factor": "", // Factor used for calculating this component + "amount": { + "value": "", // Numerical value (with implicit precision) + "currency": "" // ISO 4217 Currency Code + } +} +``` +## Core Data Structure + +### Essential Fields + +| Field | Description | Technical Notes | +|-------|-------------|----------------| +| **id** | Internal system identifier | Primary key, auto-generated | +| **version** | Version number of the definition | Supports tracking changes over time | +| **title** | Human-readable name of the charge item | Used in selection interfaces and reports | +| **slug** | URL-friendly identifier | Used for API endpoints and references | +| **status** | Current state of the definition | Controls whether it can be used for billing | +| **facility** | Healthcare facility reference | Used for facility-specific pricing | +| **description** | Detailed description of the charge item | Provides context for billing staff | +| **code** | Billing code or identifier | Links to standard coding systems when possible | +| **instance** | Reference to clinical resources | Shows which clinical activities can trigger this charge | +| **propertyGroup** | Container for pricing rules | Groups related pricing components | + +### Status Values + +| Status Value | Description | System Behavior | +|--------------|-------------|----------------| +| **draft** | Definition is being created or updated | Not yet available for charging | +| **active** | Definition is currently in use | Can be selected for charging | +| **retired** | Definition is no longer used | Not available for new charges but preserved for historical records | +| **unknown** | Status cannot be determined | Used for imported data with unclear status | + +### Price Component Types + +| Component Type | Description | Usage | +|----------------|-------------|-------| +| **base** | Core price of the service or item | Starting point for all calculations | +| **surcharge** | Additional charge on top of base price | Used for extras or special conditions (e.g., after-hours service) | +| **discount** | Reduction from base price | Used for special programs or agreements | +| **tax** | Statutory charges required by law | Applied based on tax regulations | +| **informational** | Non-charging line items | Used to show calculations or for documentation | + + +## Business Logic +1. **Single Source of Truth**: All billable items must have a corresponding Charge Item Definition. Users can only bill codes that exist here, ensuring consistent naming/pricing. +2. **Lifecycle**: + - **draft** definitions should not appear in standard picklists for charge entry. + - **active** definitions appear in the billing UI. + - **retired** definitions are hidden from new usage but remain valid for historical bills. +3. **Price Calculation**: At the moment a user (or system) creates a Charge Item referencing this definition: + - Evaluate each `propertyGroup` in order. For those whose conditions pass, accumulate the price components (base, surcharge, discount, tax, etc.). + - Derive the final unit price or total by combining those components. + - If multiple property groups apply, they can be additive. For example, base price = 100, night surcharge = 20, tax = 5% → final = 126. + +## Step-by-Step User Workflows +Though staff typically do not interact with Charge Item Definitions daily (they are more of an admin function), here is how the workflow might look for a billing administrator: + +1. **Navigate to “Charge Item Definitions” Admin Screen** + - Only users with proper roles (billing manager) can edit these definitions. + +2. **Create or Edit a Definition** + - Enter basic info: code, title, description. + - Set **status** to `active` once ready. + - Define or update `propertyGroup` details—like base price, potential surcharges, discount conditions. + +3. **Save & Activate** + - The definition now appears in the system’s reference data. + - If staff add charges referencing this code, the system automatically uses these pricing rules. + +4. **Retire a Definition** + - If no longer used, set status to `retired`. The system hides it from new charge entry. Existing references remain valid historically. + +5. **Verify Pricing** + - Admin or finance staff can test conditions to confirm the definition yields correct amounts. E.g., “Patient over 60 -> 10% discount is working as intended.” + + +**Deactivating (Retiring) a Charge Item Definition:** +- If a service is no longer offered or a code is deprecated, an admin can mark it as **Inactive**. This usually involves editing the definition and unchecking an “Active” box or setting a termination date. +- Save the change. Inactive definitions are typically hidden from the charge entry UI so that staff won’t accidentally use them. If they try to use an inactive code (say by typing it manually), the system should reject it. +- The definition remains in the database for reference (especially for old records that used it), but it’s not available for new charges. If there’s a replacement code, the admin might add a note like “Replaced by CODE123 as of 2025”. + +**Viewing the Catalog:** +- The Charge Item Definition list can usually be viewed in a table format by authorized users. It might show columns: Code, Description, Price, Unit, Active/Inactive, etc. +- Users (like billing staff) with view-only access can search this list to find how something is billed. For example, “How much is the charge for an MRI spine?” They can find the definition entry for MRI spine which says, e.g., $400. +- This ensures transparency: staff can answer patient queries about costs using the official catalog. \ No newline at end of file diff --git a/docs/care/HMIS/Billing/Invoice.md b/docs/care/HMIS/Billing/Invoice.md new file mode 100644 index 0000000..e48303b --- /dev/null +++ b/docs/care/HMIS/Billing/Invoice.md @@ -0,0 +1,165 @@ + +# Invoice + +An **Invoice** groups multiple **Charge Items** into a formal bill for a patient or payer. Once an invoice is **issued**, those charges are considered billed. The invoice can then be sent to the patient or insurer for payment. The invoice includes line items referencing the original Charge Items, plus any summary of taxes or adjustments. Once fully paid, the invoice is marked **balanced**. + +Key points about invoices: +- An invoice can be in different states (draft, issued, paid, etc.), reflecting its lifecycle. +- Invoices reference the account and the specific charge items included. +- Invoices typically have unique numbers for external reference, along with dates and payment terms. +- Once an invoice is issued (finalized), the charges on it are considered billed, and the invoice amount becomes a receivable for the hospital to collect from the payor. + +## Schema Definition +```json +{ + "id": "", // Internal Identifier + "status": "", // draft | issued | balanced | cancelled | entered-in-error + "cancelled_reason": "", // Reason if status=cancelled + "type": "", // E.g., "professional", "pharmacy", etc. + "patient": "", + "facility": "", // Facility issuing the invoice + "account": "", // The billing account associated + + "total_net": { "value": "", "currency": "" }, + "total_gross": { "value": "", "currency": "" }, + "payment_terms": "", // e.g. "Net 30 days" + "note": "" // Extra comments about the invoice +} +``` + +## Core Data Structure + +### Essential Fields + +| Field | Description | Technical Notes | +|-------|-------------|----------------| +| **id** | Internal system identifier | Primary key, auto-generated | +| **status** | Current state in the billing lifecycle | Controls available actions and payment status | +| **cancelled_reason** | Explanation if invoice is cancelled | Required when status is "cancelled" | +| **type** | Classification of the invoice | Categorizes for reporting and workflow routing | +| **patient** | Reference to the patient | Person who received the services | +| **facility** | Reference to the healthcare facility | Location that issued the invoice | +| **account** | Reference to the billing account | Account containing the charges | +| **total_price_component** | Breakdown of invoice total | Includes subtotal, taxes, discounts, etc. | +| **total_net** | Net amount before adjustments | Sum of charge items before taxes/discounts | +| **total_gross** | Final billing amount | Final amount after all adjustments | +| **payment_terms** | Payment instructions | Due date, payment methods, etc. | + +### Status Lifecycle + +| Status Value | Description | System Behavior | +|--------------|-------------|----------------| +| **draft** | Invoice is in preparation | Can be edited; not yet sent to recipient | +| **issued** | Invoice is finalized and sent | Read-only; pending payment | +| **balanced** | Invoice is fully paid | Read-only; no balance due | +| **cancelled** | Invoice has been voided | Inactive; requires reason | +| **entered-in-error** | Invoice created by mistake | Excluded from all calculations | + +## Business Logic Highlights + +- **Draft Creation**: Invoices begin as drafts, allowing staff to review and adjust before finalization. + +- **Charge Item Selection**: The system allows selecting which billable Charge Items to include on an invoice, typically gathering all unbilled charges from an account. + +- **Finalization Process**: When an invoice is issued, all included Charge Items are marked as "billed" to prevent duplicate billing. + +- **Payment Tracking**: The invoice status reflects payment completion, changing to "balanced" when fully paid. + +- **Cancellation Handling**: If an invoice is cancelled, the system reverts its Charge Items to "billable" status so they can be included on a new invoice if needed. + +- **Invoice Integrity**: Once issued, an invoice becomes read-only to maintain financial integrity. Changes require cancellation and reissuance. + +```mermaid +flowchart TD + B[Create Invoice Page] + B --> C[Gather Billable Charges] + C --> D[Review Draft Invoice] + + D --> E{Ready to Issue?} + E -->|No| F[Save as Draft] + F --> F1[Can Edit Later] + F1 --> D + + E -->|Yes| G[Finalize Invoice] + G --> H[Generate Invoice Number] + H --> I[Set Status to Issued] + I --> J[Mark Charges as Billed] + J --> K[Send to Recipient] + + K --> L{Payment Received?} + L -->|Full Payment| M[Set Status to Balanced] + L -->|Partial Payment| N[Record Payment] + N --> L + L -->|Problem Identified| O[Cancel Invoice] + + O --> P[Enter Cancellation Reason] + P --> Q[Return Charges to Billable] + Q --> R[Create New Invoice if needed] + + classDef process fill:#f9f,stroke:#333,stroke-width:2px + classDef decision fill:#bbf,stroke:#333,stroke-width:2px + classDef state fill:#6f6,stroke:#333,stroke-width:2px + + class A,B,C,D,F,F1,G,H,I,J,K,N,P,Q,R process + class E,L decision + class M,O state +``` + +**Creating an Invoice**: +1. Select the patient's account +2. The system gathers all billable (unbilled) Charge Items +3. Review the draft invoice and make any adjustments +4. When ready, finalize the invoice to generate an official invoice number +5. The system marks all included charges as "billed" +6. The invoice is now ready to be sent to the patient or insurer + +**Payment Handling**: +1. When payments are received, they are recorded against the invoice +2. Partial payments keep the invoice in "issued" status +3. When the full amount is paid, the invoice status changes to "balanced" +4. The invoice remains as a permanent record of the billing transaction + +**Cancellation Process**: +1. If an invoice needs to be cancelled, select "Cancel Invoice" +2. Enter a cancellation reason (required) +3. The system reverts all charges to "billable" status +4. If needed, create a new corrected invoice + +**Multiple Invoice Scenarios**: +- Interim billing during long stays +- Separate invoices for different service types +- Insurance billing followed by patient responsibility billing +- Corrected invoices after error identification + + + + + + +## Key Fields and Lifecycle +**Business Logic (Lifecycle & Rules):** +- **Drafting vs Finalizing:** Invoices can be prepared as draft, allowing staff to review and possibly get approval before issuing. While in draft, modifications are allowed: + - Staff can add or remove line items (which corresponds to adding or removing Charge Items to the invoice). Usually, only charges that are in “billable” status and not yet invoiced can be added. + - They might adjust quantities or give discounts in this phase as well (for example, perhaps a manager can apply a manual discount line). + - The invoice total is recalculated with each change. +- **Finalization (Issuing):** When staff are satisfied, they will finalize the invoice. At this point: + - The invoice status changes to **issued**. + - The system may assign the official invoice number (if it wasn’t assigned at creation). + - The issue date is set (if not already). + - All included Charge Items are marked as **billed** (their status updated, as discussed in Charge Item section). + - The invoice becomes read-only for content; you generally shouldn’t edit line items after issuing (short of cancelling the invoice). + - The invoice is now ready to be sent to the recipient (could be printed or electronically transmitted). +- **Posting/Printing:** Once issued, the invoice can be delivered. The system might have a function to print the invoice or to send it via email. The invoice document will list all charges and the total due. +- **Payments:** After issuance, the invoice sits in “issued” status until payment(s) are received: + - If a payment comes in (via the Payment Reconciliation process), the invoice doesn’t immediately disappear; it just gains a record of payment. The invoice might show amount paid and remaining due. + - When the total amount of the invoice has been paid, the system should mark the invoice as **balanced** automatically, indicating it’s fully settled. This could be done by the Payment Reconciliation logic (when it notices full payment). + - Partial payments do not change the status (remain “issued”), but internal tracking of outstanding balance is updated. +- **Cancellation:** If an error is discovered on an issued invoice (e.g., a charge was wrong or the invoice was sent to the wrong payer), you may need to cancel it. Business rules: + - Only allow cancellation if no (or minimal) payments have been applied. If payments exist, typically you can’t outright cancel; you might have to refund or reallocate payments first. + - When cancelled, set status = cancelled, and record a cancellation reason. The system should also free up the underlying charge items to be billed on another invoice if appropriate. (i.e., change their status back to billable or even planned, depending on scenario). + - Possibly generate a new invoice if needed (for correct charges). Or if the entire thing was wrong, just cancel and start over. + - Cancelled invoices are kept for audit, but are not considered collectible. +- **Avoiding Duplicate Invoices:** The system should ensure the same charge isn’t invoiced twice. This is handled by charge status (once included on an issued invoice, a charge shouldn’t appear on another invoice). When creating an invoice, the selection of charges should exclude any that are already billed. If a user somehow attempts to include a charge that’s been billed, the system should flag it as not allowed. +- **Multiple Invoices per Account:** It’s possible to have multiple invoices for one account. For example, in a long hospital stay, they might generate interim invoices monthly, or one at discharge and then a supplementary one for late charges. The system should support picking which charges to include each time. Typically, an invoice might include all currently uninvoiced charges up to a cutoff date. If doing partial billing, the UI might allow selecting specific items or setting a date range. +- **Invoice for Insurance vs Patient:** If insurance is involved, an initial invoice might be created to send to the insurer (or an electronic claim, depending on integration). After insurer pays or responds, a secondary invoice (often called patient statement) might be created for the patient for any remaining amount. In our HMIS, the Invoice module could handle both by marking who it’s addressed to. For instance, invoice #100 to Insurance (for full charges) and after insurance adjustments, an invoice #101 to patient for copay/deductible. +- **Invoice Adjustments/Credits:** If after issuing an invoice, one charge amount needs to be reduced (but not fully cancel the invoice), an approach is to add an adjustment line (negative line item) to the invoice.(How to do it?) diff --git a/docs/care/HMIS/Billing/PaymentReconciliation.md b/docs/care/HMIS/Billing/PaymentReconciliation.md new file mode 100644 index 0000000..28d3287 --- /dev/null +++ b/docs/care/HMIS/Billing/PaymentReconciliation.md @@ -0,0 +1,180 @@ +# Payment Reconciliation + +**Payment Reconciliation** records **payments** (and possibly adjustments) made toward one or more invoices or accounts. It answers: *“Who paid, how much, and which invoice(s) or account(s) does this money apply to?”* By storing a Payment Reconciliation entry each time a patient or insurer submits payment, the system can track how the invoice balances shift from unpaid to partially paid to fully settled. + +If a payment is reversed (e.g., check bounces), the Payment Reconciliation is canceled or marked in error, restoring the invoice’s outstanding amount. This ensures a complete audit trail of all financial transactions. + + +## Schema Definition +```json +{ + "id": "", // Internal Identifier + "type": "", // payment | adjustment | advance + "status": "", // active | cancelled | draft | entered-in-error + "kind": "", // e.g., "online", "online", "deposit" + "issuerType": "", // "patient" or "insurer" + "outcome": "", // queued | complete | error | partial + "facility": "", + "disposition": "", // Additional message or outcome detail + "method": "", // Payment method (cash, check, credit, etc.) + "datetime": "", // When payment was posted + "referenceNumber": "", // Check number or transaction reference + "authorization": "", // Auth code if card-based + "tenderedAmount": { "value": "", "currency": "" }, + "returnedAmount": { "value": "", "currency": "" }, + "amount": { "value": "", "currency": "" }, // Net amount posted + "target_invoice": "", // If a single-invoice payment + "account": "", // If no invoice, apply to Account + "note": "" +} +``` + +### Essential Fields + +| Field | Description | Technical Notes | +|-------|-------------|----------------| +| **id** | Internal system identifier | Primary key, auto-generated | +| **type** | Category of payment transaction | Distinguishes between payments, adjustments, and advances | +| **status** | Current state of the payment record | Controls visibility and effect on balances | +| **kind** | Payment workflow classification | Tracks channel or method of payment receipt | +| **issuerType** | Source of the payment | Distinguishes between patient payments and insurance payments | +| **outcome** | Processing result of the payment | Tracks whether payment was fully processed | +| **facility** | Reference to the healthcare facility | Location where payment was recorded | +| **method** | Payment method used | Cash, check, credit card, bank transfer, etc. | +| **datetime** | Date and time of payment | When payment was received | +| **referenceNumber** | External transaction identifier | Check number, transaction ID, etc. | +| **amount** | Payment amount | The actual amount received | +| **target_invoice** | Reference to the invoice | Invoice being paid (if applicable) | +| **account** | Reference to the billing account | Used when payment applies to account rather than specific invoice | + +### Status Values + +| Status Value | Description | System Behavior | +|--------------|-------------|----------------| +| **active** | Payment is complete and valid | Included in financial calculations | +| **cancelled** | Payment has been reversed | Excluded from balances; requires reversal processing | +| **draft** | Payment is being processed | Not yet included in financial calculations | +| **entered-in-error** | Payment recorded incorrectly | Excluded from all calculations | + +### Payment Types + +| Type | Description | Usage | +|------|-------------|-------| +| **payment** | Standard monetary transaction | Normal payments from patients or insurance | +| **adjustment** | Non-monetary balance change | Contractual adjustments, write-offs, etc. | +| **advance** | Payment before services | Pre-payments or deposits | + +### Payment Outcomes + +| Outcome | Description | Next Steps | +|---------|-------------|-----------| +| **queued** | Payment is pending processing | Requires follow-up to complete | +| **complete** | Payment fully processed | No additional action needed | +| **error** | Payment processing failed | Requires investigation and correction | +| **partial** | Payment partially processed | Remaining processing needed | + + +### Payment Kinds + +| Kind Value | Description | Usage | +|------------|-------------|--------| +| **deposit** | One-time payment deposit | Used for upfront payments or security deposits | +| **preriodic_payment** | Recurring scheduled payment | For payment plans or installments | +| **online** | Payment made through web portal | Self-service online payments | +| **kiosk** | Payment made at payment kiosk | Self-service kiosk payments | + + +### Payment Issuer Types + +| Issuer Type | Description | Usage | +|-------------|-------------|--------| +| **patient** | Payment from patient | Direct payments from patients or their representatives | +| **insurance** | Payment from insurance | Payments from insurance companies or third-party payers | + +### Payment Methods + +| Method Code | Description | Usage | +|------------|-------------|--------| +| **cash** | Cash payment | Physical currency payments | +| **ccca** | Credit card payment | Payment via credit card | +| **cchk** | Credit check | Payment via credit check | +| **cdac** | Credit/debit account | Payment via linked bank account | +| **chck** | Check payment | Payment via paper check | +| **ddpo** | Direct deposit | Payment via bank deposit | +| **debc** | Debit card | Payment via debit card | + + +## Flow +```mermaid +flowchart TD + A[Record Payment] --> B[Select Payment Type] + B --> C[Enter Payment Details] + C --> D[Select Target Invoice/Account] + + D --> E{Full or Partial Payment?} + E -->|Full Payment| F[Amount Equals Invoice Total] + E -->|Partial Payment| G[Enter Payment Amount] + F --> H[Validate Payment Details] + G --> H + + H --> I{Valid Payment?} + I -->|No| J[Fix Issues] + J --> H + I -->|Yes| K[Process Payment] + + K --> L[Create Payment Record] + L --> M[Update Invoice Status if Fully Paid] + M --> N[Update Account Balance] + + O[Reverse Payment] --> P[Locate Payment Record] + P --> Q[Enter Reversal Reason] + Q --> R[Process Reversal] + R --> S[Restore Invoice and Account Balances] + + classDef process fill:#f9f,stroke:#333,stroke-width:2px + classDef decision fill:#bbf,stroke:#333,stroke-width:2px + classDef state fill:#6f6,stroke:#333,stroke-width:2px + + class A,B,C,D,F,G,H,J,K,L,M,N,P,Q,R,S process + class E,I decision + class O state +``` + + +## Business Logic + +- When a payment is recorded, the amount gets distributed to invoices: + - If the user is recording a payment for a single invoice (like patient pays their bill), the system will auto-allocate full amount to that invoice (and check if it matches the invoice amount, if not, treat as partial payment). + - If the payment is meant for multiple invoices (like an insurance bulk payment or patient paying multiple bills at once), the UI should allow selecting multiple target invoices and specifying amounts for each. The sum of allocations should equal the payment. + - The account’s balance and each invoice’s balance need to update accordingly: subtract the paid amounts. +- If a payment fully covers an invoice, mark the invoice **balanced** (paid in full). If partially, invoice remains **issued** with remaining balance. +- If a payment exceeds what was due (overpayment), the system might either hold the extra as a credit on the account (unallocated) or ask the user to adjust the allocation (maybe the patient intended to pay only what was due). +- Payment records can also represent **refunds or chargebacks** if negative amounts are allowed or by using cancellation: + - We'll keep it simpler by saying to cancel or reverse the payment rather than negative entries. +- The Payment Reconciliation acts as a receipt internally. +- The module also handles **adjustments** from insurance. These might be recorded as a special kind of allocation (with no actual payment but reduces invoice balance). +- Ensuring that after posting all payments, any remaining balance on an invoice is correctly represented. +- Payments should update the **Account** as well: since account balance is charges minus payments, adding a payment will reduce the account’s balance. +- If a Payment Reconciliation is cancelled (like a bounced check), the system should re-open those invoice balances: + - The invoice status goes back from balanced to issued if it was fully paid by that payment. + - If partial, increase the outstanding amount accordingly. + - Possibly log the reason (bounced check fee maybe separate). +- There should be integrity: you shouldn’t be able to apply more money to an invoice than its amount (except if intentionally overpay, which then needs handling like credit). +- Payment Reconciliation records also help in reconciling with bank deposits (each day’s cash, check, credit totals). So you might have reports grouping payments by date/method for bank reconciliation. + +## Payment Posting + +**Handling a Payment Reversal (Bounced check or error):** +1. Locate the Payment record (e.g., search by check number or patient). +2. Use a **“Cancel Payment”** or **“Reverse Payment”** action. The system might ask for a reason (“Check bounced due to insufficient funds”). +3. On confirmation, the Payment Reconciliation status changes to **Cancelled** (or enters an error state). The system effectively **negates the effects** of that payment: + - The associated invoices’ balances are increased back by the amounts that this payment had covered. + - If those invoices were marked paid, they revert to issued (not paid). If partially paid, their outstanding increases. + - The account balance goes up accordingly. + - Optionally log an internal note on the invoice or account about this reversal. +4. The cancelled payment record remains for audit, perhaps with a note, but is not counted in totals. + +**Viewing Payment History:** +- On a patient account or invoice screen, staff can see a list of payments applied. For each payment: date, amount, method, reference. If one payment covered multiple invoices, that payment might show up in each relevant account’s history (with the portion that applied). +- There may also be a standalone Payment Reconciliation list (for all payments) where staff (like finance) can search by date range, method, etc., to do end-of-day reconciliation (e.g., total cash collected today). +- Reports can be generated, like “Daily Cash Collection Report” summing all payments by type, which should match actual cash in hand or bank deposits. \ No newline at end of file diff --git a/docs/care/HMIS/Labs/ActivityDefinition.md b/docs/care/HMIS/Labs/ActivityDefinition.md new file mode 100644 index 0000000..1017d1e --- /dev/null +++ b/docs/care/HMIS/Labs/ActivityDefinition.md @@ -0,0 +1,81 @@ +# Activity Definition + +### Summary + +In CARE, `ActivityDefinition` is used to define reusable **templates for clinical actions**, such as lab tests or medication requests. Each definition standardizes how a particular diagnostic activity should be instantiated at runtime — enabling consistent behavior across service requests and automated billing. + +### Core Relationships + +| Related Resource | Purpose | +| ----------------------- | ------------------------------------------------- | +| `ServiceRequest` | Primary output when ActivityDefinition is applied | +| `ChargeItemDefinition` | Linked to define billing behavior | +| `SpecimenDefinition` | Defines required specimens for lab tests | +| `ObservationDefinition` | Specifies expected observation outcomes | + +### Supported Fields + +| Field Name | Description | Example | +| -------------------------------- | ---------------------------------------------------------------------------- | ------------------------------ | +| `id` | Internal identifier | `AD-001` | +| `version` | Versioning control for updates | `1` | +| `slug` | Unique name within a facility | `cbc-test` | +| `derived_from_url` | Source or canonical reference | `https://fhir.care/ad/cbc` | +| `title` | Human-readable name | `Complete Blood Count` | +| `subtitle` | Optional secondary title | `CBC (Routine)` | +| `status` | Draft, active, retired | `active` | +| `category` | Clinical category (from FHIR extensible valueset) | `laboratory` | +| `description` | Long-form description | `"Standard CBC test"` | +| `purpose` | Rationale for defining the activity | `"Baseline health evaluation"` | +| `usage` | Description of clinical usage | `"Used for anemia screening"` | +| `facility` | Facility where the definition is used | `Facility/Medicity` | +| `kind` | Type of FHIR resource created by this template (e.g., `ServiceRequest`) | `ServiceRequest` | +| `code` | Clinical code (e.g., SNOMED or internal code for the action) | `718-7` | +| `body_site` | Applicable body site, if relevant | `left arm` | +| `locations[]` | List of locations where this test can be performed | `[LabA, LabB]` | +| `specimenRequirement[]` | Linked `SpecimenDefinition` entries required for the test | `Specimen/Blood` | +| `observationResultRequirement[]` | Linked `ObservationDefinition` entries that define expected result structure | `[Hemoglobin, WBC, RBC]` | + +### Functional Workflow + +- **Define Activity** + + Admin defines a test (e.g., CBC) using `ActivityDefinition`, linking to specimens, observations, and charge items. + +- **Apply ActivityDefinition** + + When a `ServiceRequest` is created (via UI/API), the system references the relevant `ActivityDefinition` and uses it to instantiate the required resource. + +- **Auto-Generate ChargeItems** + + If charges are linked to the `ActivityDefinition`, they are also instantiated. + +### **Schema Definition?** + +```jsx +{ + "id" : "", // Internal Identifier + "version" : "", // Version of the Activity Definition + "slug" : "", // Unique name per facility + "derived_from_url" : "", // URL this object was derived from + "title" : "", // Name for this activity definition (human friendly) + "subtitle" : "", // Subordinate title of the activity definition + "status" : "", // R! draft | active | retired | unknown + "category" : "" // Bound to https://build.fhir.org/valueset-servicerequest-category.html Extensible + // "contact" : [{ ContactDetail }], // Contact details for the publisher + "description" : "", // Natural language description of the activity definition + "purpose" : "", // Why this activity definition is defined + "usage" : "", // Describes the clinical usage of the activity definition + "facility" : "", // Facility where this Account is created + // topic" : "", // No Valid use for this right now + "kind" : "", // FHIR Resource Type that is created by this Definition, Options will be internally identified by the system + "code" : "", // Bound to Snomed, controls what kind of Def this is, Example Procedure Codes + //"intent" : "", // proposal | plan | directive | order | original-order | reflex-order | filler-order | instance-order | option + //"priority" : "", // routine | urgent | asap | stat + "body_site" : "" // Bound to the Body site Valueset + "locations" : [""], // Foreign key to location + "specimenRequirement" : [""], // Points to SpecimentDefinition + //"observationRequirement" : [""], //Points to Observation Requirement + "observationResultRequirement" : [""], // What observations must be produced by this action +} +``` diff --git a/docs/care/HMIS/Labs/ChargeItemDefinition.md b/docs/care/HMIS/Labs/ChargeItemDefinition.md new file mode 100644 index 0000000..fa5000e --- /dev/null +++ b/docs/care/HMIS/Labs/ChargeItemDefinition.md @@ -0,0 +1,46 @@ +# Charge Item Definition + +### Summary + +The `ChargeItemDefinition` in CARE specifies **how clinical activities (like lab tests or medications) are priced**. It allows each `ActivityDefinition`, `Medication`, or other healthcare service to be tied to a dynamic billing rule that governs how much a service costs under specific conditions. + +CARE’s billing model works behind the scenes: **as practitioners record data (ServiceRequests, MedicationRequests, etc.), billing objects are automatically created** using the relevant `ChargeItemDefinition`. + +### Core Relationships + +| Related Resource | Purpose | +| ---------------------- | -------------------------------------------------- | +| `ActivityDefinition` | Resource whose execution will generate this charge | +| `Medication` | Medication product that incurs a cost | +| `Encounter`, `Patient` | Used in condition evaluation for dynamic pricing | + +### Supported Fields + +| Field Name | Description | Example | +| ----------------- | --------------------------------------------------------- | -------------------------------------- | +| `title` | Name for human readability | `"CBC Test Standard Rate"` | +| `slug` | Unique internal reference | `"cbc-charge"` | +| `derivedFromUri` | Canonical URL reference if derived from standard | `"http://example.org/rates/cbc"` | +| `status` | Lifecycle status (`draft`, `active`, etc.) | `"active"` | +| `facility` | The facility where this pricing applies | `Facility/medicity` | +| `description` | Free-text description of the charge definition | `"Pricing for CBC including lab work"` | +| `purpose` | Rationale for the charge | `"Used to generate automated bills"` | +| `code` | Internal or external billing/product code | `"CBC01"` | +| `instance[]` | List of linked resources (ActivityDefinition, Medication) | `[ActivityDefinition/cbc]` | +| `propertyGroup[]` | Array of pricing conditions and breakdowns | See below | +| `baseprice[]` | Base Charge for a lab test | See below | +| `discounts[]` | Price reduction applied to the base amount before tax | See below | +| `taxes[]` | Applicable government taxes | See below | + +``` + +### Billing Workflow in CARE + +1. Practitioner creates a `ServiceRequest` for CBC. +2. The system checks the associated `ActivityDefinition` and its linked `ChargeItemDefinition`. +3. Based on patient and encounter details (age, location, tags), applicable pricing rules are evaluated. +4. A **charge item is instantiated** and added to the patient’s bill automatically. +5. Taxes and discounts are computed, total is stored with a detailed breakdown. + + +``` diff --git a/docs/care/HMIS/Labs/DiagnosticReport.md b/docs/care/HMIS/Labs/DiagnosticReport.md new file mode 100644 index 0000000..c157d52 --- /dev/null +++ b/docs/care/HMIS/Labs/DiagnosticReport.md @@ -0,0 +1,17 @@ +# Diagnostic Report + +### Summary + +A `DiagnosticReport` in CARE provides a structured summary of the findings, interpretations, and outcomes derived from diagnostic activities such as lab tests. While the **clinical measurements themselves are stored as `Observation` resources**, the `DiagnosticReport` acts as a **wrapper** or **summary document**, linking together those observations in a meaningful context. + +In the CARE MVP, diagnostic reports are generated **only from `ServiceRequest` resources**, but the system is designed to support reports generated from other clinical contexts in future. + +### Core Relationships + +| Related Resource | Purpose | +| ---------------- | ----------------------------------------------------- | +| `ServiceRequest` | Origin of the diagnostic request | +| `Observation[]` | Measured values linked to this report | +| `Patient` | Patient for whom the report was generated | +| `Encounter` | Visit or session in which the test was performed | +| `Specimen[]` | Specimens used for testing (currently ignored in MVP) | diff --git a/docs/care/HMIS/Labs/ObservationDefinition.md b/docs/care/HMIS/Labs/ObservationDefinition.md new file mode 100644 index 0000000..474448b --- /dev/null +++ b/docs/care/HMIS/Labs/ObservationDefinition.md @@ -0,0 +1,40 @@ +# Observation Definition + +### Summary + +`ObservationDefinition` is used to define the structure and expectations of a **clinical observation or lab result**, such as "Hemoglobin level" or "Blood glucose." These definitions describe the unit, valid value range, data type, and measurement method — forming a **template** for the actual `Observation` instances recorded during diagnostics. + +In CARE, this ensures consistency across lab results and helps maintain standards for how observations are displayed, interpreted, and validated. + +### Core Relationships + +| Related Resource | Purpose | +| -------------------- | ---------------------------------------------------------- | +| `ActivityDefinition` | Links expected observations for a test | +| `Observation` | Actual instance of a result captured using this definition | +| `SpecimenDefinition` | May define specimen type required for this observation | + +### Supported Fields + +| Field Name | Description | Example | +| ------------- | ----------------------------------------------- | ------------------------------------- | +| `title` | Human-readable name of the observation | `Hemoglobin` | +| `slug` | Unique internal reference name | `hb-level` | +| `description` | Clinical context or explanation | `"Hemoglobin concentration in blood"` | +| `status` | Lifecycle status (`draft`, `active`, etc.) | `active` | +| `category` | Clinical category | `laboratory` | +| `data_type` | Type of result value | `string` | +| `Loinc_Code` | LOINC or internal code | `"LOINCCode"` | +| `Body Site` | Location on the body for sample collection | `"Right Arm"` | +| `Method` | Measurement technique (e.g., Spectrophotometry) | `"Automatic"` | +| `unit` | Measurement unit | `"mmHg"` | +| `Components` | To record multiple related values | `CBC` | + +### Functional Workflow + +1. Admin defines the **observation format** for a test (e.g., Hemoglobin). +2. Links this definition to the appropriate **ActivityDefinition**. +3. When test results are recorded, the system: + - Enforces data type (e.g., Quantity) + - Validates result range + - Uses the `preferred_report_name` for display diff --git a/docs/care/HMIS/Labs/README.md b/docs/care/HMIS/Labs/README.md new file mode 100644 index 0000000..10cebca --- /dev/null +++ b/docs/care/HMIS/Labs/README.md @@ -0,0 +1,37 @@ +# Labs & Diagnostics Module + +This overview provides a high-level understanding of how diagnostic workflows are structured in CARE — from test orders to sample collection, report generation and recording observations. The subsequent pages detail each resource and its role in the system. + +## Key Labs Concepts + +| Resource | Description | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| ServiceRequest | A record of a request for service such as diagnostic investigations, treatments, or operations to be performed. | +| ActivityDefinition | A template that defines a standard lab or imaging procedure | +| SpecimenDefinition | A record of a sample to be used for analysis. | +| ObservationDefinition | A template that defines lab test results or imaging findings — defining expected units, value types, and coded terminologies. | +| ChargeItemDefinition | A template that provides the properties that apply to the (billing) codes necessary to calculate costs and prices. | +| DiagnosticReport | The findings and interpretations of diagnostic tests performed on a patient. | + +## High-Level Labs Flow + +Below is a simplified look at how these pieces fit together: + +```mermaid +%%{init: {'theme':'redux'}}%% +flowchart LR + A[" Patient"] --> B[" Encounter"] + B --> C[" Lab Test Ordered"] + C --> D{" Sample Collected?"} + D -- Yes --> E[" Sample Sent to Lab"] + D -- No --> F[" Notify Nurse/Phlebotomist"] + E --> G[" Lab Processing"] + G --> H{" Result Ready?"} + H -- Yes --> I[" Result Uploaded to EMR"] + H -- No --> J[" Wait/Repeat Test"] + I --> K[" Doctor Reviews Results"] +``` + +## Concept Diagram + +![Labs Concept Diagram](../../../../static/img/care/HMIS/Labs/Labs%20Concept%20Diagram.svg) diff --git a/docs/care/HMIS/Labs/ServiceRequest.md b/docs/care/HMIS/Labs/ServiceRequest.md new file mode 100644 index 0000000..668115f --- /dev/null +++ b/docs/care/HMIS/Labs/ServiceRequest.md @@ -0,0 +1,5 @@ +# Service Request + +### Summary + +In FHIR, a `ServiceRequest` represents an order or proposal to perform a clinical or non-clinical action for a patient. It can lead to the creation of related resources like `Procedure`, `Observation`, `Specimen`, or `DiagnosticReport`, though these are optional and context-dependent. diff --git a/docs/care/HMIS/Labs/Specimen.md b/docs/care/HMIS/Labs/Specimen.md new file mode 100644 index 0000000..1a3f964 --- /dev/null +++ b/docs/care/HMIS/Labs/Specimen.md @@ -0,0 +1,18 @@ +# Specimen + +### Summary + +In CARE, a `Specimen` represents a **physical sample collected from a patient** for diagnostic analysis. This includes blood, urine, swabs, or tissue samples collected as part of a diagnostic process. Each specimen is associated with a patient, collected during an encounter, and typically originates from a `ServiceRequest`. + +Specimens can optionally be **instantiated from a `SpecimenDefinition`**, inheriting baseline properties such as type, preparation, and container. However, all real-world specifics — collection details, condition, and processing — are captured in the `Specimen` resource itself. + +### Core Relationships + +| Related Resource | Purpose | +| -------------------- | ------------------------------------------------------------ | +| `Patient` | The subject from whom the specimen was collected | +| `Encounter` | The clinical context of collection | +| `ServiceRequest` | The reason the specimen was collected | +| `SpecimenDefinition` | (Optional) Template from which the specimen was instantiated | +| `Procedure` | Procedure during which the specimen was collected | +| `Observation` | Diagnostic data produced based on this specimen | diff --git a/docs/care/HMIS/Labs/SpecimenDefinition.md b/docs/care/HMIS/Labs/SpecimenDefinition.md new file mode 100644 index 0000000..b97fb80 --- /dev/null +++ b/docs/care/HMIS/Labs/SpecimenDefinition.md @@ -0,0 +1,48 @@ +# Specimen Definition + +### Summary + +`SpecimenDefinition` defines the **template or blueprint for specimen types** used in the laboratory. Instead of repeatedly defining the properties of commonly collected specimens (like blood, urine, or sputum), CARE uses `SpecimenDefinition` to maintain a central, reusable registry of specimen kinds that can be instantiated when needed. + +When a specimen is collected during a diagnostic workflow, it is linked to its `SpecimenDefinition`. The instance retains a **snapshot** of the original definition to ensure **data integrity** and **historical traceability**, even if the definition changes later. + +This resource enables structured specimen management aligned with the FHIR specification and supports integration with `ActivityDefinition` for test planning. + +### Core Relationships + +| Related Resource | Purpose | +| -------------------- | ------------------------------------------------- | +| `ActivityDefinition` | Specifies which specimens are required for a test | +| `Specimen` | Concrete instance created from this definition | +| `Facility` | Scope of usage for definition | + +### Supported Fields + +| Field | Description | Example | +| ------------------------- | ------------------------------------------- | ------------------------------ | +| `title` | Human-readable label | `"Venous Blood"` | +| `slug` | Unique internal name | `"venous-blood"` | +| `status` | Lifecycle status (`draft`, `active`, etc.) | `"active"` | +| `derived_from_uri` | Reference to external source or standard | `"http://hl7.org/specs/blood"` | +| `description` | Narrative explanation of this specimen type | `"Standard blood draw"` | +| `type_collected` | Type of specimen (bound to HL7 valuesets) | `"venous blood"` | +| `collection` | Collection procedure (e.g., venipuncture) | `"SNOMED/73761001"` | +| `patient_preparation[]` | Pre-collection instructions (e.g., fasting) | `["SNOMED/20430005"]` | +| `Is derived[]` | Whether specimen is derived or not | `[""]` | +| `Single Use[]` | Whether it is meant for a single use or not | `[""]` | +| `Specimen Type[]` | Type of specimen collected | `[""]` | +| `Preference[]` | Preferred or alternate | `[""]` | +| `Retention Time[]` | Amount of time specimen can be retained | `[""]` | +| `Requirement[]` | To add any additional requirements | `[""]` | +| `Container Description[]` | Description of container | `[""]` | +| `Cap[]` | Color of the container cap | `[""]` | +| `Capacity[]` | Capacity of container | `[""]` | +| `Minimum Quantity[]` | Minimum quantity of specimen required | `[""]` | +| `Preparation[]` | To record preparation details | `[""]` | + +### Functional Workflow + +1. **Admin defines a SpecimenDefinition** for common sample types (e.g., venous blood). +2. **Linked via ActivityDefinition** to relevant lab tests. +3. When a lab test is initiated, **specimen instances are created** from these definitions via a dedicated API. +4. Specimen instances store a **snapshot** of definition fields to preserve traceability. diff --git a/docs/care/HMIS/Pharmacy/ChargeItem.md b/docs/care/HMIS/Pharmacy/ChargeItem.md new file mode 100644 index 0000000..ff647bf --- /dev/null +++ b/docs/care/HMIS/Pharmacy/ChargeItem.md @@ -0,0 +1,54 @@ +# Charge Item + +### Summary + +The **Charge Item** resource in the CARE system captures financial details associated with services rendered or products supplied to a patient. It serves as a self-contained record, detailing the origin of the charge, the amount, applied discounts, taxes, and other relevant financial information. + +--- + +### Key Purpose + +- Document financial charges for services or products provided to patients. +- Enable automated billing processes by linking clinical activities to financial records. +- Support detailed breakdowns of charges, including taxes, discounts, and surcharges. + +--- + +## Core Data Structure + +### Essential Fields + +| Field | Description | Technical Notes | +| ----------------------- | --------------------------------------- | ------------------------------------------------ | +| **id** | Internal system identifier | Primary key, auto-generated | +| **definition** | Reference to the Charge Item Definition | Links to the catalog entry for this service/item | +| **status** | Current state in the billing lifecycle | Controls whether the item can be invoiced | +| **code** | Billing code for the service | Often derived from the definition | +| **patient** | Reference to the patient | Person receiving the service | +| **encounter** | Reference to the healthcare encounter | Links to the clinical context | +| **facility** | Reference to the healthcare facility | Location where service was provided | +| **quantity** | Number of units provided | Default is 1 for most services | +| **unitPriceComponent** | Price breakdown per unit | Includes base, surcharges, discounts, taxes | +| **totalPriceComponent** | Price breakdown for all units | Unit price × quantity with all components | +| **total_price** | Final calculated amount | Sum of all price components | +| **account** | Reference to the billing account | Where this charge accumulates | + +### Supported Fields + +**Monetary Component:** + +- **`type`**: Type of price component (e.g., base, surcharge, discount, tax, informational). +- **`code`**: Code differentiating kinds of taxes, surcharges, discounts, etc. +- **`factor`**: Factor used for calculating this component. +- **`amount`**: Monetary amount associated with this component, including value and currency. + +--- + +### Functional Workflow + +1. **Charge Item Creation**: When a service is rendered or a product is supplied, a Charge Item is automatically generated, capturing all relevant financial details. +2. **Association with Encounter and Account**: The Charge Item is linked to the specific patient encounter and their billing account, ensuring accurate financial tracking. +3. **Pricing Calculation**: Using the associated Charge Item Definition, the system calculates the unit and total prices, factoring in any applicable taxes, discounts, or surcharges. +4. **Manual Overrides**: If necessary, authorized personnel can override standard pricing, with the reason documented in the `overrideReason` field. +5. **Billing and Invoicing**: Charge Items feed into the billing system, facilitating invoice generation and payment processing. +6. **Audit and Reporting**: Detailed records of Charge Items support financial audits and reporting requirements. diff --git a/docs/care/HMIS/Pharmacy/ChargeItemDefinition.md b/docs/care/HMIS/Pharmacy/ChargeItemDefinition.md new file mode 100644 index 0000000..34c3d82 --- /dev/null +++ b/docs/care/HMIS/Pharmacy/ChargeItemDefinition.md @@ -0,0 +1,57 @@ +# Charge Item Definition + +### Summary + +The **Charge Item Definition** resource in the CARE system outlines the billing rules and pricing details associated with healthcare services and products. It serves as a blueprint for how charges are calculated, considering various factors such as patient demographics, service context, and applicable taxes. + +This resource aligns with FHIR's [ChargeItemDefinition](https://build.fhir.org/chargeitemdefinition.html) resource, providing a standardized framework for representing billing information.[FHIR Build](https://build.fhir.org/chargeitemdefinition.html?utm_source=chatgpt.com) + +--- + +### Key Purpose + +- Define billing rules and pricing structures for healthcare services and products. +- Enable automated charge item creation based on clinical data entry. +- Support conditional pricing based on patient attributes and service context. +- Facilitate tax calculations and regional billing configurations.[imagineteam.com+7HL7 Confluence+7RCM Matter+7](https://confluence.hl7.org/spaces/FHIR/pages/66929138/Chargeitemdefinition%2BFhir%2BResource%2BProposal?utm_source=chatgpt.com)[Medical Billing Star](https://www.medicalbillingstar.com/medgen-ehr/work-flow.html?utm_source=chatgpt.com) + +--- + +### Core Relationships + +| Related Resource | Purpose | +| ---------------------- | -------------------------------------------------- | +| `ActivityDefinition` | Resource whose execution will generate this charge | +| `Medication` | Medication product that incurs a cost | +| `Encounter`, `Patient` | Used in condition evaluation for dynamic pricing | + +### Supported Fields + +| Field Name | Description | Example | +| ----------------- | --------------------------------------------------------- | -------------------------------------- | +| `title` | Name for human readability | `"CBC Test Standard Rate"` | +| `slug` | Unique internal reference | `"cbc-charge"` | +| `derivedFromUri` | Canonical URL reference if derived from standard | `"http://example.org/rates/cbc"` | +| `status` | Lifecycle status (`draft`, `active`, etc.) | `"active"` | +| `facility` | The facility where this pricing applies | `Facility/medicity` | +| `description` | Free-text description of the charge definition | `"Pricing for CBC including lab work"` | +| `purpose` | Rationale for the charge | `"Used to generate automated bills"` | +| `code` | Internal or external billing/product code | `"CBC01"` | +| `instance[]` | List of linked resources (ActivityDefinition, Medication) | `[ActivityDefinition/cbc]` | +| `propertyGroup[]` | Array of pricing conditions and breakdowns | See below | +| `baseprice[]` | Base Charge for a lab test | See below | +| `discounts[]` | Price reduction applied to the base amount before tax | See below | +| `taxes[]` | Applicable government taxes | See below | + +``` + +--- + +### Functional Workflow + +1. **Definition Creation**: A Charge Item Definition is created, detailing the billing rules and pricing structures for specific services or products. +2. **Automated Charge Generation**: When clinical data is entered (e.g., medication requests), the system automatically generates corresponding charge items based on the definitions. +3. **Conditional Pricing**: The system evaluates patient and encounter data against the applicability conditions to determine the appropriate pricing. +4. **Tax Calculation**: Applicable taxes are calculated based on configured tax codes and added to the total charge. +5. **Billing Integration**: The final charge, including all components, is integrated into the billing system for invoicing and payment processing. +``` diff --git a/docs/care/HMIS/Pharmacy/InventoryItem.md b/docs/care/HMIS/Pharmacy/InventoryItem.md new file mode 100644 index 0000000..162cde5 --- /dev/null +++ b/docs/care/HMIS/Pharmacy/InventoryItem.md @@ -0,0 +1,39 @@ +# Inventory Item + +### Summary + +The **InventoryItem** resource represents the availability of a specific product at a given location. It is primarily used for inventory management within healthcare facilities, ensuring accurate tracking of stock levels for medications and other products. + +Inventory items are automatically created and updated, typically when a supply delivery is marked as completed. + +--- + +### Key Purpose + +- Track the availability and quantity of products at specific locations. +- Facilitate inventory management and auditing processes. +- Support automated updates based on supply deliveries. +- Indicate the active or inactive status of inventory items. + +--- + +--- + +### Supported Fields + +| Field Name | Type | Description | +| ----------------- | --------- | -------------------------------------------------- | +| `product` | Reference | Reference to the product being tracked. | +| `net_content` | Quantity | Quantity of the product available at the location. | +| `status` | code | Current status of the inventory item. | +| `expiration_date` | date | date of expiry | +| `Batch` | string | Batch Number | + +--- + +### Functional Workflow + +1. **Supply Delivery Completion**: When a supply delivery is marked as completed, corresponding inventory items are automatically created or updated to reflect the new stock levels. +2. **Inventory Updates**: Any changes in stock levels, such as dispensing or receiving products, result in automatic updates to the inventory items. +3. **Status Management**: Inventory items can be marked as inactive to indicate that they are no longer actively dispensed, possibly due to damage or other concerns. +4. **Inventory Auditing**: Regular audits can be conducted by reviewing the inventory items, their statuses, and quantities to ensure accurate stock management. diff --git a/docs/care/HMIS/Pharmacy/MedicationDispense.md b/docs/care/HMIS/Pharmacy/MedicationDispense.md new file mode 100644 index 0000000..9c10285 --- /dev/null +++ b/docs/care/HMIS/Pharmacy/MedicationDispense.md @@ -0,0 +1,59 @@ +# Medication Dispense + +### Summary + +The **MedicationDispense** resource in FHIR records the details of medications that have been dispensed to a patient. It serves as both a completion to the workflow initiated by a MedicationRequest and as a tool for inventory management within a healthcare setting. + +In inpatient (IP) settings, items may be dispensed and maintained in the patient's room and refilled as needed. In outpatient (OP) settings, dispensing typically occurs after an encounter has been completed. + +A **ChargeItem** can be associated with each dispense. By default, the **ChargeItemDefinition** is used to create this ChargeItem. + +--- + +### Key Purpose + +- Document the supply of medications to patients. +- Complete the medication workflow initiated by a MedicationRequest. +- Support inventory management within healthcare facilities. +- Facilitate billing through associated ChargeItems. + +--- + +### Core Relationships + +| Field | Reference Resource | Description | +| -------------------------- | ------------------ | ------------------------------------------------- | +| `product` | Product | The product being dispensed. | +| `patient` | Patient | The individual receiving the medication. | +| `encounter` | Encounter | The encounter during which the dispense was made. | +| `location` | Location | The location where the dispense occurred. | +| `authorizing_prescription` | MedicationRequest | The prescription that authorized the dispense. | +| `charge_item` | ChargeItem | The associated charge for the dispensed item. | + +--- + +### Supported Fields + +| Field Name | Type | Description | +| --------------------- | ---------- | -------------------------------------------------- | +| `medicine` | Reference | Reference to the product being dispensed. | +| `dosage_instructions` | Dosage | Instructions on how the medication should be used. | +| `select_lot` | Lot | Lot number | +| `expiry` | string | Expiry Date | +| `quantity` | Quantity | Amount of medication dispensed. | +| `days_supply` | Quantity | Number of days the supply is intended to last. | +| `price` | Amount | Price of the item | +| `discount` | Percentage | Applicable discount | +| `is_fully_dispensed` | Checkbox | Full or partial dispensed | + +--- + +### Functional Workflow + +1. **Initiation**: A MedicationRequest is created for a patient. +2. **Dispensing**: Based on the request, a MedicationDispense is recorded when the medication is prepared and handed over. +3. **Status Tracking**: The status of the dispense is updated throughout the process (e.g., from `preparation` to `completed`). +4. **Inventory Management**: The dispense record aids in managing inventory levels within the healthcare facility. +5. **Billing**: A ChargeItem is associated with the dispense for billing purposes. + +--- diff --git a/docs/care/HMIS/Pharmacy/MedicationRequest.md b/docs/care/HMIS/Pharmacy/MedicationRequest.md new file mode 100644 index 0000000..ee4f263 --- /dev/null +++ b/docs/care/HMIS/Pharmacy/MedicationRequest.md @@ -0,0 +1,63 @@ +# Medication Request + +### Summary + +A [**MedicationRequest**](https://hl7.org/fhir/medicationrequest.html) is an order or request for both the supply of medication and instructions for its administration to a patient. It represents the prescriber's intent for a medication to be supplied and/or administered. + +--- + +### Key Purpose + +- Create and track medication orders/prescriptions +- Document medication instructions and dosage requirements +- Facilitate regular and PRN (as needed) medications[Wikipedia+7Flexpa+7ExecuteCommands+7](https://www.flexpa.com/docs/fhir/medication-request?utm_source=chatgpt.com) + +--- + +### Core Components + +- Medication details (drug, form, strength) +- Dosage instructions +- Timing and frequency +- Route of administration +- Quantity/duration +- Patient and prescriber information + +--- + +### Core Relationships + +| Field | Reference Resource | Description | +| ------------ | ------------------ | -------------------------------------------------------- | +| `subject` | Patient | The patient for whom the medication is prescribed. | +| `encounter` | Encounter | The encounter during which the prescription was created. | +| `medication` | Medication | The medication being prescribed. | +| `requester` | Practitioner | The individual who initiated the prescription. | + +--- + +### Supported Fields + +| Field Name | Type | Description | +| -------------- | ------------- | ---------------------------------------- | +| `Medicine` | string | Medicine name | +| `Dosage` | string | Dosage suggested | +| `Frequency` | string | Frequency of medication | +| `Duration` | string | Duration of medicine administration | +| `Instructions` | text | Additional instructions | +| `Route` | text | Administration route | +| `Site` | text | Body site | +| `Method` | text | Administration method | +| `Intent` | text | Medicine intent | +| `Authored_on` | date and time | Prescribed on | +| `Note` | text | Additional notes about the prescription. | + +--- + +### Functional Workflow + +1. **Prescription Creation**: A healthcare provider creates a MedicationRequest during a patient encounter. +2. **Review and Approval**: The prescription is reviewed and approved as per facility protocols. +3. **Dispensing**: The pharmacy dispenses the medication as per the prescription details. +4. **Administration and Monitoring**: The patient administers the medication, and adherence is monitored. +5. **Status Updates**: The status of the MedicationRequest is updated based on the medication's lifecycle (e.g., completed, stopped). diff --git a/docs/care/HMIS/Pharmacy/Product.md b/docs/care/HMIS/Pharmacy/Product.md new file mode 100644 index 0000000..b245247 --- /dev/null +++ b/docs/care/HMIS/Pharmacy/Product.md @@ -0,0 +1,62 @@ +# Product + +### Summary + +A product in Care refers to anything that can be purchasable from the facility, this could be [medication](https://build.fhir.org/medication.html), [nutritional product](https://build.fhir.org/nutritionproduct.html) or consumables. All of these items can be requested through Medication request for a patient ( The terminology is confusion, but it made sense at the time ), requested products are dispensed through Medication Dispense. + +Since product is a culmination of multiple resources references maintained by FHIR, It should be possible to create resources of theses types when creating integrations with FHIR, the spec for the Product resource will deviate from FHIR significantly while still being able to create the individual resourse when needed. + +Product is an instantiation of Product Knowledge, All relevant details will always be present in Product Knowledge, the Product resource will only capture data that is unique to the particular batch in question, like batch no, expiry etc.. + +A Product will have a link to a charge item definition as well, this can help create charge items whenever this particular medication is billed. + +--- + +### Key Purpose + +- Represent purchasable items within the facility. +- Differentiate between general product information (Product Knowledge) and batch-specific details. +- Integrate with billing systems through Charge Item Definitions. +- Ensure compatibility with FHIR resources for interoperability. + +--- + +### Core Data Structure – Essential Fields + +- **`product_knowledge`**: Reference to the Product Knowledge resource containing general information about the product. +- **`batch_number`**: The specific batch number of the product. +- **`expiry_date`**: The expiration date of the product batch. +- **`charge_item_definition`**: Reference to the Charge Item Definition associated with the product. +- **`status`**: Current status of the product (e.g., active, inactive). + +--- + +### Core Relationships + +| Field | Reference Resource | Description | +| ------------------------ | -------------------- | -------------------------------------------- | +| `product_knowledge` | ProductKnowledge | General information about the product. | +| `charge_item_definition` | ChargeItemDefinition | Billing details associated with the product. | + +--- + +### Supported Fields + +| Field Name | Type | Description | +| ------------------------ | --------- | ------------------------------------------------------- | +| `product_knowledge` | Reference | Link to the general product information. | +| `batch_number` | string | Unique identifier for the product batch. | +| `expiry_date` | date | Expiration date of the product batch. | +| `charge_item_definition` | Reference | Link to the billing definition for the product. | +| `status` | code | Current status of the product (e.g., active, inactive). | + +--- + +### Functional Workflow + +1. **Product Knowledge Creation**: General information about a product is entered into the Product Knowledge resource. +2. **Product Instantiation**: For each batch received, a Product resource is created, referencing the Product Knowledge and including batch-specific details. +3. **Billing Integration**: The Product resource links to a Charge Item Definition, ensuring accurate billing when the product is dispensed. +4. **Dispensing Process**: Products are dispensed to patients through the Medication Dispense process, with all relevant information captured. + +--- diff --git a/docs/care/HMIS/Pharmacy/ProductKnowledge.md b/docs/care/HMIS/Pharmacy/ProductKnowledge.md new file mode 100644 index 0000000..c77919a --- /dev/null +++ b/docs/care/HMIS/Pharmacy/ProductKnowledge.md @@ -0,0 +1,90 @@ +# Product Knowledge + +### Summary + +This resource stores all foundational information about a given product, foundational information is anything need not be duplicated across different individual products, ie ingredient lists, possible allergens, nutritional information and so on.. + +All Products will have a Product Knowledge item in Care. + +## Production Knowledge can be instance or facility level. + +### Key Purpose + +- Define comprehensive, facility-wide information about products. +- Standardize product data across different batches and instances. +- Facilitate integration with FHIR resources for interoperability. +- Support inventory management, prescribing, and dispensing processes. + +--- + +### Core Data Structure – Essential Fields + +- **`facility`**: Reference to the facility where the product is available (nullable). +- **`slug`**: A URL-friendly identifier for the product. +- **`status`**: Current status of the product knowledge entry (e.g., draft, active, retired, unknown). +- **`product_type`**: Type of product (e.g., Medication, NutritionProduct, Consumable). +- **`code`**: A code representing the product, with the value set depending on the product type. +- **`name`**: The primary name of the product. +- **`base_unit`**: The unit in which the product is measured or dispensed. +- **`names`**: A list of alternative names for the product, each with a specified name type. +- **`storage_guidelines`**: Instructions for storing the product, including notes, stability duration, and environmental settings. +- **`definition`**: Detailed information about the product's form, intended route(s) of administration, ingredients, nutrients, and drug characteristics. + +--- + +### Core Relationships + +| Field | Reference Resource | Description | +| ------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `facility` | Organization | The facility where the product is available. | +| `code` | CodeSystem | The coding system used to identify the product. | +| `names.name_type` | ValueSet | The type of name, bound to [InventoryItem Name Type](https://build.fhir.org/valueset-inventoryitem-nametype.html). | +| `definition.dose_form` | ValueSet | The form of the medication, bound to [Medication Form Codes](https://build.fhir.org/valueset-medication-form-codes.html). | +| `definition.intended_route` | ValueSet | The intended route(s) of administration, bound to [Route Codes](https://build.fhir.org/valueset-route-codes.html). | +| `definition.ingredients.substance` | Substance | The substance(s) that make up the product. | +| `definition.drug_characteristic.type` | ValueSet | The type of drug characteristic, bound to [Medication Knowledge Characteristic](https://build.fhir.org/valueset-medicationknowledge-characteristic.html). | + +--- + +### Supported Fields + +| Field Name | Type | Description | +| --------------------------------------------------- | --------------- | ----------------------------------------------------------------- | +| `facility` | Reference | Reference to the facility (nullable). | +| `slug` | string | URL-friendly identifier for the product. | +| `status` | code | Status of the product knowledge entry. | +| `product_type` | code | Type of product (e.g., Medication, NutritionProduct, Consumable). | +| `code` | CodeableConcept | Code representing the product. | +| `name` | string | Primary name of the product. | +| `base_unit` | CodeableConcept | Unit in which the product is measured or dispensed. | +| `names` | List | Alternative names for the product. | +| `names.name_type` | code | Type of name (e.g., trade name, brand name). | +| `names.name` | string | The alternative name. | +| `storage_guidelines` | List | Storage instructions for the product. | +| `storage_guidelines.note` | string | Additional notes on storage. | +| `storage_guidelines.stability_duration` | Duration | Duration for which the product remains stable. | +| `storage_guidelines.environmental_setting` | List | Environmental conditions for storage. | +| `storage_guidelines.environmental_setting.type` | code | Type of environmental condition. | +| `storage_guidelines.environmental_setting.value` | string | Value of the environmental condition. | +| `definition` | BackboneElement | Detailed definition of the product. | +| `definition.dose_form` | CodeableConcept | Form of the medication. | +| `definition.intended_route` | List | Intended route(s) of administration. | +| `definition.ingredients` | List | Ingredients of the product. | +| `definition.ingredients.is_active` | boolean | Indicates if the ingredient is active. | +| `definition.ingredients.substance` | CodeableConcept | Substance that makes up the ingredient. | +| `definition.ingredients.strength` | BackboneElement | Strength information of the ingredient. | +| `definition.ingredients.strength.strength_ratio` | Ratio | Strength ratio of the ingredient. | +| `definition.ingredients.strength.strength_quantity` | Quantity | Strength quantity of the ingredient. | +| `definition.nutrients` | List | Nutritional components of the product. | +| `definition.drug_characteristic` | List | Characteristics of the drug. | +| `definition.drug_characteristic.type` | CodeableConcept | Type of drug characteristic. | +| `definition.drug_characteristic.value` | string | Value of the drug characteristic. | + +--- + +### Functional Workflow + +1. **Creation**: A Product Knowledge entry is created with comprehensive details about a product, including its classification, composition, and storage guidelines. +2. **Reference**: Individual Product instances reference the Product Knowledge entry, inheriting its general attributes while specifying batch-specific details. +3. **Integration**: The Product Knowledge resource integrates with FHIR resources like MedicationKnowledge and NutritionProduct, facilitating interoperability across systems. +4. **Maintenance**: Updates to product information, such as changes in composition or storage guidelines, are made within the Product Knowledge resource, ensuring consistency across all related Product instances. diff --git a/docs/care/HMIS/Pharmacy/README.md b/docs/care/HMIS/Pharmacy/README.md new file mode 100644 index 0000000..8703029 --- /dev/null +++ b/docs/care/HMIS/Pharmacy/README.md @@ -0,0 +1,41 @@ +# Pharmacy + +## Key Pharmacy Concepts + +This table outlines the primary components of the CARE Pharmacy Module, detailing their roles and associated FHIR resources. +| **Concept** | **FHIR Resource** | **Description** | +| --- | --- | --- | +| **Patient** | `Patient` | Represents an individual receiving healthcare services. | +| **Encounter** | `Encounter` | An interaction between a patient and healthcare provider(s) for the purpose of providing healthcare service(s). | +| **Medication Request** | `MedicationRequest` | An order or request for both the supply of the medication and the instructions for administration. | +| **Medication Dispense** | `MedicationDispense` | Indicates that a medication product is to be or has been dispensed for a named person/patient. | +| **Inventory Item** | `InventoryItem` | Represents a product in the inventory, including details like quantity, location, and status. | +| **Product** | `Medication` | The specific medication product, including its identification and definition. | +| **Product Knowledge** | `MedicationKnowledge` | Provides detailed information about a medication, including its composition, indications, and contraindications. | +| **Charge Item Definition** | `ChargeItemDefinition` | Defines the prices, factors, and conditions that apply to a billing code. | +| **Charge Item** | `ChargeItem` | Represents the provision of healthcare provider products for a patient, including billing details. | +| **Supply Request** | `SupplyRequest` | A record of a request to deliver a medication, substance, or device used in the healthcare setting. | +| **Supply Delivery** | `SupplyDelivery` | Records the delivery of a supply item. | +| **Location** | `Location` | Details and position information for a physical place where services are provided and resources are stored. | + +## High-Level Pharmacy Flow + +Below is a simplified look at how these pieces fit together: + +```mermaid +%%{init: {'theme':'redux'}}%% +flowchart LR + A[" Patient"] --> B[" Encounter"] + B --> C[" Medication Request"] + C --> D{" Drug Available in Pharmacy?"} + D -- Yes --> E[" Pharmacy Dispense Approval"] + D -- No --> F[" Notify for Substitution"] + E --> G[" Initiate Billing"] + G --> H{" Payment Completed?"} + H -- Yes --> I[" Medicine Dispensed"] + H -- No --> J[" Hold Dispensation"] +``` + +## Concept Diagram + +![Pharmacy Concept Diagram](../../../../static/img/care/HMIS/Pharmacy/Pharmacy%20Concept%20Diagram.svg) diff --git a/docs/care/HMIS/Pharmacy/SupplyDelivery.md b/docs/care/HMIS/Pharmacy/SupplyDelivery.md new file mode 100644 index 0000000..b1e9c4a --- /dev/null +++ b/docs/care/HMIS/Pharmacy/SupplyDelivery.md @@ -0,0 +1,76 @@ +# Supply Delivery + +### Summary + +The **Supply Delivery** resource in the CARE system records the delivery of healthcare-related items, such as medications, devices, or other supplies, to a specified location. It serves as a critical component in inventory management, ensuring accurate tracking of stock levels within healthcare facilities. + +This resource aligns with FHIR's [SupplyDelivery](https://build.fhir.org/supplydelivery.html) resource, facilitating standardized communication and interoperability in supply chain processes. + +--- + +### Key Purpose + +- Document the delivery of healthcare items to specific locations. +- Facilitate inventory management by updating stock levels upon delivery. +- Support auditing and tracking of supply movements within the facility. +- Enable integration with supply requests and inventory systems for seamless operations.[MyDiagram](https://mydiagram.online/process-flow-diagram-healthcare/?utm_source=chatgpt.com)[HL7 Terminology+2OntoServer+2FHIR Build+2](https://tx.ontoserver.csiro.au/fhir/CodeSystem/supplydelivery-status?utm_source=chatgpt.com) + +--- + +### Core Data Structure – Essential Fields + +- **`supply_request`**: Reference to the associated Supply Request. +- **`status`**: Current status of the delivery (e.g., in-progress, completed, abandoned, entered-in-error). +- **`status_history`**: Audit trail of status changes for the delivery. +- **`delivery_type`**: Type of supply being delivered (e.g., medication, device). +- **`stage`**: Stage of the delivery process (e.g., dispatched, received). +- **`supplied_item_quantity`**: Quantity of the item delivered. +- **`supplied_item_condition`**: Condition of the item upon delivery (e.g., intact, damaged). +- **`supplied_item`**: Reference to the specific product delivered. +- **`origin`**: Location from which the item was dispatched. +- **`destination`**: Location to which the item was delivered.[MyDiagram](https://mydiagram.online/process-flow-diagram-healthcare/?utm_source=chatgpt.com)[InterSystems Documentation](https://docs.intersystems.com/irisforhealthlatest/csp/documatic/%25CSP.Documatic.cls?CLASSNAME=HS.FHIR.DTL.vDSTU2.Model.Resource.SupplyDelivery&LIBRARY=HSCUSTOM&utm_source=chatgpt.com) + +--- + +### Core Relationships + +| Field | Reference Resource | Description | +| ---------------- | ------------------ | -------------------------------------------- | +| `supply_request` | SupplyRequest | The original request prompting the delivery. | +| `supplied_item` | Product | The specific item being delivered. | +| `origin` | Location | The source location of the delivery. | +| `destination` | Location | The target location for the delivery. | + +--- + +### Supported Fields + +**Status Codes:** + +- `in-progress`: Delivery is currently underway. +- `completed`: Delivery has been successfully completed. +- `abandoned`: Delivery was not completed. +- `entered-in-error`: Delivery record was created in error.[IdentiMedical](https://identimedical.com/the-importance-of-hospital-inventory-management/?utm_source=chatgpt.com)[FHIR Build](https://build.fhir.org/codesystem-supplydelivery-status.html?utm_source=chatgpt.com) + +**Delivery Types:** + +- `medication`: Delivery of medication items. +- `device`: Delivery of medical devices. +- `biologically-derived-product`: Delivery of biologically derived products.[Zus Health+2FHIR Build+2FHIR Build+2](https://build.fhir.org/supplydelivery-definitions.html?utm_source=chatgpt.com) + +**Item Conditions:** + +- `intact`: Item delivered in good condition. +- `damaged`: Item delivered with damage. +- `expired`: Item delivered past its expiration date.[Medplum+3CData Software+3Karexpert+3](https://cdn.cdata.com/help/KIJ/jdbc/pg_table-supplydelivery.htm?utm_source=chatgpt.com) + +--- + +### Functional Workflow + +1. **Initiation**: A Supply Request is finalized, prompting the creation of a corresponding Supply Delivery with the stage set to "dispatched." +2. **Dispatch**: Items are deducted from the inventory of the origin location upon dispatch. +3. **Receipt**: Upon arrival, the destination location verifies the quantity and condition of the items. +4. **Inventory Update**: If accepted, items are added to the destination's inventory. +5. **Discrepancy Handling**: If discrepancies or damages are noted, the delivery may be rejected, prompting a return to the origin and the creation of a new Supply Delivery. +6. **Audit Trail**: All status changes and actions are recorded in the status history for auditing purposes. diff --git a/docs/care/HMIS/Pharmacy/SupplyRequest.md b/docs/care/HMIS/Pharmacy/SupplyRequest.md new file mode 100644 index 0000000..57312ac --- /dev/null +++ b/docs/care/HMIS/Pharmacy/SupplyRequest.md @@ -0,0 +1,77 @@ +# Supply Request + +### Summary + +The **Supply Request** resource in the CARE system represents a formal request for the provision of healthcare-related items such as medications, devices, or other supplies. It serves as the initial step in the supply chain workflow, capturing the intent to procure or transfer items within or between facilities. + +This resource aligns with FHIR's [SupplyRequest](https://build.fhir.org/supplyrequest.html) resource, facilitating standardized communication and interoperability in supply management processes.[FHIR Build](https://build.fhir.org/supplyrequest.html?utm_source=chatgpt.com) + +--- + +### Key Purpose + +- Initiate requests for the supply of healthcare items. +- Facilitate inventory management by tracking requested items. +- Support logistics and procurement workflows within healthcare facilities. +- Enable integration with downstream processes such as supply delivery and inventory updates. + +--- + +### Core Data Structure – Essential Fields + +- **`id`**: Unique identifier for the supply request. +- **`status`**: Current status of the request (e.g., draft, active, suspended, completed, entered-in-error, cancelled). +- **`category`**: Classification of the supply request (e.g., central, non-stock). +- **`priority`**: Indicates the urgency of the request (e.g., routine, urgent, asap, stat). +- **`item`**: The item being requested, represented as a reference to a resource (e.g., Medication, Device) or a code. +- **`quantity`**: The amount of the item requested. +- **`occurrence`**: The timeframe when the request should be fulfilled. +- **`authoredOn`**: Date when the request was created. +- **`requester`**: Individual or organization making the request. +- **`supplier`**: Potential suppliers who can fulfill the request. +- **`reasonCode`**: Reason for the request. +- **`deliverFrom`**: Origin location for the supply. +- **`deliverTo`**: Destination location for the supply.[FHIR Build+2Medplum+2HAPI FHIR+2](https://www.medplum.com/docs/api/fhir/resources/supplyrequest?utm_source=chatgpt.com)[InterSystems Documentation+1FHIR Build+1](https://docs.intersystems.com/irisforhealthlatest/csp/documatic/%25CSP.Documatic.cls?CLASSNAME=HS.FHIR.DTL.vSTU3.Model.Resource.SupplyDelivery&LIBRARY=HSLIB&utm_source=chatgpt.com)[FHIR Build](https://build.fhir.org/supplydelivery-definitions.html?utm_source=chatgpt.com)[Medical Packaging Inc., LLC+2FHIR Build+2IdentiMedical+2](https://build.fhir.org/resourcelist.html?utm_source=chatgpt.com) + +--- + +### Core Relationships + +| Field | Reference Resource | Description | +| ------------- | -------------------------- | ------------------------------------------ | +| `item` | Medication, Device | The specific item being requested. | +| `requester` | Practitioner, Organization | Entity initiating the supply request. | +| `supplier` | Organization | Potential supplier to fulfill the request. | +| `deliverFrom` | Location | Origin location for the supply. | +| `deliverTo` | Location | Destination location for the supply. | + +--- + +### Supported Fields + +**Status Codes:** + +- `draft`: The request has been created but is not yet active. +- `active`: The request is currently active and awaiting fulfillment. +- `suspended`: The request has been temporarily suspended. +- `completed`: The request has been fulfilled. +- `entered-in-error`: The request was entered in error and is not valid. +- `cancelled`: The request has been cancelled. + +**Priority Levels:** + +- `routine`: Standard priority. +- `urgent`: High priority. +- `asap`: As soon as possible. +- `stat`: Immediate action required. + +--- + +### Functional Workflow + +1. **Request Initiation**: A supply request is created by a practitioner or organization, specifying the item, quantity, and delivery details. +2. **Review and Approval**: The request is reviewed and approved by the appropriate authority within the facility. +3. **Fulfillment Planning**: Upon approval, the request is forwarded to potential suppliers or internal departments for fulfillment planning. +4. **Supply Delivery**: Once the supply is prepared, a corresponding Supply Delivery is initiated to track the movement of items. +5. **Inventory Update**: Upon receipt, the inventory at the destination location is updated to reflect the new stock levels. +6. **Request Completion**: The supply request status is updated to 'completed' to indicate fulfillment. diff --git a/docs/care/HMIS/Scheduling/AvailabilityException.md b/docs/care/HMIS/Scheduling/AvailabilityException.md new file mode 100644 index 0000000..13b0f09 --- /dev/null +++ b/docs/care/HMIS/Scheduling/AvailabilityException.md @@ -0,0 +1,10 @@ +# Availability Exception + +### Summary + +In CARE, an **Availability Exception** represents periods when a schedulable user (e.g., a healthcare provider) is unavailable for appointments, such as during vacations, training sessions, or unforeseen absences. This concept aligns with FHIR's approach to managing non-availability through the `Schedule` and `Slot` resources. + +### Design Philosophy + +- **Explicit Non-Availability**: Clearly define periods when a provider is not available to prevent scheduling conflicts. +- **Integration with Scheduling**: Ensure that availability exceptions are considered when generating available slots for appointments. diff --git a/docs/care/HMIS/Scheduling/Encounter.md b/docs/care/HMIS/Scheduling/Encounter.md new file mode 100644 index 0000000..466224d --- /dev/null +++ b/docs/care/HMIS/Scheduling/Encounter.md @@ -0,0 +1,64 @@ +# Encounter + +### Summary + +Encounters represent interactions between a patient and a healthcare provider. + +At its core, it represents a documented contact between a patient and healthcare provider, serving as a container for clinical events and activities. + +## Key Purpose + +- Document and track patient-provider interactions +- Establish context for clinical activities and observations +- Support billing and administrative workflows +- Enable care coordination across different settings +- Maintain chronological record of patient care events + +### Core Relationships + +| CARE Concept | FHIR Resource | Purpose | +| ----------------------- | ------------------ | ----------------------------------------------------------- | +| Patient | `Patient` | Represents the individual receiving care | +| Healthcare Provider | `Practitioner` | Represents the individual providing care | +| Provider Role | `PractitionerRole` | Defines the provider's role and association with a facility | +| Appointment Reservation | `Appointment` | Represents the booked appointment leading to the encounter | +| Encounter Record | `Encounter` | Captures the details of the patient-provider interaction | +| Location | `Location` | Specifies where the encounter took place | +| Service Request | `ServiceRequest` | Indicates the request that initiated the encounter | +| Diagnostic Report | `DiagnosticReport` | Contains findings resulting from the encounter | + +### Supported Fields (Encounter) + +| Field Name | Description | Example | +| ----------------- | ------------------------------------------------------------- | ------------------------------------------------ | +| `id` | Unique identifier for the encounter | `encounter-001` | +| `status` | The current status of the encounter | `in-progress` | +| `class` | Classification of the encounter (e.g., inpatient, outpatient) | `outpatient` | +| `type` | Specific type of encounter | `Consultation` | +| `serviceType` | Specific type of service provided | `General Practice` | +| `subject` | Reference to the patient involved in the encounter | `Patient/patient-001` | +| `participant` | List of participants involved in the encounter | See participant details below | +| `appointment` | Reference to the associated appointment | `Appointment/appointment-001` | +| `period` | The start and end time of the encounter | `2025-06-15T09:00:00Z` to `2025-06-15T09:30:00Z` | +| `reasonCode` | Reason for the encounter | `Routine check-up` | +| `diagnosis` | List of diagnoses relevant to the encounter | `Hypertension` | +| `location` | List of locations where the patient has been | `Clinic Room 1` | +| `serviceProvider` | The organization responsible for the encounter | `Organization/clinic-001` | + +**Participant Details:** + +Each participant includes: + +- `type`: Role of the participant (e.g., primary performer) +- `individual`: Reference to the participant (e.g., Practitioner) +- `period`: Time period during which the participant was involved +- `status`: Participation status (e.g., accepted) + +--- + +### Functional Workflow + +1. **Initiate Encounter**: When a patient arrives for a scheduled appointment, an `Encounter` resource is created to document the interaction. +2. **Record Details**: Capture information such as participants, reasons, diagnoses, and locations associated with the encounter. +3. **Update Status**: As the encounter progresses, update the `status` field to reflect its current state (e.g., in-progress, completed). +4. **Link to Outcomes**: Associate the encounter with resulting resources like `DiagnosticReport` or `Observation` to maintain a comprehensive record. diff --git a/docs/care/HMIS/Scheduling/README.md b/docs/care/HMIS/Scheduling/README.md index 1dab3b6..6ef6a55 100644 --- a/docs/care/HMIS/Scheduling/README.md +++ b/docs/care/HMIS/Scheduling/README.md @@ -1 +1,33 @@ # Scheduling + +## Key Scheduling Concepts + +| **Concept** | **Description** | +| --------------------------- | ------------------------------------------------------------------------------------------ | +| **SchedulableUserResource** | A healthcare provider (e.g., doctor, nurse) whose time can be scheduled within a facility. | +| **AvailabilityException** | Specific time periods when a provider is unavailable (e.g., leave, holidays). | +| **Schedule** | Defines recurring availability patterns (e.g., daily 9 AM – 5 PM) for a provider. | +| **Availability** | Specific dates/times within a schedule when appointments can be booked. | +| **TokenSlot** | A concrete, bookable time unit available for patient appointments. | +| **TokenBooking** | Represents a confirmed appointment, linking a patient to a specific time slot. | + +## High-Level Scheduling Flow + +Below is a simplified look at how these pieces fit together: + +```mermaid +%%{init: {'theme':'redux'}}%% +flowchart LR + A[" Facility"] --> B[" User (Doctor/Staff)"] + B --> C[" Schedule Created"] + C --> D{" Availability"} + D -- Yes --> E[" Token Slot"] + D -- No --> F[" No Slots (Holiday/Blocked)"] + E --> G[" Token Booked"] + G --> I[" Patient"] + I --> J[" Encounter Started"] +``` + +## Concept Diagram + + ![Scheduling Concept Diagram](../../../../static/img/care/HMIS/Scheduling/Scheduling%20Concept%20Diagram.svg) diff --git a/docs/care/HMIS/Scheduling/SchedulableUserResource.md b/docs/care/HMIS/Scheduling/SchedulableUserResource.md new file mode 100644 index 0000000..e2cad05 --- /dev/null +++ b/docs/care/HMIS/Scheduling/SchedulableUserResource.md @@ -0,0 +1,34 @@ +# Schedulable User Resource + +### Summary + +In CARE, a **Schedulable User Resource** represents a healthcare provider (e.g., doctor, nurse) whose availability can be scheduled for patient appointments. + +This resource sits at the top of the scheduling hierarchy and governs the **availability**, **exceptions**, and **schedules** for each user. It acts as the anchor point from which **available slots** are derived and **token bookings** are made. + +### Design Philosophy + +- **Explicitly Declared Availability**: Not all users are schedulable by default — only those marked as such. +- **Facility-Scoped**: A user is schedulable within the context of a healthcare facility. +- **Encapsulates Multiple Scheduling Layers**: Availability, exceptions, and schedule patterns are defined here. + +### Core Relationships + +| Related Resource | Purpose | +| ----------------------- | ----------------------------------------------------------- | +| `Facility` | The organization within which the user operates | +| `Availability` | Repeating time blocks when this user is generally available | +| `AvailabilityException` | Overrides or cancels availability (e.g., leave, holiday) | +| `TokenSlot` | Actual bookable slots derived from the user's availability | +| `TokenBooking` | A confirmed reservation of a slot for a patient | +| `Encounter` | Generated upon successful booking? | + +### Functional Workflow + +1. A user is flagged as "schedulable" during onboarding or profile setup. +2. Admin assigns this user to a facility and defines: + - **Schedule** (recurring patterns) + - **Availability Exceptions** (leaves, conferences, holidays) +3. CARE dynamically calculates token slots based**Availability** ?and generates **Token Slots**. +4. Patients or staff can book available slots against this user. +5. Each successful booking leads to a **TokenBooking** and an **Encounter**. diff --git a/docs/care/HMIS/Scheduling/Schedule.md b/docs/care/HMIS/Scheduling/Schedule.md new file mode 100644 index 0000000..f0c33cb --- /dev/null +++ b/docs/care/HMIS/Scheduling/Schedule.md @@ -0,0 +1,12 @@ +# Schedule + +### Summary + +In CARE, the **Schedule** resource represents the availability of a healthcare provider (e.g., doctor, nurse) for appointments. It defines the time periods during which the provider is available to provide services. ~~This concept aligns with FHIR's `Schedule` resource~~, which serves as a container for time slots that can be booked using an appointment + +--- + +### Functional Workflow + +1. **Define Schedule**: Create a `Schedule` resource for each provider, specifying the time periods during which they are available. +2. **Generate Slots**: Within the schedule, create `Slot` resources representing specific time intervals available for booking.? diff --git a/docs/care/HMIS/Scheduling/TokenBooking.md b/docs/care/HMIS/Scheduling/TokenBooking.md new file mode 100644 index 0000000..118d7bc --- /dev/null +++ b/docs/care/HMIS/Scheduling/TokenBooking.md @@ -0,0 +1,18 @@ +# Token Booking + +### Summary + +In CARE, a **Token Booking** represents the reservation of a specific time slot by a patient for a healthcare service. It describes the details of a scheduled meeting between a patient and a healthcare provider. + +### Design Philosophy + +- **Integration with Slots**: Each appointment is linked to a `Slot` resource that defines the specific time interval. +- **Status Tracking**: Monitor the status of appointments to manage workflows effectively. + +--- + +### Functional Workflow + +1. **Select Available Slot**: Patient selects an available `Slot` for the desired service. +2. **Create Appointment**: System creates an `Appointment` resource linking the patient, provider, and selected slot. +3. **Manage Appointment**: Appointment status is updated as needed (e.g., checked-in, completed). diff --git a/docs/care/HMIS/Scheduling/TokenSlot.md b/docs/care/HMIS/Scheduling/TokenSlot.md new file mode 100644 index 0000000..3c875ea --- /dev/null +++ b/docs/care/HMIS/Scheduling/TokenSlot.md @@ -0,0 +1,5 @@ +# Token Slot + +### Summary + +In CARE, a **TokenSlot** represents a specific time interval during which a healthcare provider is available for appointments. This concept aligns with FHIR's Slot resource, which defines a slot of time on a schedule that may be available for booking appointments. diff --git a/static/img/care/HMIS/Billing/Billing Concept Diagram.svg b/static/img/care/HMIS/Billing/Billing Concept Diagram.svg new file mode 100644 index 0000000..5eab60d --- /dev/null +++ b/static/img/care/HMIS/Billing/Billing Concept Diagram.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/static/img/care/HMIS/Labs/Labs Concept Diagram.svg b/static/img/care/HMIS/Labs/Labs Concept Diagram.svg new file mode 100644 index 0000000..47e8c43 --- /dev/null +++ b/static/img/care/HMIS/Labs/Labs Concept Diagram.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/static/img/care/HMIS/Pharmacy/Pharmacy Concept Diagram.svg b/static/img/care/HMIS/Pharmacy/Pharmacy Concept Diagram.svg new file mode 100644 index 0000000..205b0e0 --- /dev/null +++ b/static/img/care/HMIS/Pharmacy/Pharmacy Concept Diagram.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/static/img/care/HMIS/Scheduling/Scheduling Concept Diagram.svg b/static/img/care/HMIS/Scheduling/Scheduling Concept Diagram.svg new file mode 100644 index 0000000..8f57188 --- /dev/null +++ b/static/img/care/HMIS/Scheduling/Scheduling Concept Diagram.svg @@ -0,0 +1 @@ + \ No newline at end of file