# donniedata/mass-ehr-dbt architecture

> Architecture diagram of the GitHub repository donniedata/mass-ehr-dbt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/donniedata/mass-ehr-dbt
- Repository: https://github.com/donniedata/mass-ehr-dbt

## Overview

This repository is a dbt project for transforming EHR-style data into modeled analytics tables. The architecture is centered on SQL models organized by transformation domain, with dbt handling dependency management, schema routing, testing, and environment-specific deployment.

1. **Core runtime**
   - The project is built around **dbt** (`dbt_project.yml`, `profiles.yml`, `packages.yml`).
   - Execution happens as SQL transformations inside the warehouse, with dbt orchestrating model builds and dependencies rather than an application runtime.

2. **Source-to-model pipeline**
   - The main data flow appears to be: **raw EHR sources → transform models → downstream modeled tables**.
   - The source contract is likely defined in `models/mass_ehr_sources.yml`, which should serve as the boundary between external/raw data and dbt-managed transformations.

3. **Transformation layer**
   - The primary business logic lives in `models/transform/`.
   - This layer contains domain-specific models for:
     - claims
     - claim transactions
     - conditions
     - encounters
     - medications
     - patients
     - payers
     - procedures
   - These files indicate a normalized healthcare analytics layer built from multiple EHR entities.

4. **Domain boundaries**
   - Each transform file represents a separate subject area, which is a clear architectural boundary for diagramming.
   - The project is not organized as a single monolith model; instead, it is split into functional marts/entities that likely depend on shared raw sources and possibly each other.

5. **Model organization**
   - `models/model/` exists as a separate folder, but the visible tree does not show concrete SQL files there.
   - That suggests the repo may be using a layered dbt convention, with `model` reserved for another modeling stage and `transform` containing the active transformations.

6. **Reusable macros**
   - `macros/generate_schema_name.sql` defines custom schema naming behavior.
   - This is important architecturally because it affects where models materialize across environments, indicating environment-aware deployment and separation of dev/test/prod schemas.

7. **Environment and setup scripts**
   - `dev_scripts/ci_cd_setup.sql` and `dev_scripts/ehr_dev.sql` suggest warehouse setup or environment bootstrap for CI/CD and development.
   - These scripts likely prepare schemas, permissions, or seed/demo data needed for local and automated runs.

8. **Project packaging and dependencies**
   - `packages.yml` indicates external dbt packages are used.
   - This means the project likely relies on shared dbt utilities or packages for standard transformation/testing behavior, though the exact packages are not visible here.

9. **Testing and validation**
   - `tests/` exists as a dedicated area, but the tree shows only placeholders.
   - In dbt terms, validation is likely split between schema tests in YAML files and SQL-based custom tests, even if not shown in this snapshot.

10. **Snapshots and seeds**
   - `snapshots/` and `seeds/` are present but currently empty placeholders.
   - Their presence indicates the project is designed to support slowly changing data capture and static reference datasets, even if they are not yet populated.

11. **Analyses**
   - `analyses/` is also present as a placeholder, which typically houses ad hoc analytical SQL not materialized as production models.
   - This is a lower-priority, exploratory boundary separate from the core transformation pipeline.

12. **Operational shape**
   - The repo is intentionally lightweight: mostly dbt structure, SQL model files, and environment setup.
   - For an architecture diagram, the key components are the raw EHR source boundary, the transform layer by domain, the schema-mapping macro, and the setup scripts that enable consistent deployment across environments.

