05 — EHR Builder: Real-Time Record Assembly¶

Data Source (chat / document / agent / API)
    │
    ▼
Typed Event Emitted (e.g., clinical_entities_extracted, chat_data_collected)
    │
    ▼
EHR Builder Service subscribes and processes
    │
    ├──▶ Validate incoming data against FHIR R4 schema
    ├──▶ Conflict detection (compare new vs existing resources)
    ├──▶ Apply merge rules (see below)
    ├──▶ Store/update FHIR resources in PostgreSQL
    ├──▶ Update Neo4j graph (add/update nodes and relationships)
    ├──▶ Index in Qdrant (update patient clinical embedding)
    ├──▶ Recalculate intake_progress
    │
    ▼
SSE notification to frontend (EHR summary view refreshes)

class EHRBuilderService:
    async def process_event(self, event: Event) -> EHRUpdateResult:
        """Main entry point. Dispatches to appropriate handler based on event_type."""

    async def merge_clinical_entities(
        self, patient_id: str, tenant_id: str,
        entities: list[ClinicalEntity], source: str, confidence: float
    ) -> list[FHIRResource]:
        """Merge extracted entities into patient EHR with conflict resolution."""

    async def update_from_chat(
        self, patient_id: str, tenant_id: str,
        extracted_data: dict, source_message_id: str
    ) -> EHRUpdateResult:
        """Process structured data extracted from chat messages."""

    async def calculate_intake_progress(
        self, patient_id: str, tenant_id: str,
        procedure_code: str | None = None
    ) -> float:
        """Calculate intake completion percentage based on procedure requirements."""

    async def get_ehr_summary(
        self, patient_id: str, tenant_id: str
    ) -> EHRSummary:
        """Return complete EHR summary for display in left panel."""

    async def detect_conflicts(
        self, patient_id: str, existing: list[FHIRResource],
        incoming: list[FHIRResource]
    ) -> list[ConflictRecord]:
        """Detect conflicts between existing and incoming data."""

def calculate_progress(patient_id: str, procedure_code: str) -> float:
    """
    Calculate how complete the patient's intake is.
    Returns 0.0 to 1.0.

    Categories and weights:
    - Demographics (0.15): name, DOB, gender, nationality, contact
    - Medical history (0.25): conditions, surgeries, medications, allergies
    - Procedure-specific (0.25): required tests, imaging, specialist referrals
    - Preferences (0.10): language, dietary, gender preference, budget
    - Documents (0.15): required docs uploaded and parsed
    - Consent (0.10): all required consent purposes granted

    Each category: (fields_filled / fields_required) * weight
    Total: sum of all category scores
    """

┌─────────────────────────┐
│ Patient: Aisha          │
│ Progress: ████████░░ 78%│
├─────────────────────────┤
│ ▼ Conditions            │
│   • M17.11 OA right knee│
│     Source: X-ray report │
│     Confidence: 0.95     │
│   • E11 Type 2 diabetes │
│     Source: Chat         │
│     Confidence: 0.88     │
│   • I10 Hypertension    │
│     Source: Chat         │
│     Confidence: 0.85     │
├─────────────────────────┤
│ ▼ Medications           │
│   • Metformin 1000mg BID│
│   • Losartan 50mg QD    │
├─────────────────────────┤
│ ▼ Documents       3/5   │
│   ✅ Knee X-ray         │
│   ✅ Blood panel        │
│   ✅ HbA1c              │
│   ⬜ ECG (required)     │
│   ⬜ MRI (recommended)  │
├─────────────────────────┤
│ ▼ Allergies             │
│   • Latex (moderate)    │
└─────────────────────────┘