# Healthdex and Analytiv Product Architecture

**Status:** Working product direction  
**Purpose:** Preserve the current thinking about how Healthdex and Analytiv should work together. This document records an architectural and product-positioning decision; it is not yet a functional requirements specification.

## Product direction

Healthdex and Analytiv should present different views of the same governed healthcare data.

- **Healthdex** is the approachable decision layer. It gives decision-makers a concise, high-level view of what the evidence means and helps them move through clear, supported workflows.
- **Analytiv** is the data-dense evidence layer. It gives analysts and expert users the detail needed to inspect, validate, challenge, and reproduce the conclusions presented in Healthdex.

Healthdex is not a redesign or replacement of Analytiv. The products serve different user needs and levels of analytical depth while remaining connected to the same evidence.

## Experience model

The intended progression is:

> Healthdex decision summary → supporting evidence → Analytiv detailed analysis

Healthdex should lead with conclusions, material decision metrics, evidence coverage, known gaps, and appropriate next actions. Analytiv should retain its analytical density, including detailed tables, filters, rate-level evidence, source records, methodology, and data-quality diagnostics.

Every material conclusion in Healthdex should offer a clear **View evidence in Analytiv** action when an equivalent Analytiv view exists. That link should open the relevant Analytiv analysis with the context of the Healthdex page preserved, including:

- market and geography;
- facility, organization, or comparison cohort;
- procedure, code set, payer, and plan context;
- date range and data release;
- filters and analytical assumptions;
- metric definitions and denominators;
- evidence coverage, freshness, and confidence; and
- relevant sources and methodology.

## Shared-data principle

Healthdex must not calculate a separate simplified answer that can drift from Analytiv. Both products should use the same governed datasets, entity identities, metric definitions, calculation services, permissions, and data versions. Healthdex summarizes and explains a governed result; Analytiv exposes that result and its supporting evidence in greater detail.

## Trust and presentation principles

1. Preserve Analytiv's detailed analytics rather than removing density needed by expert users.
2. Make evidence coverage and denominator discipline prominent in Healthdex, not secondary caveats.
3. State missing or unverified evidence directly in the decision narrative.
4. Avoid judgment presented as objective measurement. Composite scores must either be transparently adjustable and explainable or be replaced by explicit ranking and filtering criteria.
5. Keep the underlying evidence one click away wherever practical.
6. Favor reliable, predefined decision workflows over an open-ended prompt experience that the product cannot consistently support.

## Initial product scope

Contracting and negotiation are the validated initial wedge for Healthdex. Early workflows should focus on market positioning, facility comparison, governed rate evidence, quality thresholds, evidence coverage, and negotiation targets.

Patient or site-of-care guidance may demonstrate where the shared engine could go in the future, but it should remain a vision concept rather than an immediate build commitment. It introduces a different buyer, workflow, and regulatory surface and requires validation of benefits, networks, clinical factors, provider relationships, and member-specific details outside the current product scope.

## Cross-repository synchronization

This file in the Healthdex repository is the canonical record of this product direction. Work in either the Healthdex or Analytiv repository that changes shared data semantics, deep-link context, metric definitions, or the boundary between the two products should be checked against this document.

To prevent drift as both repositories evolve:

- reference this document from related planning or implementation work in Analytiv;
- use stable, versioned identifiers for saved analyses and deep-link context;
- maintain shared definitions for metrics, filters, evidence coverage, and data versions;
- record material cross-product decisions here before translating them into product-specific requirements; and
- update affected documentation in both repositories as part of the same change whenever a shared contract changes.

## Working positioning

> Healthdex helps decision-makers understand what the evidence means. Analytiv gives analysts the tools to inspect, validate, and reproduce it.