🏥 Telehealth Agent Architecture
Complete Flow Chart & Reference Guide
flowchart TD
%% ============= PATIENT INTERACTION LAYER =============
subgraph PATIENT_LAYER["👥 Patient Interaction Layer"]
direction LR
WEB["Web Portal"]
MOBILE["Mobile App"]
SMS_CH["SMS Channel"]
EMAIL_CH["Email Channel"]
PHONE["Phone/Voice"]
end
%% ============= CHANNEL ADAPTER =============
subgraph CHAN["🔄 Channel Adapter
(Message Normalization)"] direction TB CH1["Event Processor"] CH2["Protocol Converter"] CH3["Message Queue"] end PATIENT_LAYER --> CHAN %% ============= IDENTITY & SECURITY ============= subgraph IDG["🔐 Identity + Security Guard"] direction TB A1["JWT / OAuth 2.0"] A2["MFA Verification"] A3["RBAC + PHI ACL"] A4["Session Manager"] end CHAN --> IDG %% ============= DATABASE LAYER ============= subgraph DATABASE["🗄️ Database Layer
(HIPAA Compliant)"] direction TB subgraph CORE_DB["Core Records"] EHR_DB["EHR Database"] PATIENT_DB["Patient Records"] PROVIDER_DB["Provider Profiles"] end subgraph CLINICAL_DB["Clinical Data"] LAB_DB["Lab Results"] IMAGING_DB["Medical Imaging"] PRESCRIPTION_DB["Prescriptions"] VITALS_DB["Vital Signs"] end subgraph OPERATIONAL_DB["Operations"] SCHEDULING_DB["Appointments"] BILLING_DB["Billing Records"] INSURANCE_DB["Insurance Data"] COMMUNICATION_DB["Messages"] end end %% ============= CONTEXT LOADER ============= subgraph CXT["📋 Context Loader
(Encrypted • US Region)"] direction TB C1["EHR Retrieval"] C2["Lab & Imaging Fetch"] C3["Medication History"] C4["Insurance Verification"] C5["Vector Search"] note1(["All data encrypted AES-256
US-based HIPAA cluster
TLS 1.3 in transit"]) C1 --- note1 C2 --- note1 C3 --- note1 end IDG --> CXT DATABASE --> CXT %% ============= HEALTHCARE MODULES ============= subgraph HEALTH_MODULES["🏥 Healthcare Modules"] direction TB subgraph CLINICAL["Clinical Workflow"] VISITS["Visit Management"] TELEHEALTH["Telemedicine"] CARE_PLANS["Care Plans"] CLINICAL_NOTES["Clinical Notes"] end subgraph PHARMACY["Pharmacy Services"] RX_MGMT["Prescription Mgmt"] DRUG_INTERACTION["Drug Interactions"] FORMULARY["Formulary Check"] end subgraph DIAGNOSTICS["Diagnostics"] LAB_ORDERS["Lab Orders"] IMAGING_ORDERS["Imaging Orders"] RESULTS_REVIEW["Results Review"] end end %% ============= AI AGENT CORE ============= subgraph PRC["🤖 AI Prompt Composer"] direction TB P1["System Prompt"] P2["Clinical Guidelines"] P3["Patient Context"] P4["Escalation Rules"] end CXT --> PRC HEALTH_MODULES --> PRC %% ============= MODEL SELECTION ============= ROUTER{"🧠 Model Router
(Azure US-East)"} ROUTER -->|"Clinical/HIPAA"| M1["Azure GPT-4o
(Premium)"] ROUTER -->|"General/Cost-Eff"| M2["Llama 3.1
(Fine-tuned)"] PRC --> ROUTER %% ============= REASONING LOOP ============= M1 --> LLM_OUT M2 --> LLM_OUT subgraph LOOP["🔄 Reasoning + Tool Loop"] direction TB LLM_OUT["LLM Response"] Q{"Tools Needed?"} DRAFT["Draft Response"] LLM_OUT --> Q Q -->|"No"| DRAFT Q -->|"Yes"| TOOL_EXEC end %% ============= COMPREHENSIVE TOOL REGISTRY ============= subgraph TOOLS["🛠️ Healthcare Tool Registry"] direction TB subgraph CLINICAL_TOOLS["Clinical Tools"] EHR_WRITE["EHR Write"] LAB_ORDER["Lab Ordering"] RX_PRESCRIBE["E-Prescribing"] CARE_PLAN_UPDATE["Care Plan Update"] end subgraph OPERATIONAL_TOOLS["Operational Tools"] SCHEDULING["Appointment Booking"] BILLING_API["Billing API"] INSURANCE_CHECK["Insurance Verification"] REFERRAL_MGMT["Referral Management"] end subgraph COMMUNICATION_TOOLS["Communication"] SMS_SEND["SMS Notifications"] EMAIL_SEND["Email Alerts"] PORTAL_MSG["Portal Messaging"] PROVIDER_ALERT["Provider Alerts"] end end TOOL_EXEC["Tool Execution"] --> TOOLS TOOLS --> LLM_OUT %% ============= CLINICAL DECISION SUPPORT ============= subgraph CDS["⚕️ Clinical Decision Support"] direction TB DRUG_SAFETY["Drug Safety Checks"] ALLERGY_CHECK["Allergy Screening"] DOSAGE_CALC["Dosage Calculation"] PROTOCOL_CHECK["Protocol Compliance"] end TOOLS --> CDS CDS --> LLM_OUT %% ============= SAFETY & COMPLIANCE ============= DRAFT --> G1["🛡️ Clinical Safety Guard"] subgraph GUARDRAILS["🚨 Multi-Layer Guardrails"] direction TB G1 --> CLINICAL_REVIEW["Clinical Protocol Review"] G1 --> PHI_SCAN["PHI Leak Detection"] G1 --> DOSAGE_SAFETY["Dosage Safety Check"] G1 --> LEGAL_COMPLIANCE["Legal Compliance"] end GUARDRAILS -->|"Unsafe ↺"| LLM_OUT GUARDRAILS -->|"Safe ✓"| AUD %% ============= EXTERNAL INTEGRATIONS ============= subgraph EXTERNAL["🌐 External Systems"] direction TB SURESCRIPTS["Surescripts
(E-Prescribing)"] HEALTH_GORILLA["Health Gorilla
(Lab Results)"] STRIPE_BILLING["Stripe
(Billing)"] TWILIO_COMM["Twilio
(Communications)"] INSURANCE_API["Insurance APIs"] end TOOLS --> EXTERNAL %% ============= AUDIT & MONITORING ============= subgraph AUD["📊 Audit + Compliance Log"] direction TB CLINICAL_AUDIT["Clinical Actions Log"] PHI_ACCESS_LOG["PHI Access Tracking"] BILLING_AUDIT["Billing Event Log"] COMMUNICATION_LOG["Communication Log"] end subgraph MONITORING["📈 Real-time Monitoring"] direction TB CLINICAL_METRICS["Clinical KPIs"] PERFORMANCE_METRICS["Performance Metrics"] SECURITY_ALERTS["Security Monitoring"] COMPLIANCE_DASH["Compliance Dashboard"] end AUD --> MONITORING MONITORING --> RESP["✅ Secure Response Delivery"] %% ============= SOLUTIONS & OUTCOMES ============= subgraph SOLUTIONS["🎯 Clinical Solutions"] direction TB CHRONIC_CARE["Chronic Care Mgmt"] PREVENTIVE["Preventive Care"] ACUTE_CARE["Acute Care"] POPULATION_HEALTH["Population Health"] CARE_COORDINATION["Care Coordination"] end RESP --> SOLUTIONS SOLUTIONS --> PATIENT_LAYER %% ============= VISUAL STYLING ============= classDef core fill:#dfe8ff,stroke:#4c6ef5,color:#000,stroke-width:2px classDef clinical fill:#e8f5e8,stroke:#4caf50,color:#000,stroke-width:2px classDef data fill:#fff3e0,stroke:#ff9800,color:#000,stroke-width:2px classDef security fill:#fce4ec,stroke:#e91e63,color:#000,stroke-width:2px classDef ai fill:#f3e5f5,stroke:#9c27b0,color:#000,stroke-width:2px classDef external fill:#e0f2f1,stroke:#009688,color:#000,stroke-width:2px class PATIENT_LAYER,SOLUTIONS clinical class DATABASE,CXT,AUD,MONITORING data class IDG,GUARDRAILS security class PRC,ROUTER,M1,M2,LOOP,CDS ai class EXTERNAL,TOOLS external class CHAN,HEALTH_MODULES,RESP core
(Message Normalization)"] direction TB CH1["Event Processor"] CH2["Protocol Converter"] CH3["Message Queue"] end PATIENT_LAYER --> CHAN %% ============= IDENTITY & SECURITY ============= subgraph IDG["🔐 Identity + Security Guard"] direction TB A1["JWT / OAuth 2.0"] A2["MFA Verification"] A3["RBAC + PHI ACL"] A4["Session Manager"] end CHAN --> IDG %% ============= DATABASE LAYER ============= subgraph DATABASE["🗄️ Database Layer
(HIPAA Compliant)"] direction TB subgraph CORE_DB["Core Records"] EHR_DB["EHR Database"] PATIENT_DB["Patient Records"] PROVIDER_DB["Provider Profiles"] end subgraph CLINICAL_DB["Clinical Data"] LAB_DB["Lab Results"] IMAGING_DB["Medical Imaging"] PRESCRIPTION_DB["Prescriptions"] VITALS_DB["Vital Signs"] end subgraph OPERATIONAL_DB["Operations"] SCHEDULING_DB["Appointments"] BILLING_DB["Billing Records"] INSURANCE_DB["Insurance Data"] COMMUNICATION_DB["Messages"] end end %% ============= CONTEXT LOADER ============= subgraph CXT["📋 Context Loader
(Encrypted • US Region)"] direction TB C1["EHR Retrieval"] C2["Lab & Imaging Fetch"] C3["Medication History"] C4["Insurance Verification"] C5["Vector Search"] note1(["All data encrypted AES-256
US-based HIPAA cluster
TLS 1.3 in transit"]) C1 --- note1 C2 --- note1 C3 --- note1 end IDG --> CXT DATABASE --> CXT %% ============= HEALTHCARE MODULES ============= subgraph HEALTH_MODULES["🏥 Healthcare Modules"] direction TB subgraph CLINICAL["Clinical Workflow"] VISITS["Visit Management"] TELEHEALTH["Telemedicine"] CARE_PLANS["Care Plans"] CLINICAL_NOTES["Clinical Notes"] end subgraph PHARMACY["Pharmacy Services"] RX_MGMT["Prescription Mgmt"] DRUG_INTERACTION["Drug Interactions"] FORMULARY["Formulary Check"] end subgraph DIAGNOSTICS["Diagnostics"] LAB_ORDERS["Lab Orders"] IMAGING_ORDERS["Imaging Orders"] RESULTS_REVIEW["Results Review"] end end %% ============= AI AGENT CORE ============= subgraph PRC["🤖 AI Prompt Composer"] direction TB P1["System Prompt"] P2["Clinical Guidelines"] P3["Patient Context"] P4["Escalation Rules"] end CXT --> PRC HEALTH_MODULES --> PRC %% ============= MODEL SELECTION ============= ROUTER{"🧠 Model Router
(Azure US-East)"} ROUTER -->|"Clinical/HIPAA"| M1["Azure GPT-4o
(Premium)"] ROUTER -->|"General/Cost-Eff"| M2["Llama 3.1
(Fine-tuned)"] PRC --> ROUTER %% ============= REASONING LOOP ============= M1 --> LLM_OUT M2 --> LLM_OUT subgraph LOOP["🔄 Reasoning + Tool Loop"] direction TB LLM_OUT["LLM Response"] Q{"Tools Needed?"} DRAFT["Draft Response"] LLM_OUT --> Q Q -->|"No"| DRAFT Q -->|"Yes"| TOOL_EXEC end %% ============= COMPREHENSIVE TOOL REGISTRY ============= subgraph TOOLS["🛠️ Healthcare Tool Registry"] direction TB subgraph CLINICAL_TOOLS["Clinical Tools"] EHR_WRITE["EHR Write"] LAB_ORDER["Lab Ordering"] RX_PRESCRIBE["E-Prescribing"] CARE_PLAN_UPDATE["Care Plan Update"] end subgraph OPERATIONAL_TOOLS["Operational Tools"] SCHEDULING["Appointment Booking"] BILLING_API["Billing API"] INSURANCE_CHECK["Insurance Verification"] REFERRAL_MGMT["Referral Management"] end subgraph COMMUNICATION_TOOLS["Communication"] SMS_SEND["SMS Notifications"] EMAIL_SEND["Email Alerts"] PORTAL_MSG["Portal Messaging"] PROVIDER_ALERT["Provider Alerts"] end end TOOL_EXEC["Tool Execution"] --> TOOLS TOOLS --> LLM_OUT %% ============= CLINICAL DECISION SUPPORT ============= subgraph CDS["⚕️ Clinical Decision Support"] direction TB DRUG_SAFETY["Drug Safety Checks"] ALLERGY_CHECK["Allergy Screening"] DOSAGE_CALC["Dosage Calculation"] PROTOCOL_CHECK["Protocol Compliance"] end TOOLS --> CDS CDS --> LLM_OUT %% ============= SAFETY & COMPLIANCE ============= DRAFT --> G1["🛡️ Clinical Safety Guard"] subgraph GUARDRAILS["🚨 Multi-Layer Guardrails"] direction TB G1 --> CLINICAL_REVIEW["Clinical Protocol Review"] G1 --> PHI_SCAN["PHI Leak Detection"] G1 --> DOSAGE_SAFETY["Dosage Safety Check"] G1 --> LEGAL_COMPLIANCE["Legal Compliance"] end GUARDRAILS -->|"Unsafe ↺"| LLM_OUT GUARDRAILS -->|"Safe ✓"| AUD %% ============= EXTERNAL INTEGRATIONS ============= subgraph EXTERNAL["🌐 External Systems"] direction TB SURESCRIPTS["Surescripts
(E-Prescribing)"] HEALTH_GORILLA["Health Gorilla
(Lab Results)"] STRIPE_BILLING["Stripe
(Billing)"] TWILIO_COMM["Twilio
(Communications)"] INSURANCE_API["Insurance APIs"] end TOOLS --> EXTERNAL %% ============= AUDIT & MONITORING ============= subgraph AUD["📊 Audit + Compliance Log"] direction TB CLINICAL_AUDIT["Clinical Actions Log"] PHI_ACCESS_LOG["PHI Access Tracking"] BILLING_AUDIT["Billing Event Log"] COMMUNICATION_LOG["Communication Log"] end subgraph MONITORING["📈 Real-time Monitoring"] direction TB CLINICAL_METRICS["Clinical KPIs"] PERFORMANCE_METRICS["Performance Metrics"] SECURITY_ALERTS["Security Monitoring"] COMPLIANCE_DASH["Compliance Dashboard"] end AUD --> MONITORING MONITORING --> RESP["✅ Secure Response Delivery"] %% ============= SOLUTIONS & OUTCOMES ============= subgraph SOLUTIONS["🎯 Clinical Solutions"] direction TB CHRONIC_CARE["Chronic Care Mgmt"] PREVENTIVE["Preventive Care"] ACUTE_CARE["Acute Care"] POPULATION_HEALTH["Population Health"] CARE_COORDINATION["Care Coordination"] end RESP --> SOLUTIONS SOLUTIONS --> PATIENT_LAYER %% ============= VISUAL STYLING ============= classDef core fill:#dfe8ff,stroke:#4c6ef5,color:#000,stroke-width:2px classDef clinical fill:#e8f5e8,stroke:#4caf50,color:#000,stroke-width:2px classDef data fill:#fff3e0,stroke:#ff9800,color:#000,stroke-width:2px classDef security fill:#fce4ec,stroke:#e91e63,color:#000,stroke-width:2px classDef ai fill:#f3e5f5,stroke:#9c27b0,color:#000,stroke-width:2px classDef external fill:#e0f2f1,stroke:#009688,color:#000,stroke-width:2px class PATIENT_LAYER,SOLUTIONS clinical class DATABASE,CXT,AUD,MONITORING data class IDG,GUARDRAILS security class PRC,ROUTER,M1,M2,LOOP,CDS ai class EXTERNAL,TOOLS external class CHAN,HEALTH_MODULES,RESP core
📋 Block Reference & Swap-Points
| ID | Always-On Role | What You Swap Per Agent |
|---|---|---|
| A | Channel Adapter | Normalise SMS / Email / Chat messages. Choose which adapter(s) are enabled. |
| B | Identity & Scope Guard | Verify user & fetch RLS permissions. Typically static. |
| C | Context Loader | Pull PHI / orders / vector hits. SQL queries & vector index names. |
| D | Prompt Composer | Stitch system prompt + domain rules. Domain-rules YAML, tone, escalation cues. |
| E1 | Model Router | Choose LLM tier by risk/cost. Routing rule set (e.g., if medical ⇒ GPT4). |
| J | Tool Registry | JSON spec of callable functions. Tool whitelist (Billing vs. EHR vs. A/B). |
| K | Reason-Act Loop | Execute tools until goal met. Planner temperature & stop-rules. |
| I | Guardrail Filter | Regex + policy LLM checks. Thresholds, banned patterns, escalation path. |
| M | Observability Hooks | Emit cost, latency, eval scores. Which KPIs to chart for this agent. |
| CHAN | Channel Adapter | Maps Twilio, SendGrid, WebSocket events → unified JSON; strips PII before logging. |
| CXT | Context Loader | Pulls latest EHR, orders, support tickets, plus top-K vector hits; verifies data stays US-region & AES-256. |
| G1 | Guardrail Filter | Policy-LLM checks dosage, PHI leak; bad output triggers loop-back with appended "Why unsafe" note. |
🛠️ Canonical Tool Catalogue
Grant only what's needed
db.read / db.write
Cockroach gRPC CRUD
Cockroach gRPC CRUD
vec.search
Pinecone / Weaviate
Pinecone / Weaviate
billing.retry / billing.discount
Stripe / Recurly
Stripe / Recurly
sms.send / email.send
Twilio, SendGrid
Twilio, SendGrid
appt.book
Scheduler micro-service
Scheduler micro-service
rx.submit / rx.status
Surescripts / pharmacy API
Surescripts / pharmacy API
lab.fetch / dna.fetch
Health Gorilla, Autumn DNA
Health Gorilla, Autumn DNA
ab.run / ab.metrics
GrowthBook SDK
GrowthBook SDK
policy.check
Internal Moderation LLM
Internal Moderation LLM
dosage.validate
Deterministic dosage rule-set
Deterministic dosage rule-set
⚙️ Configure an Agent
- Copying the skeleton.
- Filling domain-rules.yml (persona, tone, compliance text).
- Selecting allowed tools in tool-registry.json.
- Pointing the context loader at the right SQL + vector sources.
- Tweaking guardrail thresholds & KPIs.
- Committing → CI spins up staging → canary via feature flag.
That's the whole map—you can now render, annotate, or extend it in whichever diagramming tool you prefer.