From 92a30b11db93029785ac07182704e32e1b7a57a3 Mon Sep 17 00:00:00 2001
From: Aaron Po <aaron.po97@gmail.com>
Date: Thu, 27 Aug 2026 01:02:58 -0400
Subject: [PATCH] Update docs to reflect per-table DDL scripts and schema.dbml
 from #251 (#252)

---
 docs/architecture.md     | 12 ++++++++----
 docs/website/database.md | 18 ++++++++++++------
 2 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index cd98e485..4f4f6a95 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -476,12 +476,16 @@ For the table-by-table schema and the custom SQL error code scheme, see
 ```
 scripts/
 └── 01-schema/
-    └── schema.sql   # full table/index/constraint definitions
+    ├── 01-UserAccount.sql
+    ├── 02-Photo.sql
+    ├── ...
+    └── 16-BeerPostComment.sql   # one script per CREATE TABLE
 ```
 
-Currently the whole schema is a single versioned script. As the schema evolves,
-new numbered scripts get added alongside it rather than editing `schema.sql` in
-place, so DbUp's already-applied tracking stays valid.
+Each table has its own script, numbered so a table's foreign keys always point
+at an earlier-numbered script. As the schema evolves, new numbered scripts get
+added rather than editing an existing one in place, so DbUp's already-applied
+tracking stays valid.
 
 ### Data seeding
 
diff --git a/docs/website/database.md b/docs/website/database.md
index dbb28d24..2326d03b 100644
--- a/docs/website/database.md
+++ b/docs/website/database.md
@@ -6,12 +6,17 @@ convention. For the vertical-slice code that talks to this schema, see
 
 ## Schema
 
-The full schema lives in one script:
-`web/backend/Database/Database.Migrations/scripts/01-schema/schema.sql`, run by
+The full schema lives under
+`web/backend/Database/Database.Migrations/scripts/01-schema/`, one numbered
+script per table (`01-UserAccount.sql`, `02-Photo.sql`, ...), run in order by
 `Database.Migrations` (DbUp) on startup. Each table is queried directly by the
 owning feature slice's repository (see
 [Direct SQL via Dapper/ADO.NET](../architecture.md#direct-sql-via-dapperadonet)).
 
+A generated DBML copy of the schema (for import into a diagramming tool such
+as dbdiagram.io) lives at
+`web/backend/Database/Database.Migrations/schema.dbml`.
+
 All tables use a `UNIQUEIDENTIFIER` primary key defaulting to `NEWID()`, and
 most carry a `RowVersion ROWVERSION` column used for optimistic concurrency on
 updates (`UPDATE ... WHERE ... AND RowVersion = @RowVersion`).
@@ -50,10 +55,11 @@ repository or seed data yet:
 **Tool**: DbUp, run by the `Database.Migrations` project/container.
 
 Scripts live under `scripts/`, applied in order and tracked so a script never
-re-runs once it has succeeded. Today that's a single `01-schema/schema.sql`.
-When the schema needs to change, add a new numbered script rather than editing
-`schema.sql` in place — DbUp's tracking is per-script, so editing an
-already-applied script means it won't re-run against existing databases.
+re-runs once it has succeeded. Today that's `01-schema/`, with one script per
+table, numbered so a table's foreign keys always point at an earlier-numbered
+script. When the schema needs to change, add a new numbered script rather than
+editing an existing one in place — DbUp's tracking is per-script, so editing
+an already-applied script means it won't re-run against existing databases.
 
 ## Data seeding