How I Built OmniHealth Graph with FalkorDB and LangGraph

An Intelligent Clinical Documentation & Revenue Optimization Assistant with FalkorDB

How I designed an AI-assisted clinical documentation and revenue optimization workflow using FalkorDB, LangGraph, and connected clinical knowledge.

---

📖 Demo Video & Walkthrough Watch on Google Drive

---

🚨 The Healthcare Challenge: Documentation, Coding, and Revenue Leakage

A clinical consultation is a conversation. An electronic health record (EHR) requires structured, accurate, and reviewable information.

After a consultation, clinicians may still need to convert the conversation into SOAP notes, visit summaries, discharge summaries, and EHR-ready records. Important details can be missed, documentation may require clarification, and organizing everything manually takes time away from patient care.

But documentation is only half the problem.

Medical coders, compliance auditors, and revenue-cycle teams must also determine whether proposed diagnosis and procedure codes are supported by the documentation, whether applicable bundling rules have been followed, and whether relevant services or supporting details have been overlooked.

Two examples illustrate the challenge:

1. CARC CO-50 — Medical Necessity: A claim may be denied when the documentation does not adequately support the medical necessity of a service.
2. CARC CO-97 — Procedure Bundling: A claim may encounter a bundling-related denial when a service is billed separately despite applicable rules requiring it to be included in another service.

Traditional documentation tools primarily focus on converting conversations into notes. However, a complete workflow needs to connect those notes to clinical context, coding recommendations, compliance checks, patient history, and institutional revenue patterns.

Generative AI can help organize clinical information, but generating a plausible note or code recommendation does not automatically establish its clinical or billing validity.

This is the problem OmniHealth Graph is designed to address: connecting clinical documentation with traceable coding support, longitudinal patient context, and revenue-cycle intelligence in one reviewable workflow.

---

💥 Why Language Models and Flat Retrieval Are Not Enough

Large language models can interpret consultation language, summarize information, and generate structured drafts. Retrieval-Augmented Generation (RAG) can help retrieve relevant information from a knowledge base.

However, semantic similarity alone cannot establish a valid clinical relationship, apply every coding rule, or reliably preserve relationships across patient encounters.

Three challenges are especially important.

1. A Suggested Code Needs Supporting Context

Suppose a consultation transcript contains:

"The patient experiences chest tightness while climbing stairs, which improves with rest."

A model may identify relevant clinical concepts and suggest possible diagnosis or procedure codes. But the reviewer also needs to understand what documented information supports the recommendation and whether additional clarification is required.

A knowledge graph can represent explicit relationships such as:

Documented Symptom → Diagnosis → Proposed Procedure

For example, a graph may contain a modeled relationship connecting chest tightness to a diagnosis and a proposed ECG procedure.

This makes the relationship inspectable. It does not automatically prove medical necessity or replace current coding guidance, payer requirements, or clinical judgment.

2. Coding Requires More Than Recognizing Similar Procedures

Consider a workflow that proposes multiple related procedure codes. The compliance review must determine whether applicable bundling edits affect the combination.

A language model may recognize that two procedures are related, but that is different from checking a defined relationship or validating the current applicable coding rules.

A graph can represent procedure-inclusion relationships and help flag potential conflicts before claim finalization.

3. Patient Context Extends Across Encounters

A patient's recorded medication history or previous diagnosis may be relevant to a later consultation.

For example, a patient with a previously recorded Sildenafil prescription may later be considered for Nitroglycerin. That combination presents a serious contraindication concern and requires appropriate clinical attention.

A workflow that only examines the current transcript may overlook the historical medication.

By modeling encounters, medications, and clinical relationships explicitly, OmniHealth Graph can retrieve relevant history and surface potential safety concerns for review.

The goal is not to replace language models with graphs. It is to combine their strengths: AI for interpreting and organizing information, connected data for exposing relationships, rule-based checks for identifying potential issues, and human review for final decisions.

