Encounters — the Encounter Type System

The encounter is the center of the platform. The Encounter Type System is the spine that connects what the patient says — "I have a cough and I'm due for my physical" — to what the practice does: book a right-sized slot with the right people and equipment, ask exactly the right questions (and never the same one twice), brief the clinician, and turn the answers into a treatment plan, the codes, and a clean claim. The appointment setup determines the encounter type and its length; the encounter type then drives every downstream step.

End-to-End Flow

Every encounter — regardless of type — runs the same spine. The encounter type decides which questions, resources, plan rules, and codes apply; the spine stays constant so staff and patients learn it once.

1. 1 · BookComplaintsPatient enters primary, secondary & tertiary concerns in the portal.
2. 2 · MatchType + lengthSuggestion engine maps complaints → encounter type(s) and total minutes.
3. 3 · ScheduleResourcesResource-graph solver finds a slot with the right people, rooms & equipment.
4. 4 · PrepareQuestionsPer-type questionnaires merge and de-duplicate across complaints.
5. 5 · ContextMedical recordPre-visit briefing pulls problems, meds, allergies, labs, outside records.
6. 6 · VisitAudio / AIAmbient scribe + minimal-click interview fill the structured encounter form.
7. 7 · DecideTreatment planAnswers fire plan rules → orders, Rx, referrals, follow-up — pre-checked.
8. 8 · CodeCoding & billingE/M level, CPT, ICD-10 & modifiers suggested with MDM rationale.
9. 9 · CloseSign-off → RCMSigned, coded note flows to claims; learning loop captures every edit.

Steps 1–3 are owned by Patient Portal + Scheduling; steps 4–7 by this module + Clinical Documentation; step 8 by Coding / CDS; step 9 by RCM.

Encounter Type Catalog

An encounter type is a first-class, versioned, org-scoped template — not a flat "visit type." It bundles the stages, resources, question set, treatment-plan rules, and coding hints for a kind of visit. Types fall into six categories and can be combined into a single right-sized composite visit.

A seventh, Pediatric Well-Child + Immunizations, and any number of practice-defined types are authored in the Encounter Type Editor. Full field-level schema (EncounterType, EncounterStage, ResourceRequirement) lives in the dev spec.

Stages are the unit of length

Each type is an ordered list of stages; the sum of stage durations is the visit length the scheduler books. A composite visit's length is the sum of its constituents minus the overlap the dedup engine removes.

Complaints & the Smart Suggestion Engine

During self-scheduling the patient enters up to three ranked concerns — a primary, secondary, and tertiary complaint. The suggestion engine turns that free text into the right encounter type(s) and a defensible total length, then shows the patient a plain-language recommendation they can accept or override.

1. Tokenize — lowercase, strip stop-words, stem each complaint.
2. Keyword match — match tokens against each type's ComplaintKeywords.
3. Score — sum match weights with a specificity bonus; suggest only above a 0.5 threshold.
4. Composite detection — if the patient also says "annual / checkup," combine Preventive + Acute into one visit.
5. Problem-list augmentation — if an active chronic problem (e.g. T2D) is on file, add the matching chronic follow-up type.

Phase 1 is rule-based keyword matching (transparent, auditable). Phase 2 adds a learned ranking model trained on accepted suggestions — see Learning Loop. The booking handoff to the resource-graph solver is owned by Scheduling.

Questions, prepped per type — asked once

Questions live in one global Question Bank and are referenced by encounter types. Each type ships a curated, ordered questionnaire; questions can be gated by a complaint keyword (ComplaintTrigger) or a conditional (ShowIfCondition, e.g. "show the pack-years question only if the patient smokes"). The same question can be required in one type and optional in another — that lives on the reference, not the question.

De-duplication across multiple complaints

When a visit combines types, the dedup engine guarantees the patient is never asked the same thing twice:

1. Collect every QuestionRef from each constituent type.
2. Group by QuestionID — a question used by several types appears once.
3. Union the complaint-trigger keywords across types.
4. Take the stricter required flag — required in any type ⇒ required overall.
5. If any type would show it unconditionally, it shows unconditionally.
6. Order shared questions first, then type-specific in constituent order.

Question, QuestionRef, and ChoiceOption schemas, plus the dedup merge rules in full, are in the dev spec.

The medical record, audio & AI in the room

Before the clinician walks in, the pre-visit briefing assembles the patient's longitudinal record — active problems, medications, allergies, recent labs and imaging, plus TEFCA-sourced outside records — alongside the de-duplicated pre-visit answers. The encounter opens as a structured form, not a blank note.

In the room, the ambient AI scribe streams the conversation into bounded, coded fields with an evidence link from every line back to the audio that justifies it. The clinician runs a minimal-click interview: the merged questionnaire is pre-answered from intake and the scribe, so the clinician confirms or corrects rather than types. AI is imperfect — so structure makes it safe: nothing reaches the patient's global record without an explicit accept.

