Database Seeds

K-12 school simulation for demo.databayt.org — 17 phases, single-language storage, idempotent upserts.

The seed system creates a realistic K-12 school for demo.databayt.org. Content is stored in one language (Arabic primary) with a lang field; translation happens on demand via Google Translate + DB cache. All seeds are idempotent upserts — safe to re-run.

Quick start

# Seed a single module (always use this)
pnpm db:seed:single <name>
 
# List available seeds
pnpm db:seed:single --list

Always use pnpm db:seed:single <name>. Full seed is forbidden — auto-blocked by a pre-tool hook. The full sequential run takes 45–120 minutes and is reserved for manual full resets only. See CLAUDE.md rule #8 and safe seeds.

Counts

Entity	Count	Notes
Users	3,105	All roles, `@databayt.org` emails
Teachers	100	Arabic names, qualifications, expertise
Students	970	K-12 distribution
Guardians	2,000	2 per student (father + mother)
Staff	26	Non-teaching
Departments	6	Arabic primary + `lang`
Subjects	19	Arabic primary + `lang`
Year Levels	14	KG1–12
Classrooms	28	Labs, rooms, special facilities
Classes	187	Subject × level
Student Enrollments	12,950	All classes
Assignments	188	All classes
Submissions	13,371	With grade distribution
Lumos Categories	8	Arabic LMS
Lumos Courses	59	With chapters
Lumos Enrollments	200
Books	90	Unique Arabic-titled
Borrow Records	99	Active, overdue, returned
Exams	~200	Midterm + Final + Quizzes
Exam Results	~1,500	With grade distribution
Question Bank	~950	Arabic educational
Fee Structures	8	2-year history
Fee Assignments	~1,940	Per student per year
Payments	~500	With receipt numbers
Invoices	10	With items + addresses
Expense Receipts	10	OCR data (SDG)
Salary Structures	100	Allowances + deductions
Timesheet Entries	~6,000	3 months daily
Payroll Runs	3	Oct–Dec 2025, all PAID
Bank Accounts	3	Operating, Savings, Petty Cash
Transactions	100	Oct–Dec 2025 (SDG)
Finance	~500	Chart of accounts + journals
Attendance	~60,000	60 days
Timetable Entries	~1,500	Conflict-free
Gamification	~350	Badges, streaks, competitions
Conversations	~50	300+ messages
Notifications	~500	Mixed
Admission	~50	Campaigns + applications
Catalog Subjects	~240	US K-12 grade-specific, + Sudan base
Catalog Chapters	~750	Platform-wide (no schoolId)
Catalog Lessons	~3,993	US-curriculum sourced
Audit Logs	~500
Health Records	~110	Health, disciplinary, achievements
Student Documents	200	Birth certs, passports, medical

Accounts

For the named-account table, bulk-account counts, simulation flows, and access matrix, see Test accounts — the canonical reference. For the Sudanese-specific configuration (periods, year levels, departments, classrooms, fee tiers), see Sudan curriculum.

17 phases

Phase	Module	What it creates
0	Global Catalog	`seedCatalog()` — US K-12: Subjects (~240), Chapters (~750), Lessons (~3,993) + Sudan base, images (S3/CloudFront)
1	Core Foundation	School (`demo.databayt.org`), branding
2	User Accounts	All 3,105 users
3	Academic Structure	School Year (2025–2026), Terms, Periods (8 + 2 breaks), Departments (6), Year Levels (14)
4	Subjects & Classrooms	Subjects (19), Classroom Types (8), Classrooms (28)
5	People	Teachers (100), Students (970), Guardians (~1,940), Staff (26)
6	Classes & Enrollments	Classes (187), Student Enrollments (12,950), Teacher Assignments (187)
7	LMS / Lumos	Categories (8), Courses (59), Enrollments (200), Lessons, Library (90 books, 99 borrows)
8	Assignments	Assignments (188), Submissions (13,371)
9	Announcements & Events	Temporal spread, MENA calendar Sep 2025 – Jun 2026
10	Exams, QBank & Grades	Exams (~200), exam results, QBank (~950 Arabic), grading config, gradebook `Result` rows derived from graded submissions, report cards + per-subject grades via the production aggregation
11	Finance	Chart of accounts (2-year), Fee Structures (8), Assignments (~1,940), Payments (~500), Invoices (10), Expense Receipts (10), Payroll
12	Banking	3 accounts, 100 transactions (Oct–Dec 2025)
13	Operations	Attendance (~60,000), Excuses + Interventions, Timetable (~1,500), Gamification (~350)
14	Communications	Conversations (~50, 300 messages), Notifications (~500)
15	Admission	Campaigns + Applications (~50)
16	Compliance & Wellness	Audit Logs (~500), Health/Disciplinary/Achievements (~110)

Idempotent upserts

await prisma.subject.upsert({
  where: {
    schoolId_departmentId_subjectName: {
      schoolId,
      departmentId,
      subjectName: "الرياضيات",
    },
  },
  update: { lang: "ar" },
  create: { schoolId, departmentId, subjectName: "الرياضيات", lang: "ar" },
})

Re-runnable. Never duplicates. Safe in CI. For the single-language storage strategy and getText() helper, see Translation.

Troubleshooting

pnpm db:seed:single <name>      # single module
pnpm db:seed:single --list      # available seeds
pnpm db:reset-test-user         # reset user@balqalam.com
pnpm db:reset-test-applicant    # reset applicant@balqalam.com
pnpm prisma migrate reset       # destructive: drop all data (manual only)

