dbt Project Structure: Guide Hub

This hub connects all notes on structuring a dbt project — layers, naming, materialization, YAML, modern features, and marketing analytics patterns. Consistency of conventions matters more than any specific choice; these notes provide an opinionated, tested framework based on auditing projects with 400+ models.

Prerequisites

• Basic dbt concepts (models, refs, sources, tests)
• SQL at an intermediate level
• The concept of a DAG (directed acyclic graph)

Reading Order

Start with the architecture:

1. dbt Three-Layer Architecture — The base → intermediate → marts pattern. Why alphabetical order matches lineage order. When you need all three layers versus when base + marts suffices.
2. dbt Base Layer Patterns — What belongs in base models (renaming, casting, deduplication, unnesting) and what doesn’t (business logic, joins, aggregations).
3. dbt Intermediate Layer Patterns — What belongs in intermediate (joins, business logic, window functions). The critical constraint: never reduce grain.
4. dbt Entity-Centric Naming for Intermediate Models — The opinionated case for naming intermediate models after entities, not transformations. The int__customer__customer_lj_order pattern.
5. dbt Mart Layer Patterns — What belongs in marts (aggregations for consumption, consumer-specific formatting). The principle that every mart serves a specific consumer.

Then the project-level decisions:

6. dbt Project Structure and Naming — Folder layout, the double-underscore naming convention, YAML organization (per-directory pattern), dbt_project.yml configuration, and what goes in macros, seeds, snapshots, and tests.
7. dbt Materialization Default: Tables Everywhere — The case against views and ephemeral as defaults. Why storage is cheap and debugging visibility is not.
8. Incremental Models in dbt — When to move from table to incremental, which strategies to use, and how to handle late-arriving data.

Modern dbt features worth adopting:

9. dbt Testing Taxonomy — Generic tests, singular tests, unit tests (dbt 1.8+), and contracts. Test intensity should increase toward the edges of the DAG.
10. dbt Model Contract Mechanics — Schema contracts for public-facing marts. Fail-fast behavior at build time.
11. dbt Groups and Access Modifiers — Ownership and access control. Worth using even in single projects for documentation, future-proofing, and enforced architectural boundaries.

For Marketing Analytics Specifically

If you’re building marketing analytics pipelines, these notes cover domain-specific patterns:

• dbt Ad Reporting Patterns — Cross-platform UNION patterns, platform-specific normalization, the dbt_ad_reporting package
• GA4 Sessionization Hub — Modeling GA4 event data in dbt, sessionization logic, incremental strategies for GA4
• SQL Attribution Patterns — First-touch, last-touch, and multi-touch attribution in SQL

Conventions Documentation

Write conventions down. A CONTRIBUTING.md in the dbt project root documenting naming conventions, materialization strategy, and layer responsibilities makes the conventions available to everyone working in the project.