Main entry points: [`models/mass_ehr_sources.yml`](https://github.com/donniedata/mass-ehr-dbt/blob/main/models/mass_ehr_sources.yml) (source contract), [`models/transform/transform_patients.sql`](https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_patients.sql) (patients), [`dbt_project.yml`](https://github.com/donniedata/mass-ehr-dbt/blob/main/dbt_project.yml) (dbt project), [`models/transform/transform_claims.sql`](https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_claims.sql) (claims)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["dbt core"]
  node_dbt_project["dbt project<br/>project config<br/>[dbt_project.yml]"]
  node_profiles["profiles<br/>env config<br/>[profiles.yml]"]
  node_packages["packages<br/>deps<br/>[packages.yml]"]
  node_schema_macro["schema macro"]
  node_dev_setup["dev setup<br/>sql scripts<br/>[ci_cd_setup.sql]"]
  node_quality_surfaces["quality surfaces<br/>dbt surfaces"]
end

subgraph group_sources["source boundary"]
  node_source_contract["source contract<br/>source defs"]
end

subgraph group_transform["transform layer"]
  node_transform_claims["claims<br/>model"]
  node_transform_claims_tx["claim txns<br/>model"]
  node_transform_conditions["conditions<br/>model"]
  node_transform_encounters["encounters<br/>model"]
  node_transform_medications["medications<br/>model"]
  node_transform_patients["patients<br/>model"]
  node_transform_payers["payers<br/>model"]
  node_transform_procedures["procedures<br/>model"]
end

node_dbt_project -->|"uses"| node_profiles
node_dbt_project -->|"loads"| node_packages
node_dbt_project -->|"applies"| node_schema_macro
node_dbt_project -->|"builds from"| node_source_contract
node_source_contract -->|"feeds"| node_transform_claims
node_source_contract -->|"feeds"| node_transform_claims_tx
node_source_contract -->|"feeds"| node_transform_conditions
node_source_contract -->|"feeds"| node_transform_encounters
node_source_contract -->|"feeds"| node_transform_medications
node_source_contract -->|"feeds"| node_transform_patients
node_source_contract -->|"feeds"| node_transform_payers
node_source_contract -->|"feeds"| node_transform_procedures
node_transform_claims -.->|"supports"| node_transform_claims_tx
node_transform_patients -.->|"joins"| node_transform_encounters
node_transform_patients -.->|"joins"| node_transform_conditions
node_transform_patients -.->|"joins"| node_transform_medications
node_transform_patients -.->|"joins"| node_transform_procedures
node_dev_setup -->|"prepares"| node_profiles
node_dev_setup -.->|"aligns with"| node_schema_macro
node_quality_surfaces -.->|"validates"| node_transform_claims
node_quality_surfaces -.->|"validates"| node_transform_patients

click node_dbt_project "https://github.com/donniedata/mass-ehr-dbt/blob/main/dbt_project.yml"
click node_profiles "https://github.com/donniedata/mass-ehr-dbt/blob/main/profiles.yml"
click node_packages "https://github.com/donniedata/mass-ehr-dbt/blob/main/packages.yml"
click node_schema_macro "https://github.com/donniedata/mass-ehr-dbt/blob/main/macros/generate_schema_name.sql"
click node_source_contract "https://github.com/donniedata/mass-ehr-dbt/blob/main/models/mass_ehr_sources.yml"
click node_transform_claims "https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_claims.sql"
click node_transform_claims_tx "https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_claims_transactions.sql"
click node_transform_conditions "https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_conditions.sql"
click node_transform_encounters "https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_encounters.sql"
click node_transform_medications "https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_medications.sql"
click node_transform_patients "https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_patients.sql"
click node_transform_payers "https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_payers.sql"
click node_transform_procedures "https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_procedures.sql"
click node_dev_setup "https://github.com/donniedata/mass-ehr-dbt/blob/main/dev_scripts/ci_cd_setup.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dbt_project,node_profiles,node_packages,node_schema_macro,node_dev_setup,node_quality_surfaces toneBlue
class node_source_contract toneAmber
class node_transform_claims,node_transform_claims_tx,node_transform_conditions,node_transform_encounters,node_transform_medications,node_transform_patients,node_transform_payers,node_transform_procedures toneMint
```

## Components

### dbt core

Project configuration and execution boundary

- [dbt project](https://github.com/donniedata/mass-ehr-dbt/blob/main/dbt_project.yml): project config · Main dbt project configuration and model routing · `dbt_project.yml`
- [profiles](https://github.com/donniedata/mass-ehr-dbt/blob/main/profiles.yml): env config · Warehouse connection and environment profile settings · `profiles.yml`
- [packages](https://github.com/donniedata/mass-ehr-dbt/blob/main/packages.yml): deps · External dbt package dependencies · `packages.yml`
- [schema macro](https://github.com/donniedata/mass-ehr-dbt/blob/main/macros/generate_schema_name.sql): macro · Custom schema naming and environment-aware materialization behavior · `macros/generate_schema_name.sql`
- [dev setup](https://github.com/donniedata/mass-ehr-dbt/blob/main/dev_scripts/ci_cd_setup.sql): sql scripts · Development and CI/CD warehouse bootstrap scripts · `dev_scripts/ci_cd_setup.sql`
- **quality surfaces**: dbt surfaces · Testing, snapshots, seeds, and ad hoc analysis areas

### source boundary

External EHR inputs and contract definitions

- [source contract](https://github.com/donniedata/mass-ehr-dbt/blob/main/models/mass_ehr_sources.yml): source defs · Declared raw EHR sources and dbt source boundary · `models/mass_ehr_sources.yml`

### transform layer

Domain-specific modeled tables

- [claims](https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_claims.sql): model · Claims domain transformation · `models/transform/transform_claims.sql`
- [claim txns](https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_claims_transactions.sql): model · Claim transaction transformation · `models/transform/transform_claims_transactions.sql`
- [conditions](https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_conditions.sql): model · Conditions domain transformation · `models/transform/transform_conditions.sql`
- [encounters](https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_encounters.sql): model · Encounters domain transformation · `models/transform/transform_encounters.sql`
- [medications](https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_medications.sql): model · Medications domain transformation · `models/transform/transform_medications.sql`
- [patients](https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_patients.sql): model · Patients domain transformation · `models/transform/transform_patients.sql`
- [payers](https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_payers.sql): model · Payers domain transformation · `models/transform/transform_payers.sql`
- [procedures](https://github.com/donniedata/mass-ehr-dbt/blob/main/models/transform/transform_procedures.sql): model · Procedures domain transformation · `models/transform/transform_procedures.sql`

## Connections

- dbt project → profiles: uses · Project execution is driven by environment profile settings
- dbt project → packages: loads · Project resolves external dbt package dependencies
- dbt project → schema macro: applies · Custom schema naming affects model materialization
- dbt project → source contract: builds from · Project models are organized around declared sources
- source contract → claims: feeds · Raw EHR data feeds claims modeling
- source contract → claim txns: feeds · Raw EHR data feeds claim transaction modeling
- source contract → conditions: feeds · Raw EHR data feeds conditions modeling
- source contract → encounters: feeds · Raw EHR data feeds encounters modeling
- source contract → medications: feeds · Raw EHR data feeds medications modeling
- source contract → patients: feeds · Raw EHR data feeds patient modeling
- source contract → payers: feeds · Raw EHR data feeds payer modeling
- source contract → procedures: feeds · Raw EHR data feeds procedure modeling
- claims → claim txns: supports · Claims and claim transactions are related domain outputs
- patients → encounters: joins · Patient identity is a common dimension across clinical facts
- patients → conditions: joins · Patient identity is a common dimension across clinical facts
- patients → medications: joins · Patient identity is a common dimension across clinical facts
- patients → procedures: joins · Patient identity is a common dimension across clinical facts
- dev setup → profiles: prepares · Bootstrap scripts help set up warehouse access and schemas
- dev setup → schema macro: aligns with · Setup supports the same environment-specific schema strategy
- quality surfaces → claims: validates · Tests and validation surface modeled outputs
- quality surfaces → patients: validates · Tests and validation surface modeled outputs