From d36fccebda2ea8ddd296bd140bb54e25d1617818 Mon Sep 17 00:00:00 2001 From: Dimitri Yatsenko Date: Fri, 14 Aug 2026 16:13:36 -0500 Subject: [PATCH] docs(normalization): illustrate the worked examples with dj.Diagram SVGs Add two generated, theme-adaptive dj.Diagram figures to the normalization chapter: - Fully normalized mouse-housing schema (Mouse/Cage entities + CageAssignment/ MouseWeight event tables; CageAssignment -> Cage shown as a secondary dashed FK). - Workflow-normalized order schema (Order with dashed secondary refs to Product/ Customer, then the 1:1 Order -> Payment -> Shipment -> Delivery chain). Both make the entity-vs-event split and the workflow chain visible. Single-table examples (denormalized Mouse, Species lookup) are left without diagrams. --- src/explanation/normalization.md | 4 + src/images/norm-mouse-housing.svg | 101 ++++++++++++++++++++++ src/images/norm-order-workflow.svg | 129 +++++++++++++++++++++++++++++ 3 files changed, 234 insertions(+) create mode 100644 src/images/norm-mouse-housing.svg create mode 100644 src/images/norm-order-workflow.svg diff --git a/src/explanation/normalization.md b/src/explanation/normalization.md index 5e4fd584..19bae464 100644 --- a/src/explanation/normalization.md +++ b/src/explanation/normalization.md @@ -215,6 +215,8 @@ class MouseWeight(dj.Manual): """ ``` +![Fully normalized mouse-housing schema, left to right: Mouse and Cage as entity tables; CageAssignment and MouseWeight as event tables keyed by date, each depending on Mouse. CageAssignment references Cage as a secondary (dashed) foreign key.](../images/norm-mouse-housing.svg) + This fully normalized design: - **Intrinsic attributes only** — `Mouse` contains only attributes determined at creation (birth date, sex) @@ -299,6 +301,8 @@ class Delivery(dj.Manual): """ ``` +![Workflow-normalized order schema, left to right: Order (referencing Product and Customer as secondary, dashed foreign keys), then a one-to-one chain Order → Payment → Shipment → Delivery, each step a separate table.](../images/norm-order-workflow.svg) + The foreign keys now form a chain — `Order → Payment → Shipment → Delivery` — that is simultaneously the referential-integrity structure and the workflow diagram. Every attribute is non-nullable, because a row exists only once its step diff --git a/src/images/norm-mouse-housing.svg b/src/images/norm-mouse-housing.svg new file mode 100644 index 00000000..f67860e4 --- /dev/null +++ b/src/images/norm-mouse-housing.svg @@ -0,0 +1,101 @@ + + + + + + + + + +cluster_cluster_housing + +norm_housing + + + +norm_housing.MouseWeight + + +MouseWeight + + + + + +norm_housing.CageAssignment + + +CageAssignment + + + + + +norm_housing.Mouse + + +Mouse + + + + + +norm_housing.Mouse->norm_housing.MouseWeight + + + + +norm_housing.Mouse->norm_housing.CageAssignment + + + + +norm_housing.Cage + + +Cage + + + + + +norm_housing.Cage->norm_housing.CageAssignment + + + + diff --git a/src/images/norm-order-workflow.svg b/src/images/norm-order-workflow.svg new file mode 100644 index 00000000..d32ebaec --- /dev/null +++ b/src/images/norm-order-workflow.svg @@ -0,0 +1,129 @@ + + + + + + + + + +cluster_cluster_orders + +norm_orders + + + +norm_orders.Customer + + +Customer + + + + + +norm_orders.Order + + +Order + + + + + +norm_orders.Customer->norm_orders.Order + + + + +norm_orders.Delivery + + +Delivery + + + + + +norm_orders.Payment + + +Payment + + + + + +norm_orders.Order->norm_orders.Payment + + + + +norm_orders.Shipment + + +Shipment + + + + + +norm_orders.Payment->norm_orders.Shipment + + + + +norm_orders.Product + + +Product + + + + + +norm_orders.Product->norm_orders.Order + + + + +norm_orders.Shipment->norm_orders.Delivery + + + +