Answers → treatment plan

Each encounter type carries a Treatment Plan Template: an ordered set of conditional PlanRules. As answers arrive, rules fire and assemble a proposed plan grouped for one-pass review — labs, imaging, referrals, prescriptions, follow-up, problem-list updates, screenings, and patient-education topics. Default rules arrive pre-checked; the clinician signs them off or edits.

Proposed orders flow to eRx, Labs, Imaging, and Referrals without leaving the encounter. The generated plan entity and modification patterns are in the dev spec.

Coding & billing, suggested from the visit

Each type carries a Coding Hint Set: a default E/M level, conditional E/M upgrades, common CPT codes, likely ICD-10 ranges, and modifier hints. The answer pattern and the assessment drive a suggested code set — with pre-written MDM rationale for audit defense — handed to Coding / CDS for the clinician to confirm.

• E/M level — defaults per type; upgrades when the documented MDM supports it (e.g. 3+ chronic conditions reviewed ⇒ 99214).
• CPT — preventive (99396), problem-oriented (99213/4), procedures (e.g. 11402).
• ICD-10 — type-typical ranges (Z00.00 adult exam; J00–J06 acute URI; E11.x diabetes).
• Modifiers — e.g. -25 when a significant, separately identifiable E/M occurs the same day as a procedure (the combined-visit case).

The signed, coded note flows to RCM for scrubbing and claim submission — see the dynamic RCM workflows & timelines.

Learning loop — it gets better every visit

Every clinician action is signal. Accepted suggestions, edited wording, rejected orders, added questions, and overridden encounter-type suggestions are captured and rolled up per encounter type. The platform surfaces these as proposed template improvements an admin reviews in the editor:

• Question tuning — questions that are always skipped get demoted; questions clinicians keep adding get promoted into the template.
• Plan-rule tuning — rules whose proposals are usually rejected lose their default-checked status.
• Coding accuracy — E/M suggestions are compared to final billed codes and to denial outcomes from RCM.
• Suggestion ranking — accepted vs. overridden encounter-type suggestions train the Phase-2 ranking model.

Practice admins author and version types in the Encounter Type Editor (stages, resources, questions, plan rules, coding hints) with safe activate/deactivate and full version history. Editor capabilities and wireframe are in the dev spec.

Encounter walkthroughs — end to end, every step

Each walkthrough follows one encounter type through the full spine — complaints → type/length → questions → record → audio/AI → plan → coding → sign-off — so you can see exactly what the patient, MA, and clinician each touch. (Walkthrough pages and the matching interactive demo flow are being built; the dev spec documents each as a detailed use case today.)

1. WT-1

   Annual Physical — Established Adult

   Preventive visit, screening-driven plan, 99396/99214. Use case →

2. WT-2

   Acute / Sick Visit

   Single complaint, focused questions, CXR rule, 99213. Use case →

3. WT-3

   New Patient Comprehensive

   Full history intake, 60 min, 99204. Use case →

4. WT-4

   Combined — Annual + Acute

   Composite visit, question dedup, modifier -25. Use case →

5. WT-5

   Chronic Follow-Up — Diabetes

   Problem-list driven, A1c/lipids, 99214. Use case →

6. WT-6

   Pediatric Well-Child + Immunizations

   Age-gated questions, vaccine schedule, screenings. Use case →

Delivery Phases

Success Metrics

• Right-sized visits: ≥ 80% of booked encounter types accepted by the patient without override.
• Question burden: 0 duplicate questions in composite visits; ≥ 30% fewer total questions vs. asking each type's set independently.
• Plan acceptance: ≥ 70% of default-checked plan actions signed without edit.
• Coding accuracy: suggested E/M matches final billed code ≥ 90% of the time; ≤ 2% downstream coding-related denials.
• Clinician clicks: ≤ 12 clicks median from room-in to sign-off for a standard follow-up.

Module Dependencies

• Upstream — Patient Portal collects complaints; Scheduling books the type's stages & resources; Eligibility attaches coverage/copay.
• Lateral — Clinical Documentation provides the ambient scribe & encounter form; Coding / CDS finalizes codes.
• Downstream — orders flow to eRx, Labs, Imaging, Referrals; the signed coded note flows to RCM; results & the after-visit plan render in the Patient Portal.

Try in the Demo

• Patient — enter complaints & get an encounter-type recommendation
• Doctor — minimal-click encounter interview & treatment plan
• Doctor — coding & billing suggestions from the visit

The interactive encounter / rules engine (complaint matching, live question dedup, answer-driven plan & coding) is being added to the demo for dr / nurse / PA / MA.