---

⚡ The Solution: OmniHealth Graph Powered by FalkorDB

We built OmniHealth Graph for the Graph Hacks: Context for AI Agents Powered by FalkorDB hackathon.

OmniHealth Graph is an intelligent clinical documentation and revenue optimization assistant. It brings together consultation processing, structured note generation, coding support, documentation-gap detection, graph-based compliance checks, patient memory, and institutional revenue insights.

FalkorDB serves as the connected context and knowledge layer for the LangGraph workflow. Instead of treating graph data as a passive visualization or separate reporting feature, the system uses graph relationships to inform what the agents retrieve, check, and present to reviewers.

The solution organizes information into three graph families:

• clinical_rules — clinical concepts, diagnosis and procedure relationships, drug classes, and modeled contraindications.
• patient_<id> — patient-specific encounters, conditions, and medication history.
• hospital_brain — departments, physicians, frequently billed CPT codes, and historical denial reasons.

The End-to-End Architecture

flowchart TD
    A["Ambient Clinical Audio / Consultation Transcript"]
    B["1. Voice Ingestion"]
    C["2. PII Sanitizer"]
    D["3. FalkorDB Retrieval Node"]
    E["4. Clinical SOAP Agent"]
    F["5. Medical Coding Agent"]
    G["6. Compliance & Audit Node"]
    H["7. Revenue & Hospital Brain"]
    I["8. Reviewer & Guardrails"]
    J["Clinician Review & Approval"]
    K["Approved Encounter Writeback"]

    R1[("Clinical Rules Graph")]
    R2[("Patient Memory Graph")]
    R3[("Institutional Hospital Brain")]

    A --> B --> C --> D --> E --> F --> G --> H --> I --> J --> K

    R1 <--> D
    R1 <--> F
    R1 <--> G
    R2 <--> D
    R2 <--> I
    R3 <--> H
    K --> R2

    style D fill:#0f172a,stroke:#10b981,stroke-width:2px,color:#fff
    style F fill:#0f172a,stroke:#38bdf8,stroke-width:1px,color:#fff
    style G fill:#0f172a,stroke:#f59e0b,stroke-width:1px,color:#fff
    style H fill:#0f172a,stroke:#a855f7,stroke-width:1px,color:#fff
    style I fill:#0f172a,stroke:#f43f5e,stroke-width:1px,color:#fff
    style J fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#fff

The workflow starts with consultation audio or transcript input, followed by a PII-sanitization stage. The clinical documentation agent prepares structured notes, while the coding and compliance agents examine relevant clinical relationships and potential issues.

Patient history provides longitudinal context, and the institutional graph contributes revenue-cycle insights. The reviewer stage brings these outputs together so that the responsible clinician can inspect the draft, address flagged issues, and approve the encounter.

Approved information can then be written back to the appropriate patient graph using an idempotent persistence workflow.

Here is how FalkorDB supports each of the three hackathon tracks.

---

🔗 Track 01: Agents on Connected Data

In Track 01, the graph actively informs agent behavior. The Medical Coding Agent and Compliance & Audit Node query the clinical_rules graph to inspect modeled relationships rather than relying solely on generated text.

1. Connecting Documentation to Medical-Necessity Context

The clinical agent extracts documented symptoms and relevant encounter details. The coding agent can then query FalkorDB for a path connecting a symptom to a diagnosis and a proposed procedure.

MATCH path =
    (s:Symptom)-[:INDICATES]->(d:Diagnosis)
    -[:SUPPORTS_NECESSITY]->(p:Procedure {code: $code})
WHERE s.name IN $symptoms
RETURN
    [n IN nodes(path) |
        coalesce(n.name, n.code)] AS trace_path,
    d.code AS icd,
    p.code AS cpt
ORDER BY d.code
LIMIT 1

If the graph contains a matching path, the application can render the relationship as an inspectable provenance trail:

Chest tightness
       |
       v
