CICD/docs/db/seed-data.md

Database Seeding Strategy

Status: Implemented
Script Location: scripts/seed.ts
Command: npm run db:seed

---

1. Overview

The seed script is designed to populate the database with a representative set of data that covers all core business scenarios. It serves two purposes:

1. Development: Provides a consistent baseline for developers.
2. Validation: Verifies complex schema relationships (e.g., recursive trees, JSON structures).

2. Seed Data Topology

2.1 Identity & Access Management (IAM)

We strictly follow the RBAC model defined in docs/architecture/001_database_schema_design.md.

• Roles:
  • admin: System Administrator.
  • teacher: Academic Instructor.
  • student: Learner.
  • grade_head: Head of Grade Year (Demonstrates multi-role capability).
• Users:
  • admin@next-edu.com (Role: Admin)
  • math@next-edu.com (Role: Teacher + Grade Head)
  • alice@next-edu.com (Role: Student)

2.2 Knowledge Graph

Generates a hierarchical structure to test recursive queries (parentId).

• Math (Level 0)
  • └── Algebra (Level 1)
    • └── Linear Equations (Level 2)

2.3 Question Bank

Includes rich content and nested structures.

1. Simple Single Choice: "What is 2 + 2?"
2. Composite Question (Reading Comprehension):
   • Parent: A reading passage.
   • Child 1: Single Choice question about the passage.
   • Child 2: Open-ended text question.

2.4 Exams

Demonstrates the new JSON Structure field (exams.structure).

• Title: "Algebra Mid-Term 2025"
• Structure:

  [
    {
      "type": "group",
      "title": "Part 1: Basics",
      "children": [{ "type": "question", "questionId": "...", "score": 10 }]
    },
    {
      "type": "group",
      "title": "Part 2: Reading",
      "children": [{ "type": "question", "questionId": "...", "score": 20 }]
    }
  ]
  

2.5 Classes / Enrollment / Schedule

Seeds the teacher class management domain.

• Classes: Creates at least one class owned by a teacher user.
• Enrollments: Links students to classes via class_enrollments (default status: active).
• Schedule: Populates class_schedule with weekday + start/end times for timetable validation.

3. How to Run

Prerequisites

Ensure your .env file contains a valid DATABASE_URL.

Execution

Run the following command in the project root:

npm run db:seed

Reset Behavior

WARNING: The script currently performs a TRUNCATE on all core tables before seeding. This ensures a clean state but will WIPE EXISTING DATA.