dbt-architecture

dbt Architecture

Purpose

Transform AI agents into experts on dbt project architecture and medallion layer patterns, providing guidance on structuring production-grade dbt projects with proper layer separation, naming conventions, and configuration strategies.

When to Use This Skill

Activate this skill when users ask about:

• Planning dbt project structure and folder organization
• Implementing medallion architecture (bronze/silver/gold)
• Establishing naming conventions for models and columns
• Configuring folder-level settings in dbt_project.yml
• Ensuring proper model dependencies and data flow
• Understanding layer separation and architectural patterns
• Setting up tag inheritance strategies

Core Philosophy: Medallion Architecture + Best Practices Integration

Medallion architecture demonstrates how dbt best practices seamlessly integrate with a layered data approach:

• Bronze Layer = Staging Models (stg_) - One-to-one source relationships
• Silver Layer = Intermediate Models (int_) - Business logic transformations
• Gold Layer = Marts (dim_, fct_) - Business-ready data products

Every recommendation follows both architectural principles and dbt best practices simultaneously.

---

Medallion Architecture Quick Reference

Three Layers

Bronze (Staging):

• Naming: stg_{source}__{table}
• Materialization: ephemeral
• Purpose: One-to-one source cleaning
• Rules: No joins, no business logic

Silver (Intermediate):

• Naming: int_{entity}__{description}
• Materialization: ephemeral or table
• Purpose: Business logic, enrichment
• Rules: No direct source references

Gold (Marts):

• Naming: dim_{entity} or fct_{process}
• Materialization: table or incremental
• Purpose: Business-ready data products
• Rules: Fully tested, documented, optimized

---

Critical Architectural Rules

Always enforce these patterns:

1. ✅ No Direct Joins to Source - Models reference staging (ref('stg_*')), never source() directly
2. ✅ One-to-One Staging - Each source table has exactly ONE staging model
3. ✅ Proper Layering - Clear flow: staging → intermediate → marts
4. ✅ Standardized Naming - Consistent stg_, int_, dim_, fct_ prefixes
5. ✅ Use ref() and source() - No hard-coded table references
6. ✅ Folder-Level Configuration - Set common settings in dbt_project.yml