Dynamic Clinic Seeder — Overview
Status: unreleased. This is an internal engineering + demo tool that ships on a feature branch (feat/sandbox-seed). It is not a customer-facing product feature. Everything below describes what the code on this branch actually does.
What this is, in one page
Every time someone opens a pull request, Dentolize now spins up a live preview of the whole app — a real web address, a real API, and a real database. This PR is about what goes inside that database.
Until now, a preview environment came up almost empty: you could log in, but there were no patients, no invoices, no appointments — nothing to actually look at or test. This PR adds a dynamic clinic seeder: a script that builds one complete, believable dental clinic from scratch, with months of history, and loads it into the preview database before anyone logs in.
The result is a sandbox that looks like a clinic that has been running for a year: dozens of patients, hundreds of completed visits with correctly-calculated invoices, insurance splits, part-paid balances, a funded cash drawer and bank account, stocked inventory that has been bought and consumed, staff with commissions and salaries, insurers with policy tiers, and a calendar with today's and next-fortnight's appointments already booked.
Why it matters
- Reviewers and QA see a real clinic, not an empty shell. You can judge a UI
change against realistic data the moment the preview is up.
- Sales and demos get a dependable, good-looking dataset on any branch,
refreshed on demand — no more hand-building demo accounts.
- It's deterministic. The same seed produces the same clinic every time, so
screenshots, tests, and "pick patient 003" instructions stay stable.
- It's merge-safe with the accounting module. The seeder was copied
byte-for-byte from the accounting branch, minus the accounting-only files. When accounting merges later, it layers back in through a pre-built extension point ("the hook seam") with no conflicts — see Architecture.
What's actually in this PR
| Area | What changed |
|---|---|
| The seeder | A new self-contained module, packages/server/src/generateServerData/dynamicSeed/, run via yarn seed-dynamic. |
| Determinism | Pins @faker-js/faker and drives every random draw from a fixed seed. |
| Sandbox CI | The PR preview comment now labels the login as rich demo dataset vs basic auto-seed, includes the username, and lists the whole staff roster. New "Sandbox Ops" and "Sandbox QA" workflows. |
| S3 uploads | The upload path now supports S3-compatible object stores (MinIO in the sandbox) via env vars, with production unchanged. |
| Small fixes | A feature-flag seeder import path fix. |
How to read these docs
Every topic here is explained twice:
- a Business view — plain language, no engineering background needed; and
- a Technical view — the exact models, functions and behavior, with
file:line pointers into the repository.
If you own a team, start with your By team page. If you want to see the seeded clinic, jump to the Feature Tour. If you want to know how it works under the hood, start with Architecture.
Honesty note. This walkthrough documents the code as written, not the PR description's claims. Where the two differ, the code wins and the gap is called out. One example already: the PR title says "small profile: 3 months"; the code default is 12 months / 80 patients (config.js:62), and the sandbox overrides those per run — see Parameters & safety.