Diagnosis: I20.9
       |
       v
Proposed procedure: CPT 93000

The reviewer can inspect which modeled relationships connect the documented symptoms, diagnosis, and proposed procedure.

If no matching path exists, the workflow can flag the recommendation for review or request additional documentation. A missing path does not necessarily mean the code is invalid; it may also indicate incomplete graph data.

The important distinction is that the graph exposes supporting context instead of presenting a recommendation without an explanation.

2. Detecting Potential Procedure-Bundling Conflicts

Before proposed codes are finalized, the compliance agent can check for procedure-inclusion relationships.

MATCH path =
    (a:Procedure)-[:INCLUDES]->(b:Procedure)
WHERE a.code IN $cpt_codes
  AND b.code IN $cpt_codes
RETURN
    a.code AS comprehensive,
    b.code AS component,
    [n IN nodes(path) | n.code] AS trace_path

When both procedures appear in the proposed code set and the graph models an inclusion relationship, the application can flag the pair for a bundling review.

flowchart TD
    A["Proposed Diagnosis & Procedure Codes"]
    B["Query FalkorDB Procedure Relationships"]
    C{"Potential Bundling Conflict?"}
    D["Flag for Compliance Review"]
    E["Continue Other Validation"]
    F["Validate Applicable Coding Rules"]
    G["Clinician / Coder Review"]
    H["Finalization Decision"]

    A --> B --> C
    C -->|Yes| D --> F
    C -->|No| E --> F
    F --> G --> H

    style D fill:#7f1d1d,stroke:#f87171,color:#fff
    style G fill:#0f172a,stroke:#38bdf8,color:#fff
    style H fill:#064e3b,stroke:#34d399,color:#fff

This is a screening mechanism, not an automatic substitute for the current National Correct Coding Initiative (NCCI) edits or payer-specific policies. The applicable rules must be validated before a billing decision is made.

3. Identifying Documentation Gaps and Revenue Leakage

Revenue leakage can arise when documentation is incomplete, required supporting details are missing, or potentially billable services are not captured for appropriate review.

OmniHealth Graph connects the documentation workflow to coding and compliance checks so that potential issues can be surfaced earlier.

For example, the reviewer interface can present:

• The proposed diagnosis or procedure code.
• The relevant details extracted from the consultation.
• The graph relationships found by the coding agent.
• Missing or unclear information that requires clarification.
• Potential bundling conflicts or other configured validation warnings.

This helps connect documentation quality to downstream coding and revenue-cycle review.

The system can also highlight potential missed services when the configured workflow identifies a discrepancy between documented services and proposed codes. Such findings remain recommendations for review, not authorization to bill unsupported services.

---

🧠 Track 02: Agent Memory & Coordination

Track 02 focuses on patient context that persists across clinical encounters.

A patient's medical history should remain relevant when a new consultation begins. OmniHealth Graph models this information using patient-specific graphs, such as patient_P-9801, while shared clinical rules remain in clinical_rules.

Modeling Longitudinal Patient Context

Consider a synthetic patient, Robert Vance, with a previously recorded prescription for Sildenafil.

The patient graph can represent the following relationships:

(:Patient {id: "P-9801", name: "Robert Vance"})
    -[:HAD_ENCOUNTER]->
(:Encounter {id: "ENC-01"})

(:Encounter {id: "ENC-01"})
    -[:PRESCRIBED]->
(:Medication {name: "Sildenafil 50mg"})

(:Patient {id: "P-9801"})
    -[:HAS_ACTIVE_MED]->
(:Medication {name: "Sildenafil 50mg"})

When the patient returns for a subsequent encounter, the workflow can retrieve the recorded history instead of treating the new consultation as an isolated event.

Cross-Session Medication Safety Checks

Suppose Nitroglycerin is proposed during Robert's later consultation.

The workflow can first retrieve recorded active medications from the patient graph:

MATCH (p:Patient {id: $patient_id})
      -[:HAS_ACTIVE_MED]->(m:Medication)
