Core Concepts of The Tuva Project

The Big Picture

Tuva's 7 building blocks form a pipeline. Each one transforms data a little further until you have analytics-ready datasets. Here's how they connect:

Connectors — Mapping Raw Data In

Connectors are dbt projects that transform raw source data into Tuva's Input Layer. Think of them as adapters — they know how to read your specific data format and translate it into the format Tuva expects.

Tuva provides pre-built connectors for common healthcare data sources. If your data comes from a proprietary system, you write a custom connector. The connector handles field mapping, type casting, and basic transformations.

Input Layer — The Standard Format

The Input Layer is the standardized format Tuva expects. Once your data is in Input Layer format, you can run the entire Tuva package. Key tables include:

• medical_claim — Professional and facility claims
• pharmacy_claim — Prescription drug claims
• eligibility — Member enrollment and coverage periods
• lab_result — Lab test results
• condition — Diagnosis records
• procedure — Procedure records

Each table has a defined schema with required and optional columns. The Input Layer documentation specifies every field, its data type, and whether it's required.

Data Quality — Validating Your Data

Tuva includes 100+ automated data quality checks that validate your data before it enters the pipeline. These checks catch problems early, before they propagate through every downstream model.

The checks fall into three categories:

• Completeness — Are required fields populated? Does every claim have a patient ID, dates of service, and diagnosis codes?
• Validity — Are codes valid? Is that ICD-10 code a real code? Are dates reasonable?
• Consistency — Do dates make sense? Is the discharge date after the admission date? Does the claim amount match the sum of its line items?

The output is a data quality report that shows exactly what's wrong with your data, how many records are affected, and what needs to be fixed.

Normalization — Standardizing Codes

Normalization maps source codes to standard terminologies. Your source data might use proprietary codes, abbreviations, or non-standard formats. Normalization translates everything into a common language.

Examples of what normalization handles:

• Custom drug codes → NDC (National Drug Code)
• Facility type abbreviations → Standard CMS facility type codes
• Discharge status values → Standard discharge status codes
• Bill type codes → Standard UB-04 bill type codes

After normalization, every record in your data speaks the same language regardless of where it came from.

Claims Preprocessing — From Lines to Encounters

Raw claims data comes as individual claim lines — each line representing a single charge. Claims Preprocessing groups these lines into clinically meaningful encounters and episodes.

This is where raw claim data becomes useful for analytics:

• Grouping — Multiple claim lines for the same hospital stay are combined into a single encounter
• Service categories — Each encounter is classified as inpatient, outpatient, emergency department, skilled nursing, etc.
• Claim type assignment — Professional vs. facility claims are identified and handled appropriately

Without this step, you'd be counting individual charge lines instead of actual patient visits.

Core Data Model — The Unified Schema

The Core Data Model is a unified, patient-centric schema that brings together all the processed data. Key tables include:

• patient — One row per patient with demographics and enrollment info
• condition — All diagnoses mapped to standard terminologies
• encounter — Every patient visit with dates, providers, and settings
• lab_result — Lab test results with standard LOINC codes
• medication — Prescriptions and drug claims with NDC codes
• procedure — All procedures with CPT/HCPCS codes
• observation — Clinical observations and vitals

Every downstream data mart reads from the Core Data Model, not from raw data. This means you only need to get the data right once.

Terminology & Value Sets

Tuva ships with a comprehensive library of healthcare terminologies and value sets:

• ICD-10-CM — Diagnosis codes (70,000+)
• CPT — Procedure codes
• SNOMED CT — Clinical terminology
• HCPCS — Healthcare procedure codes (Level II)
• NDC — National Drug Codes
• CMS value sets — HCC mappings, CCSR categories, readmission flags

These are stored as versioned seed files and auto-loaded from S3, GCS, or Azure when you run dbt seed. Tuva also includes its own concept library for mapping conditions, which makes it easy to build condition-based cohorts (e.g., "all patients with diabetes").

How It All Fits Together

Here's the simplified end-to-end flow showing how your data moves through the Tuva pipeline:

Getting Started

Once your data is in Input Layer format, running Tuva is straightforward:

1. dbt deps — Install the Tuva package and its dependencies
2. dbt seed — Load terminology files (ICD-10, CPT, value sets) into your warehouse
3. dbt build — Run the entire pipeline: data quality, normalization, core model, and data marts

That's it. Three commands to go from raw data to analytics-ready datasets.

Tuva uses dbt variables to control what runs:

• claims_enabled — Set to true if you have claims data
• clinical_enabled — Set to true if you have clinical/EHR data
• tuva_marts_enabled — Control which specific data marts to build