Issue	Fix
Deadlock detected	Reduce batch size in `people.ts`
Table does not exist	`pnpm prisma db push`
Unknown field	Check schema, run `prisma generate`
Foreign key constraint	Seeds run in dependency order
Prisma client not found	`pnpm prisma generate`
Can't reach database	Neon auto-suspend; retry once

npx prisma studio opens the data browser.

Production

Seeds are for development and demo only. Never run on production without review. Use migrations for schema changes. ensure-demo.ts provides Vercel deployment safety checks.

Entity	Count	Notes
Users	3,105	All roles, `@databayt.org` emails
Teachers	100	Arabic names, qualifications, expertise
Students	970	K-12 distribution
Guardians	2,000	2 per student (father + mother)
Staff	26	Non-teaching
Departments	6	Arabic primary + `lang`
Subjects	19	Arabic primary + `lang`
Year Levels	14	KG1–12
Classrooms	28	Labs, rooms, special facilities
Classes	187	Subject × level
Student Enrollments	12,950	All classes
Assignments	188	All classes
Submissions	13,371	With grade distribution
Lumos Categories	8	Arabic LMS
Lumos Courses	59	With chapters
Lumos Enrollments	200
Books	90	Unique Arabic-titled
Borrow Records	99	Active, overdue, returned
Exams	~200	Midterm + Final + Quizzes
Exam Results	~1,500	With grade distribution
Question Bank	~950	Arabic educational
Fee Structures	8	2-year history
Fee Assignments	~1,940	Per student per year
Payments	~500	With receipt numbers
Invoices	10	With items + addresses
Expense Receipts	10	OCR data (SDG)
Salary Structures	100	Allowances + deductions
Timesheet Entries	~6,000	3 months daily
Payroll Runs	3	Oct–Dec 2025, all PAID
Bank Accounts	3	Operating, Savings, Petty Cash
Transactions	100	Oct–Dec 2025 (SDG)
Finance	~500	Chart of accounts + journals
Attendance	~60,000	60 days
Timetable Entries	~1,500	Conflict-free
Gamification	~350	Badges, streaks, competitions
Conversations	~50	300+ messages
Notifications	~500	Mixed
Admission	~50	Campaigns + applications
Catalog Subjects	~240	US K-12 grade-specific, + Sudan base
Catalog Chapters	~750	Platform-wide (no schoolId)
Catalog Lessons	~3,993	US-curriculum sourced
Audit Logs	~500
Health Records	~110	Health, disciplinary, achievements
Student Documents	200	Birth certs, passports, medical

17 phases

Phase	Module	What it creates
0	Global Catalog	`seedCatalog()` — US K-12: Subjects (~240), Chapters (~750), Lessons (~3,993) + Sudan base, images (S3/CloudFront)
1	Core Foundation	School (`demo.databayt.org`), branding
2	User Accounts	All 3,105 users
3	Academic Structure	School Year (2025–2026), Terms, Periods (8 + 2 breaks), Departments (6), Year Levels (14)
4	Subjects & Classrooms	Subjects (19), Classroom Types (8), Classrooms (28)
5	People	Teachers (100), Students (970), Guardians (~1,940), Staff (26)
6	Classes & Enrollments	Classes (187), Student Enrollments (12,950), Teacher Assignments (187)
7	LMS / Lumos	Categories (8), Courses (59), Enrollments (200), Lessons, Library (90 books, 99 borrows)
8	Assignments	Assignments (188), Submissions (13,371)
9	Announcements & Events	Temporal spread, MENA calendar Sep 2025 – Jun 2026
10	Exams, QBank & Grades	Exams (~200), exam results, QBank (~950 Arabic), grading config, gradebook `Result` rows derived from graded submissions, report cards + per-subject grades via the production aggregation
11	Finance	Chart of accounts (2-year), Fee Structures (8), Assignments (~1,940), Payments (~500), Invoices (10), Expense Receipts (10), Payroll
12	Banking	3 accounts, 100 transactions (Oct–Dec 2025)
13	Operations	Attendance (~60,000), Excuses + Interventions, Timetable (~1,500), Gamification (~350)
14	Communications	Conversations (~50, 300 messages), Notifications (~500)
15	Admission	Campaigns + Applications (~50)
16	Compliance & Wellness	Audit Logs (~500), Health/Disciplinary/Achievements (~110)

Idempotent upserts

await prisma.subject.upsert({
  where: {
    schoolId_departmentId_subjectName: {
      schoolId,
      departmentId,
      subjectName: "الرياضيات",
    },
  },
  update: { lang: "ar" },
  create: { schoolId, departmentId, subjectName: "الرياضيات", lang: "ar" },
})

Re-runnable. Never duplicates. Safe in CI. For the single-language storage strategy and getText() helper, see Translation.

Troubleshooting

pnpm db:seed:single <name>      # single module
pnpm db:seed:single --list      # available seeds
pnpm db:reset-test-user         # reset user@balqalam.com
pnpm db:reset-test-applicant    # reset applicant@balqalam.com
pnpm prisma migrate reset       # destructive: drop all data (manual only)

Issue	Fix
Deadlock detected	Reduce batch size in `people.ts`
Table does not exist	`pnpm prisma db push`
Unknown field	Check schema, run `prisma generate`
Foreign key constraint	Seeds run in dependency order
Prisma client not found	`pnpm prisma generate`
Can't reach database	Neon auto-suspend; retry once

npx prisma studio opens the data browser.

balqalam

Database Seeds

Quick start

Counts

Accounts

17 phases

Idempotent upserts

Troubleshooting

Production

See also

balqalam

Database Seeds

Quick start

Counts

Accounts

17 phases

Idempotent upserts

Troubleshooting

Production

See also