RETURN m.name AS med_name

The agent can then inspect the shared clinical rules graph for modeled drug-class contraindications:

MATCH path =
    (new:Drug {name: $new_drug})
    -[:IN_CLASS]->(:DrugClass)
    -[r:CONTRAINDICATED_WITH]-(:DrugClass)
    <-[:IN_CLASS]-(active:Drug)
WHERE active.name IN $active_med_names
RETURN
    active.name,
    r.severity,
    r.effect,
    [n IN nodes(path) |
        coalesce(n.name, n.code)] AS trace_path

The application can surface a warning such as:

Potential serious contraindication: The proposed Nitroglycerin conflicts with the recorded active medication Sildenafil. Review the medication history and proposed treatment before proceeding.

This example demonstrates how patient memory and clinical rules work together. The patient graph supplies the relevant history, while the clinical rules graph supplies the modeled contraindication relationship.

sequenceDiagram
    participant C as Clinical Workflow
    participant P as Patient Graph
    participant R as Clinical Rules Graph
    participant G as Reviewer & Guardrails
    participant D as Clinician

    C->>P: Retrieve recorded active medications
    P-->>C: Return relevant patient history
    C->>R: Check proposed medication
    R-->>C: Return modeled contraindication relationships
    C->>G: Provide alert and supporting context
    G->>D: Present alert for review
    D->>G: Review and acknowledge
    G->>D: Continue configured approval workflow

The application should enforce required acknowledgements and approval rules on the backend as well as in the interface. A frontend button alone is not a sufficient safety control.

The graph helps surface a concern; it does not replace clinical assessment or a validated medication-safety process.

Coordinating Agent Memory and Approved Writeback

Once the encounter has been reviewed and approved, the application can persist the approved encounter using idempotent MERGE operations.

MERGE (p:Patient {id: $pid})
SET p.name = coalesce($name, p.name)

MERGE (p)-[:HAD_ENCOUNTER]->(e:Encounter {id: $eid})
SET e.date = $date

MERGE (e)-[:DIAGNOSED]->(c:Condition {name: $condition})

MERGE (m:Medication {name: $medication})
MERGE (e)-[:PRESCRIBED]->(m)
MERGE (p)-[:HAS_ACTIVE_MED]->(m)

This is an illustrative writeback pattern. Production logic must also handle medication discontinuation, changed prescriptions, duplicate relationships, patient access controls, and the difference between a medication prescribed during an encounter and one that remains active.

The workflow is designed around an important principle: review and approve the encounter before persisting its approved state into patient memory.

---

🏢 Track 03: The Institutional Hospital Brain

Track 03 extends the system beyond an individual patient.

Hospitals need to understand recurring relationships between departments, procedures, and historical denial reasons. The hospital_brain graph provides an institutional knowledge layer that the revenue agent can query during a review.

We model relationships involving:

• Departments: Cardiology, Internal Medicine, Emergency.
• Supervising physicians: Relationships between departments and their physicians.
• Frequently billed CPT codes: Procedures associated with departmental billing patterns.
• Historical denial reasons: Categories such as CO-50, CO-97, and CO-16.

Querying Institutional Revenue Patterns

MATCH path =
    (d:Department {name: $department})
    -[b:FREQUENTLY_BILLS]->(c:CPT)
    -[x:DENIED_FOR]->(r:DenialReason)
RETURN
    c.code,
    c.name,
    b.count,
    r.code,
    r.name,
    x.count,
    [n IN nodes(path) |
        coalesce(n.name, n.code)] AS trace_path
ORDER BY x.count DESC

The query connects a department's billing patterns to procedures and historical denial information.

For example, during a Cardiology encounter review, the revenue agent could surface relevant historical denial patterns associated with a proposed procedure. The reviewer could then investigate whether additional documentation or coding checks are appropriate.

