A clinical quality measure engine that runs CMS's own published eCQM artifacts — not a reimplementation of them.
WorkWell Measure Studio is an occupational-health compliance platform for Total Worker Health: it authors quality measures, evaluates them against FHIR patient data with a CQL engine, opens and tracks the resulting cases, and exports the evidence auditors ask for. It is built to plug into a real EHR — and does, against a live WebChart tenant.
The interesting engineering problem. A quality measure like "CMS125: Breast Cancer Screening" has an official, published definition. Most systems reimplement it and hope the reimplementation agrees. This one runs the published artifact verbatim — the same ELM CMS ships to MADiE — and keeps a second, independently-authored implementation alongside it as a correctness oracle. Where the two disagree, the disagreement is measured, written down, and turned into a test before anything ships.
- What it does · Architecture · How a measure is evaluated
- Standards · Engineering practices · Quick start
- Repository layout · API · Docs
| Author | Measure lifecycle Draft → Approved → Active → Deprecated, with CQL compilation and fixture validation gating activation. Monaco-based authoring, an ELM explorer, and a no-code rule builder that compiles to CQL (CQL stays canonical — ADR-015). |
| Evaluate | JVM-free CQL→ELM at build time; cql-execution + cql-exec-fhir at runtime. Scoped runs (ALL_PROGRAMS, MEASURE, SITE, EMPLOYEE, CASE), incremental re-evaluation, and measure-major batching. |
| Act | Idempotent case management — outreach, assign/escalate, rerun-to-verify, full timeline. Multi-channel campaigns. Standing-order proposals and immunization forecasting behind ports. |
| Prove | Per-define evidence for every outcome, an append-only audit ledger, auditor packets, CSV exports, FHIR MeasureReport, and QRDA-III. |
| Integrate | FHIR R4 ingest from a live WebChart tenant over SMART Backend Services, a SQL-backed FHIR shim, a read-only MCP server (13 role-gated tools), and a MAT-compatible measure export. |
Guardrail, enforced structurally: AI never decides compliance. It drafts CQL and test fixtures; the CQL engine is the sole authority on outcome status. See docs/AI_GUARDRAILS.md.
flowchart TB
subgraph clients["Clients"]
UI["Next.js 16 App Router<br/>React 19 · Tailwind 4"]
MCP["MCP client<br/>(Claude Desktop)"]
end
subgraph worker["backend-ts — single worker, modular packages"]
API["HTTP API<br/>auth · RBAC · CORS"]
RUN["Run pipeline<br/>scope → evaluate → persist"]
CASE["Case engine<br/>idempotent upsert"]
EXPORT["Exports<br/>MeasureReport · QRDA · CSV"]
MCPS["MCP server<br/>read-only, role-gated"]
end
subgraph engine["Measure engine — no app dependencies"]
ROUTER{{"Executor router<br/>per-measure"}}
AUTH["Authored engine<br/>cql-execution + cql-exec-fhir"]
OFF["Official executor<br/>CMS published ELM<br/>(quarantined package)"]
end
subgraph data["Data sources"]
WC[("WebChart EHR<br/>FHIR R4 / SMART")]
SHIM["WCDB FHIR shim<br/>MariaDB → FHIR"]
SYN["Synthetic roster"]
end
subgraph store["Persistence"]
PG[("PostgreSQL 16<br/>Neon")]
SQLITE[("SQLite<br/>test floor")]
S3[("S3<br/>evidence")]
end
UI --> API
MCP --> MCPS
API --> RUN --> ROUTER
ROUTER -->|default| AUTH
ROUTER -.->|"WORKWELL_OFFICIAL_MEASURES"| OFF
WC & SHIM & SYN --> RUN
RUN --> CASE --> PG
RUN --> EXPORT --> S3
RUN --> PG
PG -.->|"same contract"| SQLITE
classDef dark fill:#1f2937,stroke:#4b5563,color:#f9fafb
classDef accent fill:#065f46,stroke:#10b981,color:#ecfdf5
class ROUTER,OFF accent
class API,RUN,CASE,EXPORT,MCPS,AUTH dark
Three boundaries are enforced by tests, not convention:
src/engine/reaches nothing outside itself — a containment test freezes the dependency allowlist, so the eval core stays portable. Its runtime dependencies are exactlycql-executionandcql-exec-fhir;node:built-ins are confined to*-cli.tsentrypoints, and the CQL→ELM translator now lives in the app, so@cqframework/cqlis refused anywhere in the tree rather than carved out.fqm-executionlives in exactly one package —packages/official-executor/, reached only through a lazyawait import, policed by five boundary tests. The heavyweight official-execution dependency can never leak into the request path.- Storage is a port with two adapters — a Postgres ceiling and a SQLite floor that satisfy the same contract test, so the whole suite runs with no database.
sequenceDiagram
autonumber
participant OP as Operator
participant API as Run API
participant SRC as Data source
participant ENG as Executor router
participant DB as Store
OP->>API: POST /api/runs/manual (scope)
API->>DB: create run + audit event
API-->>OP: 202 RUNNING
API->>SRC: fetch FHIR bundles for scope
SRC-->>API: Patient + Observation + Procedure …
Note over ENG: per measure, the router picks an engine
API->>ENG: evaluate(measure, bundles)
alt measure is officially routed
ENG->>ENG: prepare bundles for QI-Core
ENG->>ENG: run CMS's published ELM (batched)
else default
ENG->>ENG: run authored CQL
end
ENG-->>API: outcome + per-define evidence
API->>DB: persist outcome + evidence_json
API->>DB: idempotent case upsert
API->>DB: audit event per state change
API->>DB: finalize run (COMPLETED / PARTIAL_FAILURE)
Every state change writes an audit_event — no exceptions. Case upsert is keyed (employee, measure_version, evaluation_period), so a nightly re-run updates rather than duplicates, and never clobbers an operator's in-progress work.
This project is deliberately careful about what it claims. docs/STANDARDS_CONFORMANCE.md states, per surface, what is executed and verified versus what is structurally aligned.
| Surface | Standard | Level |
|---|---|---|
| Measure logic | HL7 CQL / ELM | Executed — JVM-free, build-time translation |
| Patient data | FHIR R4, US Core / QI-Core | Executed — official artifacts evaluate real QI-Core bundles |
| Known-answer gate | Official MADiE test cases (5 measures) | 231/231 exact — a permanent CI gate |
| Terminology | VSAC value sets | The artifact's own expansions, fetched at build and pinned by SHA-256 |
| Reporting | FHIR MeasureReport, QRDA-I, QRDA-III | MeasureReport executed; both QRDA documents structurally representative, neither CVU+-validated |
| EHR integration | SMART Backend Services (private_key_jwt) |
Executed against a live tenant |
No measure may be routed to its official artifact without a green MADiE gate. That is a construction-time refusal, not a review convention.
The parts of this repo worth reading if you care about how it is built:
- 43 Architecture Decision Records (
docs/DECISIONS.md) — every non-obvious decision, with the alternatives and the consequences. Several record a decision being reversed by measurement or review, with the original reasoning kept rather than deleted. - Measure-first, then decide. Repeatedly, a planned refusal or guard was killed because measuring showed it would fire on correct inputs. Those reversals are documented as such — the reasoning that was wrong is the useful part.
- Guards are mutation-tested. A check that cannot fail is worse than no check, because it reads as covered. New safety conditions are verified by breaking them and confirming exactly the intended test fails.
- Vacuous-guard hunting. Tests that self-skip when a fixture is missing are treated as a defect class in their own right — a suite that reads green because it never ran is worse than a red one. The sidecar-dependent gates are named explicitly in a CI step so they cannot silently drop out, and the flip checklist tells the operator to read the
skippedcount, not justfail. - Ports and adapters throughout — measure executor, data source, value-set resolver, outreach channel, immunization forecaster, evidence bucket, store layer. Each defaults to an inert simulated implementation and is inert unless configured.
- Reversibility as a design constraint. Every seam is switchable by env var, and every switch is byte-identical to the previous behaviour when unset.
- 1604 backend tests on the SQLite floor with no external services (1590 pass, 14 self-skip without a local Postgres or the gitignored terminology sidecar); a Postgres contract suite that runs against a local
postgres:16when present; and Playwright E2E.
Prerequisites — Node.js 22.16+ (24 recommended; pnpm install enforces it), pnpm via Corepack, and Git submodules — @mieweb/cloud is vendored as one.
git clone https://github.com/Taleef7/workwell.git && cd workwell
git submodule update --init --recursive # @mieweb/cloud — the backend will not install without it
# Backend — API, engine, exports (http://localhost:8080)
cd backend-ts
pnpm install
pnpm typecheck && pnpm test
pnpm dev
# Frontend — dashboard, Studio, admin (http://localhost:3000)
cd ../frontend
pnpm install
pnpm devNo database or cloud account is needed: the SQLite floor and the synthetic roster make the whole app runnable offline.
cd backend-ts
pnpm evaluate --patient ./bundle.json --measure audiogram# both engines, same bundles, per-subject diff + before/after distribution
pnpm flip-snapshot --measure cms125 --source syntheticbackend-ts/ API worker, CQL engine, run pipeline, cases, exports, MCP, stores
src/engine/ measure evaluation — no app dependencies (boundary-tested)
src/wiring/ executor router, official artifacts, terminology
packages/ official-executor — the sole home of fqm-execution
measures/ authored CQL + vendored official artifacts
frontend/ Next.js 16 dashboard, Studio, admin
wcdb-fhir-shim/ standalone MariaDB → FHIR R4 shim (owns the DB driver)
docs/ architecture, data model, ADRs, deploy, conformance, journal
e2e/ Playwright end-to-end tests
/compliance roster grid · /programs overview · /programs/[id] trend + risk outlook · /programs/hierarchy enterprise→location→provider→patient drill-down · /runs history · /cases worklist · /campaigns bulk outreach · /measures catalog · /studio/[id] authoring · /people cross-system identity · /admin integration + scheduler
POST /api/runs/manual # scoped evaluation run
GET /api/runs/{id}/measure-report?type=summary # FHIR MeasureReport
GET /api/runs/{id}/qrda?format=xml # QRDA-III
GET /api/measures/{id}/fidelity # authored vs official spec diff
GET /api/measures/{id}/fidelity/diff # executed outcome diff
GET /api/auditor/cases/{id}/packet?format=json|html # auditor evidence packet
GET /api/cases?status=open # case worklist
GET /api/exports/outcomes?format=csv # evidence export
GET /api/identity/duplicates # cross-system identityFull surface in docs/ARCHITECTURE.md.
Running CMS's official published artifacts in place of the authored implementations, one measure at a time, behind WORKWELL_OFFICIAL_MEASURES. CMS122 and CMS125 are live on the demo/production stack (2026-07-30) — both evaluate CMS's published QI-Core artifacts verbatim. Every other measure, and every other environment, still evaluates the authored CQL. CMS122 shipped a PR later than CMS125: its official numerator counts poor glycemic control, so the MeasureReport canonical, improvementNotation and population membership all had to switch together first, and a self-contradictory report is worse than a delayed one.
What remains before the first flip, and the verification bar it has to clear, is tracked in docs/JOURNAL.md (newest first) and the ADR run 036–044 in docs/DECISIONS.md. Cypress CVU+ is the verification bar and has not yet run.
| Architecture | system boundaries, module map |
| Decisions | 43 ADRs, newest first |
| Data Model | tables, idempotency + evidence contracts |
| Measures | the TWH measure catalog in plain English |
| Standards Conformance | what we may and may not claim |
| WebChart Mapping | EHR → FHIR crosswalk |
| AI Guardrails | prompts, fallbacks, the hard rule |
| Deploy | environments, secrets, rollback |
| Production Readiness | PHI/HIPAA posture, gap list |
| Journal | the running engineering narrative |
Contributing Guide · Security Policy · Code of Conduct · Support
Built as an engineering collaboration with MIE around WebChart and Enterprise Health. Not an ONC-certified product; see Standards Conformance for exactly what is and is not claimed.