Initializing a dbt Project Structure

In this lesson, you will learn how to organize your dbt project into a professional, scalable directory structure to keep your data transformation logic maintainable and easy to navigate.

Why Structure Matters

When your data pipelines grow beyond a few models, dumping every SQL file into one folder creates technical debt. A standard dbt project structure separates your raw data, intermediate business logic, and final reporting tables. This organization allows you to decouple your "sources" (raw data ingested into your warehouse) from your "models" (the cleaned and transformed data).

The Standard Directory Layout

When you run dbt init, dbt creates a scaffold for you. To keep your project robust, you should organize your models/ directory into three logical layers:

1. staging/: Here, you define your sources.yml files. This is where you perform light cleaning, such as renaming columns or casting data types to match your internal standards.
2. intermediate/: This is the "engine room." Use this layer for complex joins and business logic that is reused across multiple final models. Keeping this separate prevents redundant code.
3. marts/: This is where your final, business-ready data lives. Organize these by business process (e.g., finance/, marketing/, or sales/).

Organizing Your Files

Your directory tree should look something like this:

my_dbt_project/
├── dbt_project.yml
├── models/
│   ├── staging/
│   │   ├── src_stripe.yml
│   │   └── stg_payments.sql
│   ├── marts/
│   │   └── finance/
│   │       └── fct_revenue.sql
└── tests/
    └── singular_tests.sql

By separating these folders, you create clear boundaries. When a stakeholder asks for a change, you know exactly whether to modify a raw source definition in staging/ or a business metric in marts/.

Additionally, the dbt_project.yml file acts as the configuration hub. It tells dbt where your models are, how to materialize them (e.g., as tables or views), and what configurations should apply globally. Establishing this structure early prevents the "spaghetti code" effect as your data team scales.

Key Takeaway: A well-organized dbt project uses a layered architecture—staging, intermediate, and marts—to ensure your transformation logic is modular, testable, and easy for the team to navigate.