# Medallion Architecture

## Purpose
The Medallion Architecture organizes a data lakehouse into three layers with increasing
data quality and fitness for purpose. Apply this skill when designing the overall structure
of a data solution, evaluating which layer a new artifact belongs to, or assessing the
current state of an existing solution.

## Layers

### Bronze (Raw)
Stores data exactly as received from source systems — no transformation, no cleaning.
Preserves the full history for reprocessing and auditability.

**Rule**: Never modify Bronze data. If the source changes, capture the new state as a new version.

Naming: `Store_{SourceSchema}_{SourceTable}` / `Access_{SourceSchema}_{SourceTable}`

### Silver (Integrated)
Cleaned, integrated, historized enterprise data. Single source of truth.
Modeled using a chosen integration pattern — see `lean-data-vault.md`, `data-vault.md`, or `3nf.md`.

**Rule**: Silver is always built from Bronze Access views — never directly from source systems.
**Rule**: Silver is the authoritative source for all downstream Gold artifacts.

Naming: depends on chosen methodology (see respective skill).

### Gold (Consumption)
Domain-optimized structures for reporting, analytics, and machine learning.
Modeled using a consumption pattern — typically Star Schema (see `star-schema.md`).

**Rule**: Gold is always built from Silver Access views — never from Silver Key/Hist tables
directly, and never from Bronze.

Naming: `Store_Dim{Entity}` / `Store_Fact{Subject}` (Star Schema)

## Layer Boundaries

| Allowed | Not Allowed |
|---|---|
| Gold reads Silver Access views | Gold reads Silver Key/Hist tables directly |
| Silver reads Bronze Access views | Silver reads Bronze Store tables directly |
| Bronze stores raw source data | Bronze transforms or cleans data |

## When to Use Which Layer

| Need | Layer |
|---|---|
| Raw source preservation, full reprocessing capability | Bronze |
| Integrated, historized, multi-source master data | Silver |
| Reporting, BI dashboards, analytics, ML features | Gold |

## Anti-Patterns
- **Skipping Silver**: Joining Bronze directly to Gold creates fragile, unmaintainable pipelines.
- **Mixed layer responsibilities**: A Bronze artifact that transforms data defeats the layer contract.
- **Business logic in tables**: Belongs in views (Silver Access views, Gold transformation logic).
- **Multiple Gold sub-layers**: One consumption layer per domain; avoid nesting Gold artifacts.
