Encounter Domain - Workflow Narrative

A conversational guide to understanding clinical visit documentation

What is an Encounter?

An encounter represents a clinical interaction between a patient and a healthcare provider. Think of it as a "visit" container - when a patient comes in to see their doctor, that creates an encounter.

But an encounter is more than just a timestamp. It's the organizing structure for all the clinical documentation that happens during that visit. The diagnoses made, medications prescribed, observations recorded, procedures performed - they all connect back to an encounter.

The encounter is like a folder that groups together everything that happened during a specific clinical interaction.

Creating an Encounter

The Trigger

Encounters can be created in two ways. Most commonly, they're created from an existing appointment. When a patient arrives for their scheduled visit and the practitioner starts seeing them, the appointment transitions to an encounter.

Alternatively, encounters can be created directly for walk-in patients or situations where no prior appointment existed.

The Creation Flow

When the EncounterService.create_patient_encounter() method is called, several things happen in sequence.

First, the service validates that the patient exists and belongs to the specified organization. You can't create an encounter for a patient that doesn't exist or belongs to a different organization.

If a practitioner ID is provided, that gets validated too. The encounter will be linked to this practitioner as the primary provider for the visit.

Setting Initial Values

The encounter is created with several default values:

status is set to "planned" or "in-progress"
documentation_status is set to "draft"
encounter_date is set to the provided date or current time
type defaults to "ambulatory" (outpatient visit)

The created_by_user field captures who initiated this encounter for audit purposes.

Activity Event

Like most significant operations, encounter creation triggers an activity event. The event type is ENCOUNTER_CREATED and includes the patient name, practitioner name, and encounter type. This shows up in activity feeds and can trigger notifications to relevant care team members.

ACL Auto-Grant

If the organization has ACL enabled with auto-grant rules, creating an encounter can automatically grant the creating practitioner access to this patient. The logic is: if you're creating a clinical encounter with a patient, you clearly need access to their records.

The auto-grant typically provides WRITE permission with a configurable expiration (often 180 days for encounters).

Encounter Notes - The New Model

Multiple Notes Per Encounter

The system has evolved to support multiple notes per encounter. This is important because in a real clinical setting, multiple providers might document on the same visit.

A primary care physician might write their assessment note. A nurse might document vital signs separately. A specialist consultant might add their own note. All of these are linked to the same encounter but are separate EncounterNote entries.

Legacy Compatibility

The Encounter model still has fields like notes and chief_complaint for backward compatibility with older API consumers. New implementations should use the EncounterNote model through the notes_list relationship.

Documentation Types

Each encounter note has a note_type field that categorizes it:

Progress notes (the most common)
SOAP notes (Subjective, Objective, Assessment, Plan format)
Consultation notes
Procedure notes
Discharge summaries

And each note has its own documentation_status - draft, submitted, final, or amended.

Retrieving Encounters

By Patient

The most common query pattern is getting encounters for a specific patient. The EncounterService.get_patient_encounters() method returns a paginated list of encounters ordered by date (most recent first).

This uses eager loading to fetch the related patient and practitioner data in the same query. Without eager loading, you'd have the N+1 problem - one query for encounters, then separate queries for each patient and practitioner. With eager loading, it's all done in 2-3 queries total.

By Organization

For organization-wide views (like an admissions dashboard), encounters can be fetched across all patients with status filters. The get_organization_encounters() method supports filtering by documentation status - show me all draft encounters, or all encounters pending signature.

Single Encounter with Details

When opening a specific encounter, the get_encounter_by_id() method can include the full notes list. This gives you the container plus all the documentation within it.

Updating an Encounter

What Can Be Updated

Encounters have multiple fields that might change during the visit lifecycle:

status - from planned to in-progress to finished
documentation_status - from draft to submitted to final
chief_complaint - the patient's main concern
practitioner_id - if the assigned provider changes
tags - for organization-specific categorization

Security Checks

The update method includes security measures. The practitioner_id can only be changed to the current user's practitioner ID if they have one - this prevents one practitioner from assigning work to another without permission.

Organization filtering ensures you can only update encounters within your organization.

Change History

When encounters are updated, the ClinicalHistoryService records the change. This creates an audit trail showing what the values were before and after, who made the change, and when.

The change types are categorized: CREATED, UPDATED, DELETED. The resource type is ENCOUNTER. This history is valuable for compliance audits and understanding how clinical documentation evolved.

Activity Events

Significant encounter updates trigger activity events. Status changes in particular are events - transitioning an encounter to "finished" signals that the visit is complete and documentation should be finalized.

