# tuva-health/tuva architecture

> Architecture diagram of the GitHub repository tuva-health/tuva, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tuva-health/tuva
- Repository: https://github.com/tuva-health/tuva

## Overview

##### Main Components
a. Data Sources
- Raw clinical and claims data in your warehouse (e.g., core tables loaded externally or via dbt `input_layer` models)
- Terminology and reference data (seeds/ S3)
b. dbt Project Layers
1) input_layer  – initial “inbound” SQL models
2) staging      – cleanses & standardizes inbound tables
3) normalized_input – normalization & code‐voting logic
4) intermediate – domain‐specific transforms (claims_preprocessing, service_category, etc.)
5) final/core  – core data model for patient, encounter, claim, etc.
6) data_marts  – specialized marts (quality_measures, cms_hcc, pqi, ed_classification, readmissions, etc.)
c. Supporting Components
- Macros library – reusable SQL functions called by models
- Seeds (seeds/terminology, seeds/value_sets) – reference & vocabulary tables loaded first
- Snapshots – temporal snapshots of key tables (cms_hcc risk, quality_measures)
- Data Quality Models & Tests – DQI models/test suites under models/data_quality & macros/tests
- Documentation – auto‐generated dbt docs site (docs/manifest.json, etc.)
- CI/CD – GitHub Actions workflows under .github/workflows, custom lint scripts, integration & CI tests
- Helper scripts – Python scripts for schema extraction & S3 loading

##### Relationships & Data Flow
- Snapshots to the final/core models they reference
- Data quality models consume core and marts; tests and DQI macros apply against staging & final tables
- CI/CD orchestrates:
– On commit, GitHub Actions → run dbt build/test → update docs → deploy artifacts

##### Architectural Patterns & Principles
- Layered ELT pipeline (modular, each folder is a logical layer)
- Reusability via macros (DRY SQL)
- Packaging & versioning (dbt package.yml, semantic versioning)
- Environment‐agnostic configuration (profiles for BigQuery, Snowflake, Redshift, Fabric)
- CI/CD gating quality (unit tests in macros/tests, integration_tests, ci_testing pipelines)

##### Call Out Key Technologies & Integrations
- dbt (SQL‐based transformations)
- Warehouse platforms (BigQuery, Redshift, Snowflake, Databricks, DuckDB)
- AWS S3 (for large terminology files)
- GitHub Actions (CI/CD)
- Python (helper_scripts/schema_extract.py)
- dbt docs site (static HTML in docs/)

##### Detail Level
- Major folder as a component (don’t list every SQL file)
- How seeds (terminology, value_sets) feed into staging

## Diagram (Mermaid)

```mermaid
flowchart TB
    DataSources["Raw Clinical & Claims Data"]:::storage
    Seeds["Seeds (terminology & value_sets)"]:::storage

    InputLayer["Input Layer\n(models/input_layer)"]:::model-layer
    Staging["Staging Layer"]:::model-layer
    Normalized["Normalized Input Layer"]:::model-layer
    Intermediate["Intermediate Layer"]:::model-layer
    Final["Final/Core Layer"]:::model-layer
    DataMarts["Data Marts"]:::model-layer

    Macros["Macros Library"]:::service
    Snapshots["Snapshots"]:::storage
    DQ["Data Quality Models & Tests"]:::service
    Docs["Documentation Site"]:::service
    CI["CI/CD Orchestration"]:::service
    Helper["Helper Scripts"]:::service

    %% Data flow
    DataSources --> InputLayer
    Seeds --> Staging
    InputLayer --> Staging
    Staging --> Normalized
    Normalized --> Intermediate
    Intermediate --> Final
    Final --> DataMarts

    %% Macro usage
    InputLayer --> Macros
    Staging --> Macros
    Normalized --> Macros
    Intermediate --> Macros
    Final --> Macros
    DataMarts --> Macros

    %% Snapshots & quality
    Snapshots --> Final
    Final --> DQ
    DataMarts --> DQ

    %% CI/CD and docs
    CI --> InputLayer
    CI --> Docs

    %% Helper scripts
    Helper --> DataSources
    Helper --> Seeds

    %% Click events
    click Seeds "https://github.com/tuva-health/tuva/tree/main/seeds/"
    click InputLayer "https://github.com/tuva-health/tuva/tree/main/models/input_layer/"
    click Staging "https://github.com/tuva-health/tuva/tree/main/models/core/staging/"
    click Normalized "https://github.com/tuva-health/tuva/tree/main/models/claims_preprocessing/normalized_input/"
    click Intermediate "https://github.com/tuva-health/tuva/tree/main/models/quality_measures/intermediate/"
    click Final "https://github.com/tuva-health/tuva/tree/main/models/core/final/"
    click DataMarts "https://github.com/tuva-health/tuva/tree/main/models/quality_measures/final/"
    click Macros "https://github.com/tuva-health/tuva/tree/main/macros/"
    click Snapshots "https://github.com/tuva-health/tuva/tree/main/snapshots/"
    click DQ "https://github.com/tuva-health/tuva/tree/main/models/data_quality/"
    click Docs "https://github.com/tuva-health/tuva/tree/main/docs/"
    click CI "https://github.com/tuva-health/tuva/tree/main/.github/workflows/"
    click Helper "https://github.com/tuva-health/tuva/tree/main/helper_scripts/"

    %% Styles
    classDef storage fill:#ffd8b1,stroke:#333,stroke-width:1px
    classDef model-layer fill:#b3d9ff,stroke:#333,stroke-width:1px
    classDef service fill:#d1ffd6,stroke:#333,stroke-width:1px
```
