@studious-lms/server 1.4.9 → 1.5.0

package/prisma/schema.prisma

@@ -15,8 +15,8 @@ generator client {
 // }
 
 datasource db {
-  provider = "postgresql"
-  url      = env("DATABASE_URL")
+  provider  = "postgresql"
+  url       = env("DATABASE_URL")
   directUrl = env("DIRECT_URL")
 }
 
@@ -47,10 +47,20 @@ enum UploadStatus {
   CANCELLED
 }
 
-enum GenerationStatus {
+/// UI-shaped status shared by every domain row that has an async/AI lifecycle
+/// the user can observe (chat messages, AI grading, etc.).
+///
+/// Not every row uses every value — e.g. a Message never goes to NOT_STARTED
+/// (the row doesn't exist until the message is sent) or CANCELLED (the app
+/// doesn't cancel chat replies mid-flight). The full set lives here so a
+/// single enum can serve every UI surface.
+///
+/// For the queue-internal lifecycle (PENDING / RUNNING / SUCCEEDED) see
+/// RunJobStatus — those names matter operationally and shouldn't be mixed
+/// in here.
+enum JobStatus {
   NOT_STARTED
   PENDING
-  GENERATING
   COMPLETED
   FAILED
   CANCELLED
@@ -101,15 +111,14 @@ enum SchoolInviteStatus {
 }
 
 model School {
-  id          String      @id @default(uuid())
-  name        String
-  logo        File?       @relation(references: [id], fields: [logoId])
-  logoId      String?
-  subdomain   String?     @unique
-  createdAt   DateTime    @default(now())
-  updatedAt   DateTime    @updatedAt
-  
-  
+  id        String   @id @default(uuid())
+  name      String
+  logo      File?    @relation(references: [id], fields: [logoId])
+  logoId    String?
+  subdomain String?  @unique
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
   users       User[]
   memberships SchoolMembership[]
   invites     SchoolInvite[]
@@ -117,46 +126,45 @@ model School {
 }
 
 model User {
-  id           String      @id @default(uuid())
-  username     String
-  email        String
-  password     String
-  profile      UserProfile?
-  verified     Boolean     @default(false)
-  role         UserRole    @default(NONE)
-
-  teacherIn   Class[] @relation("UserTeacherToClass")
-  studentIn   Class[] @relation("UserStudentToClass")
-
-  submissions Submission[]
-  sessions    Session[]
-  files       File[]
-  assignments Assignment[]
-  specificAssignments Assignment[] @relation("SpecificAssignmentAssignedTo")
-  events      Event[]
-  announcements Announcement[]
-  notificationsSent Notification[] @relation("SentNotifications")
-  notificationsReceived Notification[] @relation("ReceivedNotifications")
-  studentQuestionProgress StudentQuestionProgress[]
+  id       String       @id @default(uuid())
+  username String
+  email    String
+  password String
+  profile  UserProfile?
+  verified Boolean      @default(false)
+  role     UserRole     @default(NONE)
+
+  teacherIn Class[] @relation("UserTeacherToClass")
+  studentIn Class[] @relation("UserStudentToClass")
+
+  submissions               Submission[]
+  sessions                  Session[]
+  files                     File[]
+  assignments               Assignment[]
+  specificAssignments       Assignment[]               @relation("SpecificAssignmentAssignedTo")
+  events                    Event[]
+  announcements             Announcement[]
+  notificationsSent         Notification[]             @relation("SentNotifications")
+  notificationsReceived     Notification[]             @relation("ReceivedNotifications")
+  studentQuestionProgress   StudentQuestionProgress[]
   studentWorksheetResponses StudentWorksheetResponse[]
 
-  presentAttendance  Attendance[] @relation("PresentAttendance")
+  presentAttendance Attendance[] @relation("PresentAttendance")
   lateAttendance    Attendance[] @relation("LateAttendance")
   absentAttendance  Attendance[] @relation("AbsentAttendance")
 
-  school School? @relation(fields: [schoolId], references: [id])
-  schoolId String?
+  school            School?            @relation(fields: [schoolId], references: [id])
+  schoolId          String?
   schoolMemberships SchoolMembership[]
-  sentSchoolInvites SchoolInvite[] @relation("SchoolInviteInvitedBy")
+  sentSchoolInvites SchoolInvite[]     @relation("SchoolInviteInvitedBy")
 
   // Chat relations
   conversationMemberships ConversationMember[]
-  sentMessages Message[] @relation("SentMessages")
-  mentions Mention[] @relation("UserMentions")
-  createdLabChats LabChat[] @relation("CreatedLabChats")
-  comments Comment[]
-  reactions Reaction[]
-
+  sentMessages            Message[]            @relation("SentMessages")
+  mentions                Mention[]            @relation("UserMentions")
+  createdLabChats         LabChat[]            @relation("CreatedLabChats")
+  comments                Comment[]
+  reactions               Reaction[]
 }
 
 model SchoolMembership {
@@ -178,230 +186,227 @@ model SchoolMembership {
 }
 
 model SchoolInvite {
-  id          String               @id @default(uuid())
-  token       String               @unique
-  email       String
-  role        SchoolMembershipRole
-  status      SchoolInviteStatus   @default(PENDING)
-  expiresAt   DateTime
-  acceptedAt  DateTime?
-  revokedAt   DateTime?
-  createdAt   DateTime             @default(now())
-  updatedAt   DateTime             @updatedAt
+  id         String               @id @default(uuid())
+  token      String               @unique
+  email      String
+  role       SchoolMembershipRole
+  status     SchoolInviteStatus   @default(PENDING)
+  expiresAt  DateTime
+  acceptedAt DateTime?
+  revokedAt  DateTime?
+  createdAt  DateTime             @default(now())
+  updatedAt  DateTime             @updatedAt
 
   schoolId    String
-  school      School               @relation(fields: [schoolId], references: [id], onDelete: Cascade)
+  school      School @relation(fields: [schoolId], references: [id], onDelete: Cascade)
   invitedById String
-  invitedBy   User                 @relation("SchoolInviteInvitedBy", fields: [invitedById], references: [id], onDelete: Cascade)
+  invitedBy   User   @relation("SchoolInviteInvitedBy", fields: [invitedById], references: [id], onDelete: Cascade)
 
   @@index([schoolId, status])
   @@index([email])
 }
 
 model UserProfile {
-  id String @id @default(uuid())
+  id     String @id @default(uuid())
   userId String @unique
-  user User? @relation(fields: [userId], references: [id], onDelete: Cascade)
-  
-  displayName String?
-  bio String?
-  location String?
-  website String?
-  profilePicture String?
+  user   User?  @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  displayName             String?
+  bio                     String?
+  location                String?
+  website                 String?
+  profilePicture          String?
   profilePictureThumbnail String?
-  
+
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
-} 
+}
 
 model Class {
-  id            String         @id @default(uuid())
-  name          String
-  subject       String
-  color         String?        @default("#3B82F6")
-  section       String
-  syllabus      String?
-  announcements Announcement[]
-  assignments   Assignment[]
-  attendance    Attendance[]
-  events        Event[]
-  sections      Section[]
-  sessions      Session[]
-  worksheets    Worksheet[]
-  students      User[]         @relation("UserStudentToClass")
-  teachers      User[]         @relation("UserTeacherToClass")
+  id                String            @id @default(uuid())
+  name              String
+  subject           String
+  color             String?           @default("#3B82F6")
+  section           String
+  syllabus          String?
+  announcements     Announcement[]
+  assignments       Assignment[]
+  attendance        Attendance[]
+  events            Event[]
+  sections          Section[]
+  sessions          Session[]
+  worksheets        Worksheet[]
+  students          User[]            @relation("UserStudentToClass")
+  teachers          User[]            @relation("UserTeacherToClass")
   // markSchemes   MarkScheme[] @relation("ClassToMarkScheme")
   // gradingBoundaries GradingBoundary[] @relation("ClassToGradingBoundary")
-  draftFiles File[] @relation("ClassDraftFiles")
-  classFiles Folder? @relation("ClassFiles")
-  labChats LabChat[] @relation("ClassLabChats")
-  markSchemes MarkScheme[]
+  draftFiles        File[]            @relation("ClassDraftFiles")
+  classFiles        Folder?           @relation("ClassFiles")
+  labChats          LabChat[]         @relation("ClassLabChats")
+  markSchemes       MarkScheme[]
   gradingBoundaries GradingBoundary[]
-  school    School? @relation(fields: [schoolId], references: [id])
-  schoolId  String?
+  school            School?           @relation(fields: [schoolId], references: [id])
+  schoolId          String?
 }
 
 model MarkScheme {
-  id String @id @default(uuid())
-  classId String
+  id          String       @id @default(uuid())
+  classId     String
   // class Class[] @relation("ClassToMarkScheme")
-  class Class? @relation(fields: [classId], references: [id], onDelete: Cascade)
-  structured String
+  class       Class?       @relation(fields: [classId], references: [id], onDelete: Cascade)
+  structured  String
   assignments Assignment[]
 }
 
 model GradingBoundary {
-  id String @id @default(uuid())
-  classId String
+  id          String       @id @default(uuid())
+  classId     String
   // class Class[] @relation("ClassToGradingBoundary")
-  class Class? @relation(fields: [classId], references: [id], onDelete: Cascade)
-  structured String
+  class       Class?       @relation(fields: [classId], references: [id], onDelete: Cascade)
+  structured  String
   assignments Assignment[]
 }
 
 model Folder {
-  id String @id @default(uuid())
-  name String
-  files File[] @relation("FolderFiles")
-  childFolders Folder[] @relation("ParentChildFolders")
-  parentFolder Folder? @relation("ParentChildFolders", fields: [parentFolderId], references: [id])
+  id             String   @id @default(uuid())
+  name           String
+  files          File[]   @relation("FolderFiles")
+  childFolders   Folder[] @relation("ParentChildFolders")
+  parentFolder   Folder?  @relation("ParentChildFolders", fields: [parentFolderId], references: [id])
   parentFolderId String?
-  color String? @default("#3B82F6")
-  class Class? @relation("ClassFiles", fields: [classId], references: [id])
-  classId String? @unique
+  color          String?  @default("#3B82F6")
+  class          Class?   @relation("ClassFiles", fields: [classId], references: [id])
+  classId        String?  @unique
 }
 
 model File {
-  id         String @id @default(uuid())
+  id         String    @id @default(uuid())
   name       String
   path       String
   size       Int?
   type       String
-  user       User? @relation(fields: [userId], references: [id])
+  user       User?     @relation(fields: [userId], references: [id])
   userId     String?
   uploadedAt DateTime? @default(now())
 
   // Upload tracking fields
-  uploadStatus UploadStatus @default(PENDING)
-  uploadUrl    String?
-  uploadExpiresAt DateTime?
-  uploadSessionId String?
-  uploadProgress Int?
-  uploadError   String?
-  uploadRetryCount Int @default(0)
-  isOrphaned Boolean @default(false)
-  cleanupAt  DateTime?
+  uploadStatus     UploadStatus @default(PENDING)
+  uploadUrl        String?
+  uploadExpiresAt  DateTime?
+  uploadSessionId  String?
+  uploadProgress   Int?
+  uploadError      String?
+  uploadRetryCount Int          @default(0)
+  isOrphaned       Boolean      @default(false)
+  cleanupAt        DateTime?
 
   // Thumbnail relationship
-  thumbnail   File?  @relation("Thumbnail", fields: [thumbnailId], references: [id])
-  thumbnailId String? @unique
-  originalFile File? @relation("Thumbnail")
+  thumbnail    File?   @relation("Thumbnail", fields: [thumbnailId], references: [id])
+  thumbnailId  String? @unique
+  originalFile File?   @relation("Thumbnail")
 
-  assignment Assignment? @relation(fields: [assignmentId], references: [id], onDelete: Cascade)
+  assignment   Assignment? @relation(fields: [assignmentId], references: [id], onDelete: Cascade)
   assignmentId String?
 
-  submission Submission? @relation("SubmissionFile", fields: [submissionId], references: [id], onDelete: Cascade)
+  submission   Submission? @relation("SubmissionFile", fields: [submissionId], references: [id], onDelete: Cascade)
   submissionId String?
 
-  annotations Submission? @relation("SubmissionAnnotations", fields: [annotationId], references: [id], onDelete: Cascade)
+  annotations  Submission? @relation("SubmissionAnnotations", fields: [annotationId], references: [id], onDelete: Cascade)
   annotationId String?
 
-  classDraft Class? @relation("ClassDraftFiles", fields: [classDraftId], references: [id], onDelete: Cascade)
+  classDraft   Class?  @relation("ClassDraftFiles", fields: [classDraftId], references: [id], onDelete: Cascade)
   classDraftId String?
 
-  folder Folder? @relation("FolderFiles", fields: [folderId], references: [id], onDelete: Cascade)
+  folder   Folder? @relation("FolderFiles", fields: [folderId], references: [id], onDelete: Cascade)
   folderId String?
 
   conversationId String?
 
   messageId String?
-  message Message? @relation("MessageAttachments", fields: [messageId], references: [id], onDelete: Cascade)
+  message   Message? @relation("MessageAttachments", fields: [messageId], references: [id], onDelete: Cascade)
 
-  announcement Announcement? @relation("AnnouncementAttachments", fields: [announcementId], references: [id], onDelete: Cascade)
+  announcement   Announcement? @relation("AnnouncementAttachments", fields: [announcementId], references: [id], onDelete: Cascade)
   announcementId String?
 
-  schools      School[]
+  schools School[]
 
-  schoolDevelopementProgram SchoolDevelopementProgram? @relation("SchoolDevelopementProgramSupportingDocumentation", fields: [schoolDevelopementProgramId], references: [id], onDelete: Cascade)
+  schoolDevelopementProgram   SchoolDevelopementProgram? @relation("SchoolDevelopementProgramSupportingDocumentation", fields: [schoolDevelopementProgramId], references: [id], onDelete: Cascade)
   schoolDevelopementProgramId String?
 }
 
 model Assignment {
-  id            String         @id @default(uuid())
-  title         String
-  instructions  String
-  dueDate       DateTime
-  createdAt     DateTime?      @default(now())
-  modifiedAt    DateTime?      @updatedAt
-  teacher       User           @relation(fields: [teacherId], references: [id], onDelete: NoAction)
-  teacherId     String
-  class         Class          @relation(fields: [classId], references: [id], onDelete: Cascade)
-  classId       String
-  attachments   File[]
-  acceptFiles Boolean @default(false)
-  acceptExtendedResponse Boolean @default(false)
-  acceptWorksheet Boolean @default(false)
-  gradeWithAI Boolean @default(false)
+  id                     String    @id @default(uuid())
+  title                  String
+  instructions           String
+  dueDate                DateTime
+  createdAt              DateTime? @default(now())
+  modifiedAt             DateTime? @updatedAt
+  teacher                User      @relation(fields: [teacherId], references: [id], onDelete: NoAction)
+  teacherId              String
+  class                  Class     @relation(fields: [classId], references: [id], onDelete: Cascade)
+  classId                String
+  attachments            File[]
+  acceptFiles            Boolean   @default(false)
+  acceptExtendedResponse Boolean   @default(false)
+  acceptWorksheet        Boolean   @default(false)
+  gradeWithAI            Boolean   @default(false)
 
   aiPolicyLevel Int @default(0)
 
-  submissions   Submission[]
-  comments      Comment[] @relation("AssignmentComments")
-  assignedTo    User[] @relation("SpecificAssignmentAssignedTo")
-  section       Section?       @relation(fields: [sectionId], references: [id], onDelete: Cascade)
-  sectionId     String?
-  graded        Boolean        @default(false)
-  maxGrade      Int?          @default(0)
-  weight        Float         @default(1)
-  type          AssignmentType @default(HOMEWORK)
-  inProgress    Boolean        @default(false)
-  template      Boolean        @default(false)
-  eventAttached Event?        @relation(fields: [eventId], references: [id], onDelete: NoAction)
-  eventId       String?
-  markScheme    MarkScheme? @relation(fields: [markSchemeId], references: [id], onDelete: Cascade)
-  markSchemeId  String?
-  order         Int?
-  gradingBoundary GradingBoundary? @relation(fields: [gradingBoundaryId], references: [id], onDelete: Cascade)
-  gradingBoundaryId String?
-  worksheets Worksheet[] @relation("AssignmentWorksheets")
-  targetedBySubmissions Submission[] @relation("SubmissionTargetedAssignment")
+  submissions           Submission[]
+  comments              Comment[]        @relation("AssignmentComments")
+  assignedTo            User[]           @relation("SpecificAssignmentAssignedTo")
+  section               Section?         @relation(fields: [sectionId], references: [id], onDelete: Cascade)
+  sectionId             String?
+  graded                Boolean          @default(false)
+  maxGrade              Int?             @default(0)
+  weight                Float            @default(1)
+  type                  AssignmentType   @default(HOMEWORK)
+  inProgress            Boolean          @default(false)
+  template              Boolean          @default(false)
+  eventAttached         Event?           @relation(fields: [eventId], references: [id], onDelete: NoAction)
+  eventId               String?
+  markScheme            MarkScheme?      @relation(fields: [markSchemeId], references: [id], onDelete: Cascade)
+  markSchemeId          String?
+  order                 Int?
+  gradingBoundary       GradingBoundary? @relation(fields: [gradingBoundaryId], references: [id], onDelete: Cascade)
+  gradingBoundaryId     String?
+  worksheets            Worksheet[]      @relation("AssignmentWorksheets")
+  targetedBySubmissions Submission[]     @relation("SubmissionTargetedAssignment")
 }
 
-
-
 model Announcement {
-  id      String @id @default(uuid())
-  remarks String
-  teacher User @relation(fields: [teacherId], references: [id])
-  teacherId String
-  createdAt DateTime @default(now())
-  modifiedAt DateTime? @updatedAt
-  class   Class @relation(fields: [classId], references: [id], onDelete: Cascade)
-  classId String
-  attachments File[] @relation("AnnouncementAttachments")
-  comments Comment[]
-  reactions Reaction[]
+  id          String     @id @default(uuid())
+  remarks     String
+  teacher     User       @relation(fields: [teacherId], references: [id])
+  teacherId   String
+  createdAt   DateTime   @default(now())
+  modifiedAt  DateTime?  @updatedAt
+  class       Class      @relation(fields: [classId], references: [id], onDelete: Cascade)
+  classId     String
+  attachments File[]     @relation("AnnouncementAttachments")
+  comments    Comment[]
+  reactions   Reaction[]
 }
 
 model Comment {
-  id            String @id @default(uuid())
-  content       String
-  author        User @relation(fields: [authorId], references: [id], onDelete: Cascade)
-  authorId      String
-  announcement  Announcement? @relation(fields: [announcementId], references: [id], onDelete: Cascade)
-  announcementId String?
-  assignment    Assignment? @relation("AssignmentComments", fields: [assignmentId], references: [id], onDelete: Cascade)
-  assignmentId  String?
-  submission    Submission? @relation("SubmissionComments", fields: [submissionId], references: [id], onDelete: Cascade)
-  submissionId  String?
-  parentComment Comment? @relation("CommentReplies", fields: [parentCommentId], references: [id], onDelete: Cascade)
-  parentCommentId String?
-  status GenerationStatus?
-  replies       Comment[] @relation("CommentReplies")
-  reactions     Reaction[]
-  createdAt     DateTime @default(now())
-  modifiedAt    DateTime? @updatedAt
-  studentQuestionProgress StudentQuestionProgress? @relation("StudentQuestionProgressComments", fields: [studentQuestionProgressId], references: [id], onDelete: Cascade)
+  id                        String                   @id @default(uuid())
+  content                   String
+  author                    User                     @relation(fields: [authorId], references: [id], onDelete: Cascade)
+  authorId                  String
+  announcement              Announcement?            @relation(fields: [announcementId], references: [id], onDelete: Cascade)
+  announcementId            String?
+  assignment                Assignment?              @relation("AssignmentComments", fields: [assignmentId], references: [id], onDelete: Cascade)
+  assignmentId              String?
+  submission                Submission?              @relation("SubmissionComments", fields: [submissionId], references: [id], onDelete: Cascade)
+  submissionId              String?
+  parentComment             Comment?                 @relation("CommentReplies", fields: [parentCommentId], references: [id], onDelete: Cascade)
+  parentCommentId           String?
+  replies                   Comment[]                @relation("CommentReplies")
+  reactions                 Reaction[]
+  createdAt                 DateTime                 @default(now())
+  modifiedAt                DateTime?                @updatedAt
+  studentQuestionProgress   StudentQuestionProgress? @relation("StudentQuestionProgressComments", fields: [studentQuestionProgressId], references: [id], onDelete: Cascade)
   studentQuestionProgressId String?
 
   @@index([assignmentId])
@@ -409,16 +414,16 @@ model Comment {
 }
 
 model Reaction {
-  id            String @id @default(uuid())
-  type          ReactionType
-  user          User @relation(fields: [userId], references: [id], onDelete: Cascade)
-  userId        String
-  announcement  Announcement? @relation(fields: [announcementId], references: [id], onDelete: Cascade)
+  id             String        @id @default(uuid())
+  type           ReactionType
+  user           User          @relation(fields: [userId], references: [id], onDelete: Cascade)
+  userId         String
+  announcement   Announcement? @relation(fields: [announcementId], references: [id], onDelete: Cascade)
   announcementId String?
-  comment       Comment? @relation(fields: [commentId], references: [id], onDelete: Cascade)
-  commentId     String?
-  createdAt     DateTime @default(now())
-  
+  comment        Comment?      @relation(fields: [commentId], references: [id], onDelete: Cascade)
+  commentId      String?
+  createdAt      DateTime      @default(now())
+
   @@unique([userId, announcementId])
   @@unique([userId, commentId])
   @@index([announcementId])
@@ -426,57 +431,57 @@ model Reaction {
 }
 
 model Submission {
-  id      String @id @default(uuid())
-  createdAt DateTime @default(now())
+  id         String   @id @default(uuid())
+  createdAt  DateTime @default(now())
   modifiedAt DateTime @default(now())
 
-  assignment Assignment @relation(fields: [assignmentId], references: [id], onDelete: Cascade)
+  assignment   Assignment @relation(fields: [assignmentId], references: [id], onDelete: Cascade)
   assignmentId String
 
-  student User @relation(fields: [studentId], references: [id])
+  student   User   @relation(fields: [studentId], references: [id])
   studentId String
 
-  attachments File[]  @relation("SubmissionFile")
-  annotations File[]  @relation("SubmissionAnnotations")
-  comments Comment[] @relation("SubmissionComments")
-  worksheetResponses StudentWorksheetResponse[]
-  extendedResponse String?
-  gradeReceived Int?
-  recommendationState SubmissionRecommendationState @default(NONE)
+  attachments             File[]                        @relation("SubmissionFile")
+  annotations             File[]                        @relation("SubmissionAnnotations")
+  comments                Comment[]                     @relation("SubmissionComments")
+  worksheetResponses      StudentWorksheetResponse[]
+  extendedResponse        String?
+  gradeReceived           Int?
+  recommendationState     SubmissionRecommendationState @default(NONE)
   recommendationUpdatedAt DateTime?
-  targetedAssignmentId String?
-  targetedAssignment Assignment? @relation("SubmissionTargetedAssignment", fields: [targetedAssignmentId], references: [id], onDelete: SetNull)
+  targetedAssignmentId    String?
+  targetedAssignment      Assignment?                   @relation("SubmissionTargetedAssignment", fields: [targetedAssignmentId], references: [id], onDelete: SetNull)
 
-  rubricState String?
+  rubricState     String?
   teacherComments String?
 
-  submittedAt DateTime?
-  submitted   Boolean? @default(false)
-  returned    Boolean? @default(false)
+  submittedAt  DateTime?
+  submitted    Boolean?     @default(false)
+  returned     Boolean?     @default(false)
   newtonTutors NewtonChat[]
 
   @@index([studentId, recommendationState])
 }
 
 model NewtonChat {
-  id String @id @default(uuid())
-  submissionId String
-  submission Submission @relation(fields: [submissionId], references: [id], onDelete: Cascade)
-  conversationId String @unique
-  conversation Conversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-  title String @default("Session with Newton Tutor")
+  id             String       @id @default(uuid())
+  submissionId   String
+  submission     Submission   @relation(fields: [submissionId], references: [id], onDelete: Cascade)
+  conversationId String       @unique
+  conversation   Conversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
+  createdAt      DateTime     @default(now())
+  updatedAt      DateTime     @updatedAt
+  title          String       @default("Session with Newton Tutor")
 }
 
 model Section {
-  id        String @id @default(uuid())
-  name      String
-  classId   String
-  class     Class @relation(fields: [classId], references: [id], onDelete: Cascade)
+  id          String       @id @default(uuid())
+  name        String
+  classId     String
+  class       Class        @relation(fields: [classId], references: [id], onDelete: Cascade)
   assignments Assignment[]
-  color String? @default("#3B82F6")
-  order Int?
+  color       String?      @default("#3B82F6")
+  order       Int?
 }
 
 enum SessionType {
@@ -487,57 +492,57 @@ enum SessionType {
 }
 
 model Session {
-  id        String @id @default(uuid())
-  createdAt DateTime? @default(now())
+  id        String      @id @default(uuid())
+  createdAt DateTime?   @default(now())
   expiresAt DateTime?
   type      SessionType @default(AUTH)
   userId    String?
-  user      User? @relation(fields: [userId], references: [id], onDelete: NoAction)
+  user      User?       @relation(fields: [userId], references: [id], onDelete: NoAction)
   classId   String?
-  class     Class? @relation(fields: [classId], references: [id], onDelete: Cascade)
+  class     Class?      @relation(fields: [classId], references: [id], onDelete: Cascade)
 }
 
 model Event {
-  id        String @id @default(uuid())
-  name      String?
-  startTime DateTime
-  endTime   DateTime
-  location  String?
-  remarks   String?
-  userId    String?
-  user      User? @relation(fields: [userId], references: [id], onDelete: Cascade)
-  classId   String?
-  class     Class? @relation(fields: [classId], references: [id], onDelete: Cascade)
-  color         String? @default("#3B82F6")
+  id                  String       @id @default(uuid())
+  name                String?
+  startTime           DateTime
+  endTime             DateTime
+  location            String?
+  remarks             String?
+  userId              String?
+  user                User?        @relation(fields: [userId], references: [id], onDelete: Cascade)
+  classId             String?
+  class               Class?       @relation(fields: [classId], references: [id], onDelete: Cascade)
+  color               String?      @default("#3B82F6")
   assignmentsAttached Assignment[]
-  attendance Attendance[]
+  attendance          Attendance[]
 }
 
 model Attendance {
-  id        String   @id @default(uuid())
-  date      DateTime @default(now())
-  
-  class     Class    @relation(fields: [classId], references: [id], onDelete: Cascade)
-  classId   String
+  id   String   @id @default(uuid())
+  date DateTime @default(now())
+
+  class   Class  @relation(fields: [classId], references: [id], onDelete: Cascade)
+  classId String
 
-  event     Event?   @relation(fields: [eventId], references: [id], onDelete: Cascade)
-  eventId   String?
+  event   Event?  @relation(fields: [eventId], references: [id], onDelete: Cascade)
+  eventId String?
 
-  present   User[]   @relation("PresentAttendance")
-  late      User[]   @relation("LateAttendance")
-  absent    User[]   @relation("AbsentAttendance")
+  present User[] @relation("PresentAttendance")
+  late    User[] @relation("LateAttendance")
+  absent  User[] @relation("AbsentAttendance")
 }
 
 model Notification {
-  id String @id @default(uuid())
-  title String
-  content String
-  createdAt DateTime @default(now())
-  senderId String? // no ID means sys
+  id         String   @id @default(uuid())
+  title      String
+  content    String
+  createdAt  DateTime @default(now())
+  senderId   String? // no ID means sys
   receiverId String
-  read Boolean @default(false)
-  sender User? @relation("SentNotifications", fields: [senderId], references: [id])
-  receiver User @relation("ReceivedNotifications", fields: [receiverId], references: [id], onDelete: Cascade)
+  read       Boolean  @default(false)
+  sender     User?    @relation("SentNotifications", fields: [senderId], references: [id])
+  receiver   User     @relation("ReceivedNotifications", fields: [receiverId], references: [id], onDelete: Cascade)
 }
 
 enum ConversationType {
@@ -551,179 +556,201 @@ enum ConversationRole {
 }
 
 model Conversation {
-  id String @id @default(uuid())
-  type ConversationType
-  name String?
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
+  id        String           @id @default(uuid())
+  type      ConversationType
+  name      String?
+  createdAt DateTime         @default(now())
+  updatedAt DateTime         @updatedAt
 
   displayInChat Boolean @default(true)
-  
-  members ConversationMember[]
-  messages Message[]
-  labChat LabChat?
+
+  members    ConversationMember[]
+  messages   Message[]
+  labChat    LabChat?
   newtonChat NewtonChat?
 }
 
 model LabChat {
-  id String @id @default(uuid())
-  title String
-  context String // JSON string for LLM context
-  classId String
-  conversationId String @unique
-  createdById String // Teacher who created the lab
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-  class Class @relation("ClassLabChats", fields: [classId], references: [id], onDelete: Cascade)
-  conversation Conversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
-  createdBy User @relation("CreatedLabChats", fields: [createdById], references: [id], onDelete: NoAction)
+  id             String       @id @default(uuid())
+  title          String
+  context        String // JSON string for LLM context
+  classId        String
+  conversationId String       @unique
+  createdById    String // Teacher who created the lab
+  createdAt      DateTime     @default(now())
+  updatedAt      DateTime     @updatedAt
+  class          Class        @relation("ClassLabChats", fields: [classId], references: [id], onDelete: Cascade)
+  conversation   Conversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
+  createdBy      User         @relation("CreatedLabChats", fields: [createdById], references: [id], onDelete: NoAction)
 }
 
 model ConversationMember {
-  id String @id @default(uuid())
-  userId String
-  conversationId String
-  role ConversationRole @default(MEMBER)
-  joinedAt DateTime @default(now())
-  hiddenAt DateTime? // When user last hid this conversation from their list
-  lastViewedAt DateTime? // When user last viewed this conversation
+  id                  String           @id @default(uuid())
+  userId              String
+  conversationId      String
+  role                ConversationRole @default(MEMBER)
+  joinedAt            DateTime         @default(now())
+  hiddenAt            DateTime? // When user last hid this conversation from their list
+  lastViewedAt        DateTime? // When user last viewed this conversation
   lastViewedMentionAt DateTime? // When user last viewed mentions in this conversation
-  
-  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  user         User         @relation(fields: [userId], references: [id], onDelete: Cascade)
   conversation Conversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
-  
+
   @@unique([userId, conversationId])
 }
 
 model Message {
-  id String @id @default(uuid())
-  content String
-  senderId String
+  id             String       @id @default(uuid())
+  content        String
+  senderId       String
   conversationId String
-  createdAt DateTime @default(now())
-  status GenerationStatus? @default(NOT_STARTED)
-  sender User @relation("SentMessages", fields: [senderId], references: [id], onDelete: Cascade)
-  conversation Conversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
-  mentions Mention[]
-  attachments File[] @relation("MessageAttachments")
+  createdAt      DateTime     @default(now())
+  /// UI-shaped status. NULL for messages with no AI lifecycle (normal user DMs).
+  /// Operational/queue state (retries, errors, attempts) lives on `runJob`.
+  status         JobStatus?
+  /// Link to the background job that's generating / generated the AI response
+  /// for this message. NULL for non-AI messages.
+  runJobId       String?
+  runJob         RunJob?      @relation("MessageRunJob", fields: [runJobId], references: [id], onDelete: SetNull)
+  sender         User         @relation("SentMessages", fields: [senderId], references: [id], onDelete: Cascade)
+  conversation   Conversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
+  mentions       Mention[]
+  attachments    File[]       @relation("MessageAttachments")
 
   meta Json? @default("{}")
+
+  @@index([runJobId])
 }
 
 model AiUsageLog {
-  id                  String   @id @default(uuid())
-  reason              String
-  provider            String   @default("openai")
-  model               String
-  operation           String
-  success             Boolean  @default(true)
-  promptTokens        Int?
-  completionTokens    Int?
-  totalTokens         Int?
+  id                   String   @id @default(uuid())
+  reason               String
+  provider             String   @default("openai")
+  model                String
+  operation            String
+  success              Boolean  @default(true)
+  promptTokens         Int?
+  completionTokens     Int?
+  totalTokens          Int?
   estimatedInputTokens Int?
-  metadata            Json?    @default("{}")
-  error               String?
-  createdAt           DateTime @default(now())
+  metadata             Json?    @default("{}")
+  error                String?
+  createdAt            DateTime @default(now())
 
   @@index([reason, createdAt])
 }
 
 model Mention {
-  id String @id @default(uuid())
+  id        String   @id @default(uuid())
   messageId String
-  userId String
+  userId    String
   createdAt DateTime @default(now())
-  
+
   message Message @relation(fields: [messageId], references: [id], onDelete: Cascade)
-  user User @relation("UserMentions", fields: [userId], references: [id], onDelete: Cascade)
-  
+  user    User    @relation("UserMentions", fields: [userId], references: [id], onDelete: Cascade)
+
   @@unique([messageId, userId])
 }
 
 model Worksheet {
-  id String @id @default(uuid())
-  name String
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-  classId String
-  class Class? @relation(fields: [classId], references: [id], onDelete: Cascade)
-  assignments Assignment[] @relation("AssignmentWorksheets")
-  questions WorksheetQuestion[]
+  id                        String                     @id @default(uuid())
+  name                      String
+  sourceUrl                 String?
+  createdAt                 DateTime                   @default(now())
+  updatedAt                 DateTime                   @updatedAt
+  classId                   String
+  class                     Class?                     @relation(fields: [classId], references: [id], onDelete: Cascade)
+  assignments               Assignment[]               @relation("AssignmentWorksheets")
+  questions                 WorksheetQuestion[]
   studentWorksheetResponses StudentWorksheetResponse[]
+
+  runJobId                  String?
+  runJob                    RunJob?                    @relation("WorksheetRunJob", fields: [runJobId], references: [id], onDelete: SetNull)
+
+  status                    JobStatus?                 @default(NOT_STARTED)
+
+  @@unique([classId, sourceUrl])
 }
 
 model WorksheetQuestion {
-  id String @id @default(uuid())
-  worksheetId String
-  worksheet Worksheet @relation(fields: [worksheetId], references: [id], onDelete: Cascade)
-  type WorksheetQuestionType
-  question String
-  answer String
-  options Json?  @default("{}")
-  markScheme Json?  @default("{}")
-  points Int @default(0)
-  order Int? @default(0)
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
+  id               String                    @id @default(uuid())
+  worksheetId      String
+  worksheet        Worksheet                 @relation(fields: [worksheetId], references: [id], onDelete: Cascade)
+  type             WorksheetQuestionType
+  question         String
+  answer           String
+  options          Json?                     @default("{}")
+  markScheme       Json?                     @default("{}")
+  points           Int                       @default(0)
+  order            Int?                      @default(0)
+  createdAt        DateTime                  @default(now())
+  updatedAt        DateTime                  @updatedAt
   studentResponses StudentQuestionProgress[]
 }
 
 model StudentWorksheetResponse {
-  id String @id @default(uuid())
-  studentId String
-  student User @relation(fields: [studentId], references: [id], onDelete: Cascade)
-  worksheetId String
-  worksheet Worksheet @relation(fields: [worksheetId], references: [id], onDelete: Cascade)
-  responses StudentQuestionProgress[]
-  submission Submission? @relation(fields: [submissionId], references: [id], onDelete: Cascade)
+  id           String                    @id @default(uuid())
+  studentId    String
+  student      User                      @relation(fields: [studentId], references: [id], onDelete: Cascade)
+  worksheetId  String
+  worksheet    Worksheet                 @relation(fields: [worksheetId], references: [id], onDelete: Cascade)
+  responses    StudentQuestionProgress[]
+  submission   Submission?               @relation(fields: [submissionId], references: [id], onDelete: Cascade)
   submissionId String?
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-  submittedAt DateTime?
-  submitted Boolean @default(false)
+  createdAt    DateTime                  @default(now())
+  updatedAt    DateTime                  @updatedAt
+  submittedAt  DateTime?
+  submitted    Boolean                   @default(false)
 }
 
 model StudentQuestionProgress {
-  id String @id @default(uuid())
-  studentId String
-  student User @relation(fields: [studentId], references: [id], onDelete: Cascade)
-  questionId String
-  question WorksheetQuestion @relation(fields: [questionId], references: [id], onDelete: Cascade)
-  response String
-  isCorrect Boolean @default(false)
-  markschemeState Json? @default("{}")
-  points Int @default(0)
-  comments Comment[] @relation("StudentQuestionProgressComments")
-  feedback String?
-  createdAt DateTime @default(now())
-  updatedAt DateTime? @updatedAt
+  id                         String                    @id @default(uuid())
+  studentId                  String
+  student                    User                      @relation(fields: [studentId], references: [id], onDelete: Cascade)
+  questionId                 String
+  question                   WorksheetQuestion         @relation(fields: [questionId], references: [id], onDelete: Cascade)
+  response                   String
+  isCorrect                  Boolean                   @default(false)
+  markschemeState            Json?                     @default("{}")
+  points                     Int                       @default(0)
+  comments                   Comment[]                 @relation("StudentQuestionProgressComments")
+  feedback                   String?
+  createdAt                  DateTime                  @default(now())
+  updatedAt                  DateTime?                 @updatedAt
   studentWorksheetResponseId String?
-  studentWorksheetResponse StudentWorksheetResponse? @relation(fields: [studentWorksheetResponseId], references: [id], onDelete: Cascade)
-  status GenerationStatus? @default(NOT_STARTED)
-  
+  studentWorksheetResponse   StudentWorksheetResponse? @relation(fields: [studentWorksheetResponseId], references: [id], onDelete: Cascade)
+  /// UI-shaped grading lifecycle. Operational/queue state lives on `runJob`.
+  status                     JobStatus?                @default(NOT_STARTED)
+  /// Link to the auto-grading background job. NULL when no auto-grading
+  /// has ever been attempted for this question.
+  runJobId                   String?
+  runJob                     RunJob?                   @relation("StudentQuestionProgressRunJob", fields: [runJobId], references: [id], onDelete: SetNull)
+
   @@index([studentId, questionId])
+  @@index([runJobId])
 }
 
 model SchoolDevelopementProgram {
-  id String @id
-  name String
-  type String
-  address String
-  city String
-  country String
+  id               String  @id
+  name             String
+  type             String
+  address          String
+  city             String
+  country          String
   numberOfStudents Int
   numberOfTeachers Int
-  website String?
+  website          String?
 
-  contactName String?
-  contactRole String?
-  contactEmail String?
-  contactPhone String? @default("")
+  contactName            String?
+  contactRole            String?
+  contactEmail           String?
+  contactPhone           String?   @default("")
   eligibilityInformation String?
-  whyHelp String?
-  additionalInformation String?
-  submittedAt DateTime? @default(now())
-  reviewedAt DateTime?
+  whyHelp                String?
+  additionalInformation  String?
+  submittedAt            DateTime? @default(now())
+  reviewedAt             DateTime?
 
   status String @default("NOT_STARTED") // NOT_STARTED, PENDING, APPROVED, REJECTED, REFERRED
 
@@ -731,8 +758,59 @@ model SchoolDevelopementProgram {
 }
 
 model EarlyAccessRequest {
-  id String @id @default(uuid())
-  email String
-  createdAt DateTime @default(now())
+  id              String   @id @default(uuid())
+  email           String
+  createdAt       DateTime @default(now())
   institutionSize String
 }
+
+enum RunJobType {
+  PDF_TO_WORKSHEET
+  GRADE_WORKSHEET
+  AI_LAB_CHAT
+  AI_NEWTON_CHAT
+  STUDENT_PROGRESS_CHAT
+}
+
+enum RunJobStatus {
+  PENDING
+  RUNNING
+  SUCCEEDED
+  FAILED
+  CANCELLED
+}
+
+/// App-level audit/status record for background jobs.
+/// BullMQ owns queue state in Redis (retries, scheduling, in-flight execution);
+/// this table is the durable, queryable record of who started what and how it ended.
+model RunJob {
+  id     String       @id @default(uuid())
+  type   RunJobType
+  status RunJobStatus @default(PENDING)
+
+  classId String?
+  userId  String?
+
+  /// BullMQ job id, set after enqueue. Null if enqueue failed before the queue accepted it.
+  bullJobId String?
+
+  input    Json
+  result   Json?
+  error    String?
+  attempts Int     @default(0)
+
+  startedAt  DateTime?
+  finishedAt DateTime?
+  createdAt  DateTime  @default(now())
+  updatedAt  DateTime  @updatedAt
+
+  /// Domain rows produced or driven by this job. Each relation is optional —
+  /// most jobs touch zero or one of these.
+  messages                  Message[]                 @relation("MessageRunJob")
+  studentQuestionProgresses StudentQuestionProgress[] @relation("StudentQuestionProgressRunJob")
+  worksheet                 Worksheet[]                @relation("WorksheetRunJob")
+
+  @@index([userId, type, status])
+  @@index([classId, status])
+  @@index([status, createdAt])
+}