flowchart LR
    A["Department"]
    B["Frequently Billed CPT"]
    C["Historical Denial Reason"]
    D["Revenue & Hospital Brain Agent"]
    E["Reviewer Dashboard"]
    F["Prioritize Relevant Review"]

    A --> B --> C --> D --> E --> F

    style D fill:#581c87,stroke:#c084fc,color:#fff
    style F fill:#064e3b,stroke:#34d399,color:#fff

These insights help teams identify patterns worth investigating. They do not guarantee that a specific claim will be denied or that a particular intervention will prevent a denial.

The institutional graph complements the other two graphs: clinical rules support rule-oriented checks, patient memory provides encounter context, and the hospital brain contributes organizational knowledge.

---

🛠️ Key Technical Design Decisions

The main architectural decision is to give the agents access to connected, structured context at the stages where it is useful.

1. Graph Traversals for Inspectable Relationships

FalkorDB lets the application represent relationships explicitly and query paths across connected nodes. These paths can be surfaced to reviewers to explain which modeled relationships informed a recommendation.

The usefulness and performance of each query depend on the graph data, query design, and deployment configuration. Performance claims should be measured against the actual implementation.

2. LangGraph for Coordinated Workflow Execution

LangGraph coordinates the eight workflow nodes, keeping documentation generation, coding support, compliance checks, revenue intelligence, and reviewer guardrails as distinct stages.

This structure makes the workflow easier to reason about than a single prompt that attempts to generate notes, assign codes, check rules, and finalize an encounter in one step.

3. Patient-Specific Graphs for Longitudinal Context

Graphs such as patient_P-9801 separate patient-specific context from shared clinical rules and institutional knowledge.

The application must still enforce authorization, tenant isolation, and access controls. Separate graph names alone do not establish complete privacy or security.

4. Human Review Before Finalization

The workflow keeps the clinician in control of the final decision. Generated notes and coding recommendations remain subject to review, and configured safety or compliance warnings can be surfaced before approval.

The final approval gate should be enforced server-side, with an auditable record of the review and the approved state.

---

🗂️ Graph Data Model in FalkorDB

OmniHealth Graph organizes its knowledge into three graph families.

Track 01 — clinical_rules

Node labels

• (:Symptom {name, aliases})
• (:Diagnosis {code, description})
• (:Procedure {code, description})
• (:Drug {name, aliases})
• (:DrugClass {name})

Relationship types

• [:INDICATES]
• [:SUPPORTS_NECESSITY]
• [:INCLUDES]
• [:IN_CLASS]
• [:CONTRAINDICATED_WITH {severity, effect}]

Track 02 — patient_<id>

Node labels

• (:Patient {id, name})
• (:Encounter {id, date})
• (:Condition {name})
• (:Medication {name})

Relationship types

• [:HAD_ENCOUNTER]
• [:DIAGNOSED]
• [:PRESCRIBED]
• [:HAS_ACTIVE_MED]

Track 03 — hospital_brain

Node labels

• (:Department {name})
• (:Physician {name})
• (:CPT {code, name})
• (:DenialReason {code, name})

Relationship types

• [:SUPERVISED_BY]
• [:FREQUENTLY_BILLS {count}]
• [:DENIED_FOR {count}]

Graph schema reference: View the Graph Schema on Google Drive

---

🔐 Responsible AI, Privacy, and Human Review

Clinical documentation and revenue optimization involve sensitive information and decisions with real-world consequences. Privacy, safety, and governance must be part of the workflow.

• Synthetic and anonymized data: Use synthetic or appropriately anonymized consultation transcripts, clinical notes, EHR samples, coding references, and billing examples in the public demo.
• PII sanitization: The pipeline includes a PII-sanitization stage. This step alone does not establish HIPAA compliance; de-identification must be validated against applicable requirements.
• Data security: Protect sensitive information in transit and at rest, manage secrets outside source control, and restrict access according to role.
• Human oversight: Treat generated clinical notes and code recommendations as drafts or recommendations that require appropriate review.
• Traceability: Make relevant graph paths, checks, warnings, and reviewer decisions inspectable.
• Approval safeguards: Enforce required acknowledgements and authorization on the backend, not only through frontend controls.
• Responsible coding support: Validate coding and bundling checks against current authoritative guidance and applicable payer requirements.
• No unsupported guarantees: Graph relationships can make modeled evidence explicit, but they cannot guarantee perfect coding, zero denials, or clinical correctness.

