MeasureMap

An open-source KPI governance registry for organizations that take their metrics seriously.

Self-hosted. LDAP/AD-native. Audit-ready. Free to deploy, modify, and run on your own infrastructure.

---

The problem

Every operations team — hospitals, finance teams, supply-chain orgs, government agencies — tracks dozens to hundreds of KPIs. The definitions drift. The owners turn over. The "approved" formula in last quarter's board deck doesn't match the SQL query running in production. Spreadsheets sprawl. Audits hurt.

You don't have a data problem. You have a definitions problem.

What MeasureMap does

MeasureMap is the single source of truth for what each metric means, who owns it, and whether it's still valid. It is built for the people responsible for governance — not the dashboards themselves.

• One authoritative record per measure — name, definition, formula, owner, source system, dashboard link.
• Status lifecycle with version history — every change to a measure is snapshotted; you can answer "what did this metric mean on April 3rd?"
• Clinical / regulatory detail — numerator, denominator, exclusions, target value, benchmark source, regulatory program. Optional, structured, searchable.
• Annual review workflow — assign reviewers, track pending/in-review/overdue states, log what changed and why.
• Bulk CSV import — column mapping, per-row validation, preview before commit, full error report on failures.
• Role-based access — Admin / Steward / Viewer, mapped to your Active Directory groups. No separate user database to manage.

Why self-hosted, why open source

Metric definitions are often the sensitive part of a business. Putting them behind someone else's SaaS terms — especially in regulated industries (healthcare, finance, government) — is a non-starter for many organizations.

MeasureMap runs entirely on your own infrastructure. There is no telemetry, no external network calls at runtime, no licensing server. Deploy it on an internal VM, behind your reverse proxy, with your own TLS certificates. It works air-gapped.

If your organization can benefit from this, use it. Fork it. Modify it. Run it without paying anyone. That's the point.

Who it's for

• Healthcare quality teams tracking CMS measures, HCAHPS, Vizient benchmarks, NHSN surveillance
• Finance & ops teams managing KPI definitions across BI dashboards
• Compliance & audit functions needing version history and reviewer attribution
• Any organization where "what does this metric actually measure?" has become a recurring meeting

Screenshots

Add screenshots of dashboard, KPI list, and KPI detail here.

Quick start

Prerequisites

• Node.js 22+ and pnpm 9+
• Docker + Docker Compose (for PostgreSQL; can also point at an existing DB)
• LDAP / Active Directory server for authentication (or use a Samba 4 AD-DC container for local testing — see docs/LDAP_SETUP.md)

Local development

# 1. Clone and install
git clone https://github.com/CCallahan308/MeasureMap.git
cd MeasureMap
pnpm install

# 2. Configure environment
cp .env.example .env
# Edit .env: set NEXTAUTH_SECRET (openssl rand -base64 32), LDAP_* variables

# 3. Start PostgreSQL
docker compose -f docker/docker-compose.yml --env-file docker/.env up postgres -d

# 4. Apply migrations and seed demo data
pnpm db:migrate
pnpm db:seed   # creates 10 demo users, 25 demo KPIs

# 5. Run the dev server
pnpm dev

Open http://localhost:3000 and sign in with a user whose AD account is a member of MeasureMap-Admins, MeasureMap-Stewards, or MeasureMap-Viewers.

Note: Demo users created by the seed exist as data-ownership references only — they cannot log in (authentication is delegated entirely to your LDAP/AD server).

Production deployment

See docs/DEPLOYMENT.md for the full guide. The short version:

cd docker
# Edit docker/.env with production values
docker compose --profile tls up -d

This brings up PostgreSQL 16, the Next.js app, and Caddy reverse proxy with TLS (Caddy is opt-in via the tls Compose profile; without it, the stack is HTTP-only for internal networks). MeasureMap is designed to run on a single VM with restricted outbound internet.

Features

Capability	Status
KPI registry with search, filter, pagination	✅
Bulk CSV import with column mapping and per-row validation	✅
Status lifecycle (Draft → Approved → Deprecated) with version history	✅
Clinical / regulatory measure profiles (numerator, denominator, target, benchmark)	✅
Annual review workflow with reviewer assignment and overdue tracking	✅
LDAP/AD authentication with group-based role mapping (JIT provisioning)	✅
Audit logging for privileged actions	✅
Rate limiting + CSRF protection	✅
White-label branding via env vars	✅
Dark mode	✅
Docker Compose + Caddy reverse proxy with TLS	✅
Single-tenant by default; multi-org schema in place	✅
Offline licensing (designed, not implemented)	⬜
SMTP notifications	⬜

