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

> Understand dbt-labs/dbt-core root directories. Learn how distinct folders separate engine code, docs, assets, and CI for the v2.0 architecture. Explore the complete guide.

- Repository: [dbt Labs/dbt-core](https://github.com/dbt-labs/dbt-core)
- Tags: deep-dive
- Published: 2026-06-28

---

**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`](https://github.com/dbt-labs/dbt-core/blob/main/Cargo.toml) defines the workspace members using a glob pattern that includes every crate automatically:

```toml

# Cargo.toml workspace definition

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

```

To build the entire workspace from the repository root:

```bash
cargo build --workspace --release

```

This command compiles all crates in `crates/` into the final binary. For example, [`crates/dbt-schemas/src/state.rs`](https://github.com/dbt-labs/dbt-core/blob/main/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`](https://github.com/dbt-labs/dbt-core/blob/main/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:

```python
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:

```rust
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`](https://github.com/dbt-labs/dbt-core/blob/main/.github/workflows/release.yml))
- **Hidden configuration files** – `.gitignore` configures git behavior, while [`.cargo/config.toml`](https://github.com/dbt-labs/dbt-core/blob/main/.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`](https://github.com/dbt-labs/dbt-core/blob/main/Cargo.toml) manages the workspace, [`README.md`](https://github.com/dbt-labs/dbt-core/blob/main/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`](https://github.com/dbt-labs/dbt-core/blob/main/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`](https://github.com/dbt-labs/dbt-core/blob/main/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`](https://github.com/dbt-labs/dbt-core/blob/main/docs/roadmap/2026-06-announcing-v2.md) detailing the v2.0 rewrite plans. The root [`README.md`](https://github.com/dbt-labs/dbt-core/blob/main/README.md) also directs developers to the appropriate branch for v1 (`1.latest`) versus v2 development.