Encounter Status Workflow

Status Progression

Encounters follow a typical status progression:

planned - The encounter is scheduled but hasn't started
arrived - The patient has arrived at the facility
in-progress - The clinical interaction is happening
on-leave - The patient temporarily left (for tests, etc.)
finished - The clinical interaction is complete
cancelled - The encounter was cancelled before completion

Documentation Status

Parallel to the encounter status is the documentation status:

draft - Notes are being written
submitted - Provider has submitted for review
final - Documentation is complete and locked
amended - A correction was made after finalization

Workflow Implications

The combination of status and documentation status drives UI behavior. An in-progress encounter with draft documentation shows the full editing interface. A finished encounter with final documentation is read-only except for formal amendments.

Clinical Resources Within Encounters

The Container Relationship

When you're in the context of an encounter, you can create clinical resources that are linked to it:

Observations (vital signs, lab results)
Conditions (diagnoses made during this visit)
Medications (prescriptions written)
Allergies (newly discovered allergies)
Immunizations (vaccines administered)
Documents (uploaded files like images or reports)
Service Requests (lab orders, imaging orders)

Each of these resources has both a patient_id and an encounter_id. The patient link is primary - the resource belongs to the patient. The encounter link provides context - when was this recorded?

Bulk Collection

When you open an encounter for editing, the service can return all associated resources in a single response. This includes recent observations, active conditions, current medications, and known allergies.

The eager loading strategy fetches all these relationships efficiently. The frontend receives everything it needs to render the full encounter view without additional API calls.

Signing and Finalizing

The Sign-Off Workflow

Clinical documentation typically requires a sign-off process. When a practitioner has finished documenting an encounter, they submit it for review (or directly to final if they have that authority).

Submitting changes documentation_status to "submitted". Finalizing changes it to "final" and typically locks the encounter against further edits.

Digital Signatures

The system captures who signed the documentation and when. The updated_by_user field tracks this, along with the timestamp. For organizations with stricter requirements, additional signature metadata might be stored in the encounter's custom_data JSON field.

Amendment Process

If documentation needs to change after finalization (correction of an error, addition of missing information), it goes through an amendment process. The status changes to "amended", and the change is logged with a reason. The original documentation is preserved for audit purposes.

Connecting Encounters to Other Domains

From Appointments

Many encounters start as appointments. The appointment_id field links the encounter back to its source appointment. This connection allows you to trace from the scheduled time to the actual clinical interaction.

When an appointment is "checked in", it often creates or transitions to an encounter. The appointment gets a status update while the encounter becomes the active context.

To Billing

Encounters are the source of billable services. When an encounter is finalized, the billing domain can generate invoices based on the services documented. The encounter ID links charges back to the clinical encounter that generated them.

The diagnoses (conditions) from the encounter become the billing diagnoses. The procedures performed become billing line items. This clinical-to-financial flow is dependent on complete encounter documentation.

To AI Summaries

The AI domain uses encounter data to generate clinical summaries. The encounter notes, observations, and diagnoses provide the raw material for AI-generated patient summaries and visit recaps.

When a practitioner asks the AI to "summarize this visit", the system pulls the encounter context and provides it to the Gemini model for synthesis.

Performance Considerations

Eager Loading Is Critical

Encounter queries almost always need related data. You never just want the encounter - you want the patient name, practitioner name, and often the clinical resources within.

The service uses SQLAlchemy's selectinload to batch-fetch these relationships. Instead of 100 queries for 100 encounters, you get 2-3 queries total.

Pagination for Lists

Patients can have many encounters over time. A patient who's been with a practice for years might have dozens or hundreds of encounters. Pagination ensures the system returns manageable chunks.

Default limits are typically 10-20 encounters per page, with total counts provided for UI pagination controls.

Status-Based Filtering

Most encounter list views filter by status. "Show me my draft encounters" or "show me today's in-progress encounters" are common queries. Database indexes on the status fields make these filtered queries fast.

Key Takeaways

Encounters are containers - they group clinical documentation for a visit
Multiple notes per encounter - different providers can document separately
Status workflows - encounters and documentation have parallel status progressions
Clinical resources attach - observations, medications, etc. link with encounter_id
Change history is tracked - updates are logged for compliance
Appointment connection - many encounters originate from scheduled appointments
Billing integration - finalized encounters feed the billing process

Next: Read about the Appointment Domain to understand scheduling workflows

အသုံးပြုသူ လက်စွဲစာအုပ်

Guides