Glossary & data model
Terms
Dynamic seeder — the script in packages/server/src/generateServerData/dynamicSeed/ that builds one complete clinic from parameters. Run with yarn seed-dynamic.
Rich seed vs basic seed — "rich" is the dynamic seeder's full clinic (SEED_MODE=rich). "Basic" is the minimal overlay auto-seed on branches without dynamicSeed/. The PR comment labels which one ran.
Descriptive vs realistic naming — NAMING=descriptive encodes each record's configuration in its name ("Patient 011 · Insured 50%"); realistic uses normal localized names. Sandbox = descriptive; marketing captures should use realistic.
Country preset — SA / AE / EG, fixing currency, VAT, dial code, timezone, Faker locale, cities and insurers (countries.js:7). VAT/currency come from the preset, never Faker.
The hook seam — the extension point in hooks.js that lets the shared files run generically (base schema, no GL) or, when accountingHooks.js is present, with real general-ledger postings, HR and payroll. See Architecture.
Merge invariant — the rule that shared seeder files stay byte-identical across the main line and the accounting branch, so accounting merges without conflicts.
Operational vs GL bookkeeping — "operational" = the subledger rows and balances the app UI reads (treasury balance, inventory value, patient balance, invoice paid). "GL" = general-ledger journal legs. The seeder always writes operational data (money.js); GL legs are hook-gated and only exist on the accounting branch.
Idempotency (per OWNER_EMAIL) — re-running the seeder when the owner already exists refreshes passwords and reprints creds instead of creating a second company (index.js:71).
Safety guard — the refusal to seed a non-local DATABASE_URL without --confirm (config.js:105).
Insurer AR left open — the seeder pays the patient's share of each invoice but leaves the insurer's share as an unpaid receivable, on purpose, so the claims flow has AR to settle (generate.js:11).
Treasury — a money location on a branch: cash drawer, card/POS terminal, or bank account. The seeder makes all three per branch (setupBranches.js:18).
Policy class — an insurance tier (Class A–D) with a coverage percentage and a limit (catalog.js:36); insured patients are attached to one.
Wallet / patient balance — prepaid credit on a patient. ~25% of patients prepay; some visits are paid from the wallet (generate.js:264, fundWallet money.js:141).
SANDBOX_SEED_INFO / SANDBOX_SEED_USERS — the machine-readable blocks the seeder prints for the sandbox CLI to parse into the PR comment (report.js:32).
MinIO — the self-hosted, S3-compatible object store the sandbox uses for uploads; enabled via env vars in this PR (s3.js:15). See S3-compatible uploads.
Data model touched by the seed
The seeder writes to existing product models — it defines no new schema. The main tables it populates, roughly in creation order:
| Model | Written by | Notes |
|---|---|---|
Company | S-1 | tier 2, isBeta, groups + all catalog arrays |
permission Groups | S-1 | via createGroups |
| procedure / condition / medical / clinical / note-template groups | S-1 | from chart-specific seed data |
Branch | S-2 | rooms, localized hours in tenant tz |
Treasury (×3/branch) | S-2 | cash / card / bank |
BranchTreasury | S-2 | default-treasury mappings |
PriceList + Price | S-2, S-4 | standard list + per-insurer plans |
User (owner / doctors / staff) | S-3 | groups, commissions, salaries |
DoctorPercent | S-3 | per-procedure commission overrides |
Supplier | S-4 | 3 dental suppliers |
InventoryStorage (master/branch) | S-4 | |
InventoryItem | S-4 | 15 consumables; allowNegative |
InventoryOrder / InventoryTransaction | S-4/S-5 | purchases + usage |
InsuranceCompany / InsurancePolicy / PolicyClass | S-4 | region insurers, Class A–D tiers |
Patient | S-5 | demographics, insurance link, denormalized totals |
Appointment | S-5 | completed history + upcoming bookings |
Operation | S-5 | one per procedure per visit |
Invoice | S-5 | subtotal/discount/tax/total/insurance split |
Payment + Transaction | S-5 | cash/card/wallet; treasury moves |
SalaryAdjustment | S-5 | doctor commission accruals |
Expense (+ BillingPayment) | S-4/S-5 | stock, assets, monthly opex |
Quotation | S-5 | ~15% of patients (best-effort) |
Accounting/HR/GL models (journals, payroll runs, fixed assets, categories, attendance, leave) are only written on the accounting branch through the hook seam — not by this branch. See Architecture.
Where to read the code
- Orchestration & steps —
index.js, and The seed pipeline - Parameters, presets, safety —
config.js/countries.js, and
- The money —
generate.js/money.js, and The money model - The seam —
hooks.js, and Architecture - Sandbox contract —
report.js, and Sandbox & CI wiring