What Are the Root Directories in dbt-labs/dbt-core? A Complete Guide

The root directories in dbt-labs/dbt-core separate the Rust-based engine code, project documentation, static assets, TLS certificates for testing, and CI automation into distinct top-level folders that enable the v2.0 architecture.

Understanding the root directory structure of the dbt-core repository clarifies how the codebase is compartmentalized between the Fusion engine, developer resources, and infrastructure. Each top-level folder serves a specific role in building, documenting, and testing the next-generation dbt runtime. This guide explains the purpose of every root directory based on the actual source code layout.

The crates/ Directory: Rust Engine Components

The crates/ directory contains the Rust crates that compose the dbt-core engine. Each sub-directory functions as an independent crate within the Cargo workspace, compiled into the single binary that powers the Fusion engine.

Key crates include:

• dbt-schemas – Defines the state model used by the compiler
• dbt-dag – Handles directed acyclic graph operations
• dbt-jinja – Processes Jinja templating logic
• dbt-tracing – Implements observability and logging features

The top-level Cargo.toml defines the workspace members using a glob pattern that includes every crate automatically:

# Cargo.toml workspace definition

[workspace]
members = ["crates/*"]

To build the entire workspace from the repository root:

cargo build --workspace --release

This command compiles all crates in crates/ into the final binary. For example, crates/dbt-schemas/src/state.rs contains the core schema logic used by the compiler to manage state across runs.

The docs/ and assets/ Directories: Documentation and Static Files

The docs/ directory stores project documentation and roadmap markdown files that are rendered on the dbt website. These files guide developers on architecture decisions, usage patterns, and future direction. A representative file is docs/roadmap/2026-06-announcing-v2.md, which documents the v2.0 rewrite announcement.

The assets/ directory holds static assets such as images used by documentation and marketing materials. For example, assets/dbt-fusion-engine.png illustrates the engine architecture in README files and web pages.

You can access documentation files programmatically relative to the repository root:

import pathlib

doc_path = pathlib.Path(__file__).parents[1] / "docs" / "roadmap" / "2025-12-magic-to-do.md"
print(doc_path.read_text().splitlines()[0])   # → "# 2025‑12 Magic To‑Do"

The certificates/ Directory: Test Security Fixtures

The certificates/ directory provides TLS certificates required by internal integration tests. These certificates are not used at runtime by end-users but ensure reproducible CI environments when testing connections to secure services.

For example, certificates/root.crt supplies the root certificate for mock TLS servers in test suites. A Rust integration test might load this certificate as follows:

let cert_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
    .join("certificates")
    .join("root.crt");
let cert = std::fs::read(cert_path).expect("certificate file");

Configuration and Automation at the Root

Several root-level files and directories manage project configuration and automation:

• Cargo.toml – The top-level Cargo manifest that defines the workspace structure and dependencies
• README.md – The entry point for developers that explains the v2.0 alpha status and points to the 1.latest branch for v1 development
• pyproject.toml – Contains Python packaging metadata for hybrid Python/Rust components
• .github/ – Houses GitHub workflow definitions, issue templates, and action scripts used for CI/CD, releases, and community automation (e.g., .github/workflows/release.yml)
• Hidden configuration files – .gitignore configures git behavior, while .cargo/config.toml sets Cargo defaults for the repository

Summary

• crates/ – Contains independent Rust crates (dbt-schemas, dbt-dag, dbt-jinja, dbt-tracing) that compile into the Fusion engine binary.
• docs/ – Stores markdown documentation and roadmap files explaining architecture and future plans.
• assets/ – Holds static images and media used in documentation and marketing.
• certificates/ – Provides TLS certificates exclusively for integration testing and CI reproducibility.
• Root configuration files – Cargo.toml manages the workspace, README.md guides contributors, and .github/ automates releases and testing.

Frequently Asked Questions

What is the purpose of the crates/ directory in dbt-core?

The crates/ directory houses the Rust-based components of the dbt-core engine, with each sub-directory representing an independent crate such as dbt-schemas or dbt-dag. These crates are compiled together via the workspace configuration in Cargo.toml to produce the single binary that powers the dbt Fusion engine.

How does the Cargo.toml file organize the dbt-core workspace?

The root Cargo.toml defines a Cargo workspace using the members glob crates/*, which automatically includes every crate located in the crates/ directory. This allows developers to build the entire project using cargo build --workspace without manually specifying each crate.

Are the certificates in dbt-core used in production environments?

No, the certificates stored in certificates/ are used exclusively for internal integration tests and CI pipelines to ensure reproducible TLS connections. They are not distributed with or used by the runtime binary in production environments.

Where can I find the roadmap documentation for dbt-core v2.0?

Roadmap documentation is located in the docs/roadmap/ directory, with files such as docs/roadmap/2026-06-announcing-v2.md detailing the v2.0 rewrite plans. The root README.md also directs developers to the appropriate branch for v1 (1.latest) versus v2 development.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}