WorkWell Measure Studio

WorkWell Measure Studio is a Spring Boot + Next.js monorepo for Total Worker Health (TWH) compliance operations. It combines measure authoring, deterministic CQL evaluation, case management, audit trails, admin tooling, and exportable evidence in one operational platform.

At a glance

• Lifecycle-managed measures: Draft -> Approved -> Active -> Deprecated
• CQL compile + fixture validation gates before activation
• Scoped run pipeline: ALL_PROGRAMS, MEASURE, CASE
• Case operations: outreach, assign/escalate, rerun-to-verify, timeline audit
• AI assist for CQL drafting and test fixture generation (never compliance decisions)
• MAT-compatible FHIR R4 export for measure portability
• Risk outlook analytics for upcoming exposure and repeat non-compliance patterns

Status

• Sprint queue through Sprint 7 is implemented in the repo.
• Sprint 7 issues #47-#51 are completed and closed.
• Default branch: main only (stale sprint branches cleaned up).

Production surfaces

• Primary demo frontend: https://twh.os.mieweb.org
• Primary demo backend API: https://twh-api.os.mieweb.org
• Public preview frontend: https://workwell-measure-studio.vercel.app
• Public preview backend API: https://workwell-measure-studio-api.fly.dev

Technology stack

• Backend: Java 21, Spring Boot 3.x, Gradle Kotlin DSL, PostgreSQL 16, Flyway
• Frontend: Next.js 16 App Router, TypeScript, Tailwind, shadcn/ui, Monaco
• CQL/FHIR: HAPI FHIR + org.opencds.cqf.fhir:cqf-fhir-cr 3.26.0
• Infra: MIE Create-a-Container (primary), Neon, GitHub Actions

Repository layout

• backend/ API, CQL evaluation, caseflow, exports, security, MCP
• frontend/ dashboard, Studio, admin, login, UX surfaces
• docs/ architecture, data model, deploy, runbooks, sprint and journal history
• e2e/ Playwright tests

Quick start

Prerequisites

• Java 21
• Node.js 20+
• npm (or pnpm if installed locally)

Backend

cd backend
./gradlew.bat test
./gradlew.bat bootRun

Frontend

cd frontend
npm install
npm run lint
npm run build
npm run dev

Verification commands

# backend
cd backend
./gradlew.bat test

# frontend
cd ../frontend
npm run lint
npm run test
npm run build

Key routes

• /programs compliance overview
• /programs/[measureId] trend, drivers, risk outlook
• /runs run history and detail
• /cases case worklist and filters
• /cases/[id] evidence, actions, timeline
• /measures catalog
• /studio/[id] measure authoring
• /admin integration and scheduler controls

API highlights

• POST /api/measures/{id}/ai/draft-cql
• POST /api/measures/{id}/ai/generate-test-fixtures
• GET /api/programs/{measureId}/risk-outlook?horizonDays=30
• GET /api/measures/{measureId}/versions/{versionId}/export/mat?format=xml
• POST /api/runs/manual
• GET /api/cases?status=open
• GET /api/exports/runs?format=csv
• GET /api/auditor/cases/{caseId}/packet?format=json|html

For full API surface and behavioral notes, see docs linked below.

Documentation map

• Architecture
• Data Model
• Measures
• Deploy Guide
• Exports
• Sprint Index
• Journal
• Changelog

Engineering and governance notes

• AI assist is constrained by docs/AI_GUARDRAILS.md; compliance remains CQL-derived only.
• Public API audit actor is always security-context derived.
• Evidence download/upload operations are role-gated and audited.
• Production startup enforces auth, JWT, and CORS safety checks.

Community and contribution

• Contributing Guide
• Security Policy
• Code of Conduct
• Support

License

Licensed under the Apache License 2.0.