The goal is to help professionals make better-informed decisions while maintaining clear accountability for clinical and billing outcomes.

---

🎯 Expected Outcomes

OmniHealth Graph aims to connect the clinical documentation workflow with coding support, patient context, compliance checks, and institutional revenue intelligence.

The intended outcomes include:

1. Reduced documentation overhead: Generate structured draft SOAP notes, visit summaries, discharge summaries, and EHR-ready records from consultation input.
2. More traceable coding recommendations: Present graph relationships connecting documented symptoms, diagnoses, and proposed procedures.
3. Earlier identification of documentation gaps: Surface missing or unclear supporting information for review.
4. Earlier compliance review: Flag potential procedure-bundling conflicts before claim finalization.
5. Better longitudinal context: Make relevant recorded encounters and active medications available to the current workflow.
6. More actionable revenue intelligence: Surface institutional relationships between departments, procedures, and historical denial reasons.
7. Clear human accountability: Keep clinician review and approval in the workflow before finalization and approved memory writeback.

These are intended benefits, not guaranteed results. Their impact should be evaluated using measured outcomes from testing and deployment.

---

🩺 Demo Walkthrough: Robert Vance

The demo uses synthetic patient data to illustrate how all three tracks work together.

1. Open the application using a configured demo clinician account.
2. Select the synthetic patient Robert Vance in the Cardiology department.
3. Load a sample consultation describing chest heaviness and tightness during exertion that improves with rest.
4. Run the documentation workflow to generate a draft SOAP note and potential diagnosis and procedure codes.
5. Inspect the graph-supported relationships relevant to the proposed procedure.
6. Review any documentation gaps or potential bundling conflicts surfaced by the compliance stage.
7. Inspect the cross-session medication alert involving historical Sildenafil and proposed Nitroglycerin.
8. Review relevant institutional denial patterns from hospital_brain.
9. Review the generated documentation, address flagged issues, and complete the configured clinician approval workflow.
10. Verify that the approved encounter is written to the appropriate patient graph.

Use only synthetic demo records and credentials configured in the local environment. Never publish working passwords, API keys, or tokens in the repository or blog.

---

💻 Technical Stack

Component	Technology
Graph database	FalkorDB
Agent orchestration	LangGraph
Backend	FastAPI
Frontend	React 18 + Vite
Graph queries	OpenCypher-compatible queries
Documentation workflow	Audio/transcript ingestion, PII sanitization, structured clinical notes
Coding and compliance	ICD-10/CPT recommendations, graph-based checks, documentation-gap review
Patient context	Patient-specific graph memory and cross-session retrieval
Revenue intelligence	Institutional graph queries and historical denial-pattern analysis
Governance	Reviewer guardrails, clinician approval, and approved encounter writeback

---

Closing Thoughts

Clinical AI needs to do more than turn conversations into readable notes. It should help connect documentation to relevant clinical context, make coding recommendations easier to inspect, surface potential issues before finalization, and preserve relevant patient history across encounters.

OmniHealth Graph brings these capabilities together through a coordinated LangGraph workflow powered by FalkorDB.

By combining clinical documentation, graph-grounded coding support, longitudinal patient memory, and institutional revenue intelligence, the system aims to make the workflow more connected, traceable, and reviewable.

The idea behind OmniHealth Graph is simple: generate the documentation, connect the evidence, surface what needs attention, and keep qualified professionals in control.

Healthcare AI should support clinical judgment—not replace it.