# Healthdex Product Architecture

**Status:** Working product and architecture direction

**Purpose:** Define Healthdex system ownership, runtime boundaries, trust principles, and initial product scope.

## Product direction

Healthdex is an approachable healthcare decision product. It helps decision-makers understand healthcare evidence and move through focused, supported workflows. The product must stand on its own and provide enough evidence, provenance, methodology, and detail for users to understand and evaluate every result within Healthdex.

## Independent-system principle

Healthdex owns its implementation end to end:

- source acquisition and immutable release history;
- databases and schemas;
- canonical identities and relationships;
- transformations and derived models;
- metric definitions and calculations;
- permissions and authentication;
- application services and user workflows; and
- deployment, operations, and release lifecycle.

External reference material or deliberately adapted implementation patterns do not create a runtime dependency. Any future shared service, database access, identity integration, deep link, or deployment coupling requires a new, explicit architecture decision.

## Repository and runtime boundaries

Healthdex documentation is authoritative for Healthdex behavior. Work adapted from an external repository or reference must be restated against Healthdex requirements, licensing, data contracts, and verification gates.

When adapting an external pattern:

- use the source only as reference;
- define the Healthdex requirement independently;
- do not assume schema, service, identity, or interface compatibility;
- reuse only code or assets whose ownership and licensing permit it;
- test the result against Healthdex contracts; and
- avoid runtime imports, shared databases, or deployment coupling unless separately authorized.

## Trust and presentation principles

1. Lead with conclusions, material decision metrics, evidence coverage, known gaps, and appropriate next actions.
2. Preserve sufficient detailed evidence for users to evaluate conclusions.
3. Make evidence coverage and denominator discipline prominent rather than secondary caveats.
4. State missing or unverified evidence directly in the decision narrative.
5. Avoid presenting judgment as objective measurement. Composite scores must be transparently adjustable and explainable or replaced by explicit ranking and filtering criteria.
6. Favor reliable, predefined decision workflows over an open-ended prompt experience the product cannot consistently support.
7. Keep published price, Medicare payment, accounting-cost estimate, and market comparison semantically and visually distinct.

## Initial scope

Contracting and negotiation are the validated initial wedge. Early workflows focus on market positioning, facility comparison, governed rate evidence, evidence coverage, accounting-cost context, and defensible negotiation preparation.

Patient or site-of-care guidance remains a possible future product area rather than an immediate commitment. It introduces different buyers, workflows, and regulatory considerations and requires validated benefits, networks, clinical factors, provider relationships, and member-specific evidence outside the current scope.

## Working positioning

> Healthdex helps decision-makers understand and act on governed healthcare evidence.