Start typing to search this publication.
techcirkle
Open menu

Subscribe to techcirkle

Get new posts delivered straight to your inbox.

Stop Hard-Coding Telehealth Policy: Designing a Versioned Rules Engine

How to move licensure, modality, prescribing and consent logic out of app code and into a versioned, testable telehealth policy engine, with examples.

techcirkle
5 min read
Cover image for Stop Hard-Coding Telehealth Policy: Designing a Versioned Rules Engine

Search a typical telehealth codebase for the word waiver and you may find it in a booking handler, a billing job, a React component and a comment that says TODO remove after PHE. That is what happens when regulation gets treated as a requirement you implement once. Telehealth rules behave more like configuration with a shelf life, and they deserve an architecture that reflects it.

Doctor in his later career using a laptop at his desk to consult with a patient by video
Doctor in his later career using a laptop at his desk to consult with a patient by video

Two current examples show why. The fourth temporary DEA and HHS extension for telemedicine prescribing of controlled substances runs through December 31, 2026. Medicare's geographic and originating-site waivers run through December 31, 2027, following the Consolidated Appropriations Act, 2026. Either date could be revised. If you handle them with branching in application code, every change means a cross-cutting refactor under time pressure.

The policies below are invented examples showing the shape of the system. They are not statements of what any state or payer requires. Real rule content should come from healthcare counsel, and you should confirm the current status of these dates yourself.

What belongs in the engine

A useful test: if the answer could change because of a regulator, a payer contract or your compliance team, and no feature has changed, it is policy. Four domains usually qualify:

Domain

Question answered

Typical inputs

Output

Licensure

Can this clinician see this patient now?

Patient location, clinician licenses, date

allow or deny, reason

Modality

Which visit types are allowed?

Service, payer, location, date

video, audio, async

Prescribing

Which conditions apply to this order?

Substance class, prior in-person visit, date

allow, block, require step

Consent

What must the patient see and accept?

Location, recording, AI use

template IDs

Things that do not belong: clinical judgment, UI layout, and anything that needs an arbitrary program to decide. Keep the engine boring. A clinician still decides what is clinically appropriate. The engine only answers whether a pathway is permitted and what must happen first.

Rules as data

Every rule needs an identity, an effective window, a provenance trail and a review status. An illustrative rule:

{
  "id": "rx.controlled.remote-initiation",
  "version": 7,
  "domain": "prescribing",
  "status": "approved",
  "effective": { "from": "2026-01-01", "until": "2026-12-31" },
  "when": {
    "all": [
      { "fact": "order.substanceClass", "op": "in", "value": ["controlled"] },
      { "fact": "patient.priorInPersonVisit", "op": "eq", "value": false }
    ]
  },
  "then": { "effect": "allow", "requires": ["epcs_signing", "state_check"] },
  "onExpiry": "rx.controlled.remote-initiation.fallback",
  "provenance": {
    "basis": "Placeholder: citation supplied by counsel",
    "reviewedBy": "compliance-lead",
    "reviewedAt": "2026-10-12"
  }
}

Look at onExpiry. It is the most valuable field in the file, because it forces someone to write the "what if this lapses" rule while there is still time, and to get it approved. The fallback sits in the store as a draft or approved rule with its own effective window, so nothing silently falls through on January 1.

Default to denial when no rule matches and route the case to a human queue. In this domain, an unknown should never become an automatic yes.

Evaluation you can explain

The evaluator can be surprisingly small. The important decision is that it takes an explicit evaluation time and returns its reasoning.

type Decision = {
  effect: "allow" | "deny" | "review";
  requires: string[];
  matched: { id: string; version: number }[];
  snapshot: string; // ID of the published rule set
};

function evaluate(facts: Facts, at: Date, set: RuleSet): Decision {
  const active = set.rules.filter(
    (r) => r.status === "approved" && inWindow(r.effective, at)
  );
  const hits = active.filter((r) => matches(r.when, facts));

  if (hits.length === 0) {
    return { effect: "review", requires: [], matched: [], snapshot: set.id };
  }
  // Conservative resolution: any deny wins over any allow.
  const effect = hits.some((r) => r.then.effect === "deny") ? "deny" : "allow";
  return {
    effect,
    requires: hits.flatMap((r) => r.then.requires ?? []),
    matched: hits.map((r) => ({ id: r.id, version: r.version })),
    snapshot: set.id,
  };
}

Passing at rather than reading the clock inside lets you simulate next January today. You can answer "what breaks if this date passes?" by replaying real, de-identified encounter shapes against a future timestamp and comparing decisions.

Store the returned Decision with the encounter. Months later, when someone asks why a visit was permitted, you can point to rule version 7 from a specific snapshot instead of guessing what the code did at the time.

Stethoscope resting near a phone and an open notepad on a blue surface
Stethoscope resting near a phone and an open notepad on a blue surface

The publishing workflow

Treat a rule change like a code change, with a compliance reviewer in the path:

  1. Propose. A compliance lead or engineer edits a rule in a pull request or an admin UI backed by the same store.

  2. Test. A fixtures suite runs every scenario and prints a decision diff.

  3. Approve. Someone outside the author's role signs off, and the approval is recorded.

  4. Publish. The system creates an immutable rule set snapshot.

  5. Monitor. Deny and review rates are tracked per rule, with an alert on sudden movement.

A golden test file doubles as readable documentation:

- name: patient in unlicensed state is denied
  at: 2026-11-20
  facts: { patient.location: XX, clinician.licenses: [YY] }
  expect: deny

- name: remote initiation falls back after expiry
  at: 2027-01-02
  facts: { order.substanceClass: controlled, patient.priorInPersonVisit: false }
  expect: review

Gotchas worth planning for

  • Facts must be fresh. Patient location should be confirmed for each encounter, since clinicians generally need licensure where the patient is physically located during the visit. A home address on the profile is not good enough.

  • Consent versions. Record which template version a patient accepted, not just a boolean.

Why this pays off beyond compliance

Once policy is explicit, other things improve. New states become mostly a data exercise rather than a release. And when an AI agent eventually starts handling bookings or follow-ups, it can call the same engine, so automation inherits the same guardrails. TechCirkle's page on agentic workflow development goes further into permissions and approvals for that kind of automation.

For how a rules layer fits within the wider decision about scope, integration, AI and budget, read the full guide to telehealth app development services.

Frequently Asked Questions

Do I need a commercial rules engine for telehealth policy?

Often not at first. A versioned data store, a small evaluator and strong tests can handle a modest rule set well. Consider a dedicated product once rule volume, authoring needs or audit requirements clearly outgrow that setup.

Who should own policy rules, engineering or compliance?

Share it deliberately. Compliance and counsel own the meaning of a rule, engineering owns the engine and tests, and every publication should carry a recorded approval from someone other than its author.

Should an engine decision block a clinician automatically?

Use hard denials sparingly for clear legal limits and send uncertain cases to a human review queue. The engine confirms whether a pathway is permitted, while clinical judgment stays with the clinician.

How do I test a rule that takes effect in the future?

Make evaluation time an explicit input, then run scenarios at future timestamps in CI. Replaying de-identified encounter shapes against a future date also reveals which active workflows would change.

How should rule versions connect to the audit trail?

Save the decision, matched rule IDs, versions and snapshot ID with each encounter. That lets you reconstruct what the system permitted at the time, even after the rules change.

Subscribe to techcirkle