The medallion architecture organises a lakehouse into three layers of increasing quality: bronze (raw data as it arrived), silver (cleaned and conformed) and gold (business-level tables). This sample shows a retailer's lakehouse from source systems through ingestion and the three layers to dashboards, ML and APIs.
This is an architecture diagram, not UML. UML covers software structure and behaviour; layered data architecture views are one of the other standard notations used alongside it.
1. The Diagram
Sources. An OLTP database (change data capture), a click stream and files from partners or SaaS APIs.
Ingestion. Incremental loaders (Auto Loader, a Kafka connector, COPY INTO) track what has already been loaded, so each record lands once.
Bronze. One table per source, append-only, with metadata such as ingest time and source file. Nothing is thrown away, so you can always rebuild.
Silver. Types are fixed, duplicates removed, records merged by key and history tracked where needed. This is where data becomes trustworthy.
Gold. Facts, dimensions and aggregates shaped for one purpose: revenue reporting, customer lifetime value.
Serving. BI tools, feature stores and reverse ETL read only gold (and sometimes silver). The dashed governance band shows that permissions and lineage apply to every layer.
2. How to Read It
Read left to right: each step to the right adds quality and loses generality. Keep the layer colours the same in every diagram your team draws, and list real table names inside each layer so the picture doubles as a map of the catalog.
3. Variant: Quality Gate into Silver
The main diagram hides the most important rule of silver: bad rows must not get in. Here each batch from bronze is checked against expectations. Passing rows are merged into silver.orders; failing rows go to a quarantine table together with the rule they broke. After the upstream bug or the rule is fixed, the quarantined rows are reprocessed. Thresholds turn quality into an operational signal: alert at 1% failures, stop at 5%.
4. Pros, Cons, and When to Use
Pros
Easy shared vocabulary: everyone knows what "a silver table" promises.
Shows where to look when numbers are wrong (bronze keeps the raw truth).
Separates ingestion concerns from business logic.
Maps directly onto catalog schemas and access policies.
Works for batch and streaming hops alike.
Cons
Three layers are a convention, not a law; some data needs two, some four.
Does not show schedules, freshness or SLAs.
Can hide heavy storage cost from keeping every layer.
Gold layer quickly turns into many tables that one box cannot represent.
Product names (Unity Catalog, Auto Loader) tie the diagram to one vendor.
When to use
Onboarding engineers and analysts to a lakehouse.
Agreeing quality contracts between layers.
Planning access control by layer.
When not to use
Detailed job dependencies (use a DAG).
Column-level provenance (use a lineage graph).
5. As Diagrams-as-Code
Mermaid flowchart LR with one subgraph per layer:
flowchart LR
pg[(Postgres CDC)] --> ing[Ingestion: Auto Loader / Kafka]
ks[(Clickstream Kafka)] --> ing
files[(Files / APIs)] --> ing
subgraph bronze[Bronze: raw]
orders_raw; clicks_raw; files_raw
end
subgraph silver[Silver: cleaned]
orders; customers; sessions
end
subgraph gold[Gold: business]
fct_revenue; dim_customer; customer_ltv
end
ing --> bronze --> silver --> gold
gold --> bi[BI dashboards]
gold --> ml[ML features]
gold --> api[Reverse ETL / API]