Architecture

apps/web/                Next.js 15 (App Router), React 19, Tailwind, NextAuth v5
  src/app/               Routes (auth + protected layouts, API handlers)
  src/components/        Shared UI primitives
  src/features/          Feature modules (auth, kpis, imports, domains, admin)
  src/lib/               Cross-cutting utilities (prisma, audit log, rate limit, LDAP client)
packages/
  schemas/               Shared Zod schemas — source of truth for validation
  config/                Env validation, branding config
prisma/
  schema.prisma          Database schema
  migrations/            Versioned migrations (additive-only, with .safe-to-drop markers for destructive ops)
  seed.ts                Demo data seed
docker/
  docker-compose.yml     App + PostgreSQL + Caddy
  Dockerfile             Multi-stage production build
  Caddyfile              TLS reverse proxy config
docs/                    Architecture, deployment, LDAP setup, git workflow guides

See docs/ARCHITECTURE.md for the deeper dive and CLAUDE.md for the LLM/contributor cheat sheet.

Tech stack

Layer	Technology
Framework	Next.js 15 (App Router) + React 19
Language	TypeScript (strict mode)
Database	PostgreSQL 16
ORM	Prisma 6
Auth	NextAuth v5 with LDAP/AD Credentials provider
Validation	Zod (shared schemas across UI + API + CSV)
Styling	Tailwind CSS + design tokens
Testing	Vitest
Deployment	Docker Compose + Caddy
CI	GitHub Actions

Security

MeasureMap is built defensively. Notable behaviors:

• LDAP filter values are escaped per RFC 4515 before substitution into search filters.
• Authorization is enforced at the route-handler level, not in middleware — middleware only checks session-cookie existence (Edge runtime limitation).
• All queries are organization-scoped via the session's orgId.
• CSRF protection validates Origin headers against the canonical NEXTAUTH_URL and APP_ALLOWED_ORIGINS.
• Rate limiting on the LDAP login endpoint protects against credential-stuffing.
• Audit logging captures every privileged action with PII-scrubbing of sensitive fields.
• Destructive Prisma migrations are blocked by CI unless explicitly acknowledged with a .safe-to-drop marker.

Found a security issue? Open a private security advisory on GitHub rather than a public issue.

Common commands

Command	Purpose
pnpm dev	Start the dev server
pnpm build	Production build
pnpm test	Run all tests once
pnpm test:watch	Vitest watch mode
pnpm lint	ESLint
pnpm db:migrate	Apply Prisma migrations to the dev DB
pnpm db:seed	Seed demo data
pnpm db:studio	Open Prisma Studio
bash scripts/check-migrations.sh	Run the destructive-SQL check that CI runs

Contributing

Pull requests welcome. A few guidelines that matter:

• Add validation through packages/schemas, not ad-hoc per-route. The same Zod schema validates the form, the API request, and (where relevant) CSV rows.
• Database migrations must be additive by default. Destructive operations (drops, type changes) require a .safe-to-drop marker file with justification. See docs/GIT_WORKFLOW.md §13.
• Tests live next to the code they cover in __tests__/ directories. Cross-cutting tests (org isolation, middleware) live in apps/web/src/lib/__tests__/.
• Don't widen the API surface speculatively — add fields when a feature needs them, not for "future flexibility."

Branch model is feature/* / hotfix/* off main, squash-merge via PR, CI must pass. Full details in docs/GIT_WORKFLOW.md.

License

MeasureMap is released under the Apache License 2.0.

In plain English: you can use, modify, redistribute, and even commercialize MeasureMap, for any purpose, with or without payment. Attribution is required (keep the LICENSE and NOTICE files when you distribute it). There is no warranty.

If you find it useful and want to support continued development, opening an issue with feedback, contributing a fix, or sharing how your organization is using it is genuinely the most valuable thing you can do.

Acknowledgements

Built and maintained by Christian Callahan. If your organization deploys MeasureMap and finds it useful, I'd love to hear about it.

---

Stop tracking KPIs in spreadsheets. Start governing them.

Quick start · Architecture · Deployment · LDAP setup