donniedata/mass-ehr-dbt

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.