MetricGraph is a business-facing KPI discovery, reconciliation, governance, experimentation, and impact-intelligence application for Microsoft Fabric and Power BI estates. It treats measures as technical evidence—not automatic KPI truth—and keeps the relational registry authoritative while projecting a rebuildable graph for explanation and impact traversal.
The initial product runs end to end with a deterministic synthetic estate and includes a configuration-ready, metadata-only Microsoft Fabric connector. Live tenant validation is pending authorized credentials; no live Fabric test is claimed by this repository.
The enterprise increment is now in implementation. Its delivered foundation models the four trust planes, fixes interactive Power BI queries to a delegated-user identity policy, provides an MSAL-backed OBO broker boundary, exposes scope-bound capability diagnostics, and persists identity/capability contracts. It now also includes a disabled-by-default AI-provider harness and a query-scoped DAX preview flow: users may describe a variant when an approved provider is configured or paste mature DAX without any provider. Live semantic-model execution, INFO.VIEW probes, SemPy execution, generated artifacts, and report publication remain incomplete and are reported as unavailable rather than simulated as live. Read the canonical white paper, execution plan, and trust-plane ADR.
Prerequisites: Node.js 22 or newer and npm 11 or newer. PostgreSQL 17 is needed only for the persistent worker profile; the complete demo uses an in-memory registry.
npm install
npm run dev:demoOpen the hosted MetricGraph demo. This GitHub Pages build uses a representative synthetic metadata sample; its interactions stay in the browser session and never access a tenant or perform production writes.
For local full-stack development, open http://127.0.0.1:4311. The API runs on port 4310; OpenAPI UI is at http://127.0.0.1:4310/documentation.
For PostgreSQL-backed jobs:
docker compose -f deploy/local/docker-compose.yml up -d
# Set DATABASE_URL from an ignored local environment file or secret injection.
npm run db:migrate
METRICGRAPH_DEMO_MODE=false npm run devDemo mode intentionally uses the in-memory registry. With demo mode disabled and DATABASE_URL set, the API and worker share the PostgreSQL registry; the worker leases resumable 100-workspace batches and idempotently persists snapshots, workspace/model/report/measure/dimension inventory, dependency evidence, optional report visual-field usage, classifications, review cases, coverage, and the rebuildable graph projection. Docker was not available in the implementation environment, so the Compose runtime itself remains operator-verification pending. The same SQL migrations, upgrade path, worker writes, and runtime reads are exercised with PGlite in automated integration tests. See Enterprise validation remediation for the post-deployment corrections and verification boundary.
- Stable workspace-name resolution with duplicate disambiguation, access/capability preflight, audited stable-ID scope creation, and asynchronous scan progress.
- Synthetic and real replaceable Fabric providers for workspace directory, Admin Scanner inventory, report/semantic definitions, PBIR visual usage, endorsements, lineage, and capability state.
- Entra client-credential and managed-identity token providers, throttling, pagination,
Retry-After, LRO polling, secret-safe logging, and explicit coverage gaps. - Plane-specific identity-policy contracts, a fixed-scope delegated Power BI OBO broker, user/tenant/scope-partitioned in-memory MSAL caches, saved-scope capability probes, and explicit scanner/query/AI/publisher identity diagnostics.
- A server-only AI-provider framework with Microsoft Foundry/Entra and allowlisted OpenAI-compatible profiles, versioned bounded context and instructions, a minimal skill/tool allowlist, prompt-injection checks, structured-output validation, and a provider-free pasted-DAX path.
- A KPI Management workspace that groups the Work Queue, KPI Catalog, Draft & Simulate, and Sandbox. Draft & Simulate requires semantic-model confirmation, validates model references and forbidden operations, and returns only ephemeral synthetic demo previews with explicit evidence warnings and no production write.
- The complete relational registry schema and repository, temporal KPI contracts/variants, immutable approvals, sandbox trust boundaries, classifications, reconciliation cases, audit history, and database-backed resumable job leases.
- Deterministic classification and reconciliation with human-readable evidence; no opaque model makes governance decisions.
- Bounded graph queries, reachability, blast radius, shortest explanation path, connected components, topological ordering, and cycle detection.
- A responsive Fluent UI business application with dark/light themes and three task-oriented workspaces: Overview with governance health, KPI Management with catalog/drafting/sandbox workflows, and Graph Explorer with focused 3D exploration plus a 2D measures inventory/matrix. Fabric and optional AI infrastructure are configured together under Connections.
- Keyboard node finding, visible focus, reduced motion, orbit/drag interaction, click-to-focus, and an axe-checked WCAG 2.2 AA primary shell.
Studio (React + Fluent UI) -> Fastify API -> relational registry
-> Fabric capability providers
Worker -> PostgreSQL leased scan jobs -> graph projection
| Area | Location |
|---|---|
| Business web app | apps/studio |
| API and local workflow state | apps/api |
| Database-backed worker | apps/worker |
| Canonical contracts and schemas | packages/contracts |
| Governance and temporal rules | packages/domain |
| Fabric providers | packages/fabric-connector |
| Classification/reconciliation | packages/classification, packages/reconciliation |
| Graph algorithms | packages/graph |
| Deterministic estate | packages/test-fixtures |
| PostgreSQL migrations | db/migrations |
The canonical product and design decisions remain under docs/product-design, docs/ui-ux, docs/integrations, and docs/architecture.
Copy .env.example to .env and fill values through an approved secret mechanism. Never commit the populated file.
METRICGRAPH_FABRIC_PROVIDER=syntheticis the local default.- Set
METRICGRAPH_FABRIC_PROVIDER=fabricplus either Entra client credentials or managed identity variables to activate Microsoft providers. METRICGRAPH_AUTH_MODE=developmentgrants the explicit local actor every role. Use enterprise mode only with configured Entra issuer/audience values.METRICGRAPH_ENTRA_API_CLIENT_IDis the audience for incoming MetricGraph API tokens.METRICGRAPH_QUERY_OBO_CLIENT_IDandMETRICGRAPH_QUERY_OBO_CLIENT_SECRETconfigure the confidential middle tier for downstream delegated Power BI tokens; inject the secret through an approved server-side secret mechanism.- Optional definition providers remain feature-flagged because current Fabric definition APIs require item read/write permission and can be blocked by sensitivity labels.
- AI generation is off by default. Configure it only on the API server; never put a model key in Studio, GitHub Pages, source control, or browser storage. Manual pasted DAX remains available while AI is disabled.
See AI Agent provider setup, Fabric administrator prerequisites, and workspace onboarding.
npm run check
npm run test:e2e
npm run db:verify
npm run verify:secrets
npm audit --audit-level=high
mkdir -p artifacts && npm run sbomThe deterministic domain packages enforce at least 80% statement, branch, function, and line coverage. Browser tests cover catalog, onboarding/scan completion, reconciliation, sandbox promotion, the 3D force-directed graph, orbit interaction, keyboard node finding, axe accessibility, reduced motion, and mobile layout.
Primary visual evidence:
- GitHub Pages demo build
- Draft & Simulate pasted-DAX preview
- Overview
- 3D force-directed Graph Explorer
- Completed workspace scan
- Mobile overview
The implemented runtime stores metadata and governance evidence, never business fact rows. Its connector is read-only toward production Fabric/Power BI content. DAX is drafted or accepted only for validation and an explicitly synthetic local preview; there is no live DAX execution, report/semantic-model modification, certification, endorsement, deletion, or deployment write-back. Human action is required for model confirmation, review decisions, approvals, variant precedence, sandbox promotion, and publication.
The identity foundation preserves that baseline by separating metadata scanning, delegated-user DAX, AI inference, ephemeral result values, and optional publication into independent trust planes and identities. The AI adapter is disabled until a server-side provider passes its configuration gates and is never presented as live-validated from configuration alone. Live query, result, artifact, and publication adapters remain disabled until their own implementation and validation gates pass.
Read SECURITY.md and the threat model before enterprise deployment.