Add Key Design Decisions section to 5.1 database seeding article

Author: workcontrolgit

blogs/series-5-devops-data/5.1-database-seeding.md

@@ -460,6 +460,22 @@ When an E2E test suite needs a specific dataset before running, this is where yo
 
 ---
 
+## 🔑 Key Design Decisions
+
+**`Faker<T>` for seeding, `AutoFaker<T>` for unit tests.** `DatabaseSeeder` uses `Faker<T>` with explicit rules for every field — giving precise control over FK assignment and field-to-field dependencies. `EmployeeBogusConfig` uses `AutoFaker<T>` which auto-fills unspecified fields — faster to write for unit test fixtures where exact values don't matter.
+
+**`.UseSeed()` makes generation deterministic.** Every developer who runs `dotnet run` gets the exact same 1,000 employees with the same names, emails, and FK assignments. Seed value `1969` is just a memorable constant — any integer works. Determinism is what makes automated tests reliable: if a test checks for a specific employee record, it can rely on that record always being there.
+
+**FK generation order mirrors the dependency graph.** `Departments` and `SalaryRanges` are generated first because `Positions` references them, and `Employees` reference both `Positions` and `Departments`. Reversing this order would produce FK values pointing to records that don't exist yet. The constructor enforces the correct sequence.
+
+**`SkipDbSeed` flag enables clean-state testing.** Setting `"SkipDbSeed": true` in `appsettings.Development.json` starts the API with an empty database. This is useful for integration tests that need to control exactly what data exists, or for testing the "empty state" UI experience without deleting and recreating the database.
+
+**Development-only seeding with an idempotency check.** The entire seed block is inside `if (app.Environment.IsDevelopment())` — production never auto-seeds. The `needsSeed` check (`!dbContext.Departments.Any() || !dbContext.Employees.Any()`) ensures the seeder only runs on an empty database, so restarting the API doesn't duplicate records.
+
+**`InsertMockPositionCommand` for runtime seeding.** The CQRS `POST /api/v1/positions/seed` endpoint lets you add more positions without restarting the API. It fetches existing departments and salary ranges from the database and passes them to `PositionInsertBogusConfig` — so every generated position has valid FK references to real rows. This pattern extends to any entity that has FK dependencies.
+
+---
+
 ## 🌟 Why This Matters
 
 Empty databases make demos unconvincing and make UI bugs invisible — you can't find pagination problems without enough rows to paginate. Starting with a Bogus-powered seeder that generates 1,000 realistic employees in three seconds means the application looks like a real HR system from day one, not a toy.