feat: add new critical API documentation for notifications, dashboard widgets, signage, and exam sessions

Co-authored-by: cetinmustafa83 <30570791+cetinmustafa83@users.noreply.github.com>

prisma/migrations/20260731135508_add_module_j_widgets/migration.sql

@@ -0,0 +1,73 @@
+-- CreateTable
+CREATE TABLE "dashboard_widgets" (
+    "id" TEXT NOT NULL PRIMARY KEY,
+    "schoolId" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "widgetType" TEXT NOT NULL,
+    "title" TEXT,
+    "position" INTEGER NOT NULL,
+    "size" TEXT NOT NULL DEFAULT 'medium',
+    "isVisible" BOOLEAN NOT NULL DEFAULT true,
+    "config" TEXT,
+    "dataSource" TEXT,
+    "refreshInterval" INTEGER NOT NULL DEFAULT 300,
+    "lastRefresh" DATETIME,
+    "cacheData" TEXT,
+    "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" DATETIME NOT NULL,
+    CONSTRAINT "dashboard_widgets_schoolId_fkey" FOREIGN KEY ("schoolId") REFERENCES "School" ("id") ON DELETE RESTRICT ON UPDATE CASCADE,
+    CONSTRAINT "dashboard_widgets_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User" ("id") ON DELETE RESTRICT ON UPDATE CASCADE
+);
+
+-- CreateTable
+CREATE TABLE "dashboard_layouts" (
+    "id" TEXT NOT NULL PRIMARY KEY,
+    "schoolId" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "gridColumns" INTEGER NOT NULL DEFAULT 4,
+    "isDefault" BOOLEAN NOT NULL DEFAULT false,
+    "widgets" TEXT NOT NULL,
+    "theme" TEXT,
+    "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" DATETIME NOT NULL,
+    CONSTRAINT "dashboard_layouts_schoolId_fkey" FOREIGN KEY ("schoolId") REFERENCES "School" ("id") ON DELETE RESTRICT ON UPDATE CASCADE,
+    CONSTRAINT "dashboard_layouts_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User" ("id") ON DELETE RESTRICT ON UPDATE CASCADE
+);
+
+-- CreateTable
+CREATE TABLE "widget_templates" (
+    "id" TEXT NOT NULL PRIMARY KEY,
+    "schoolId" TEXT NOT NULL,
+    "widgetType" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "description" TEXT,
+    "defaultConfig" TEXT NOT NULL,
+    "thumbnail" TEXT,
+    "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT "widget_templates_schoolId_fkey" FOREIGN KEY ("schoolId") REFERENCES "School" ("id") ON DELETE RESTRICT ON UPDATE CASCADE
+);
+
+-- CreateIndex
+CREATE INDEX "dashboard_widgets_schoolId_idx" ON "dashboard_widgets"("schoolId");
+
+-- CreateIndex
+CREATE INDEX "dashboard_widgets_userId_idx" ON "dashboard_widgets"("userId");
+
+-- CreateIndex
+CREATE INDEX "dashboard_widgets_widgetType_idx" ON "dashboard_widgets"("widgetType");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "dashboard_widgets_userId_position_key" ON "dashboard_widgets"("userId", "position");
+
+-- CreateIndex
+CREATE INDEX "dashboard_layouts_schoolId_idx" ON "dashboard_layouts"("schoolId");
+
+-- CreateIndex
+CREATE INDEX "dashboard_layouts_userId_idx" ON "dashboard_layouts"("userId");
+
+-- CreateIndex
+CREATE INDEX "widget_templates_schoolId_idx" ON "widget_templates"("schoolId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "widget_templates_schoolId_widgetType_key" ON "widget_templates"("schoolId", "widgetType");

prisma/schema.prisma

@@ -132,6 +132,10 @@ model School {
   // Module H notifications relations
   notificationHubs NotificationHub[]
   notificationArchives NotificationArchive[]
+  // Module J widgets relations
+  dashboardWidgets DashboardWidget[]
+  dashboardLayouts DashboardLayout[]
+  widgetTemplates WidgetTemplate[]
 }
 
 model User {
@@ -234,6 +238,9 @@ model User {
   // Module H notifications relations
   notificationHubs          NotificationHub[]
   notificationArchives      NotificationArchive[]
+  // Module J widgets relations
+  dashboardWidgets          DashboardWidget[]
+  dashboardLayouts          DashboardLayout[]
 }
 
 model SchoolYear {
@@ -3572,3 +3579,69 @@ model NotificationArchive {
   @@index([archivedAt])
   @@map("notification_archives")
 }
+
+// ─── Module J: Customizable Dashboard Widgets ──────────────────────
+
+model DashboardWidget {
+  id                String   @id @default(cuid())
+  schoolId          String
+  userId            String
+  widgetType        String   // grade_summary, attendance_trend, upcoming_assessments, class_schedule, wellness_status, recent_messages, announcements
+  title             String?  // Custom title override
+  position          Int      // Grid position (0-11)
+  size              String   @default("medium") // small, medium, large, full_width
+  isVisible         Boolean  @default(true)
+  config            String?  // JSON: widget-specific settings { colors, dateRange, filters, etc }
+  dataSource        String?  // API endpoint or computed field reference
+  refreshInterval   Int      @default(300) // seconds (0 = manual)
+  lastRefresh       DateTime?
+  cacheData         String?  // JSON cached widget data
+  createdAt         DateTime @default(now())
+  updatedAt         DateTime @updatedAt
+
+  school            School   @relation(fields: [schoolId], references: [id])
+  user              User     @relation(fields: [userId], references: [id])
+
+  @@index([schoolId])
+  @@index([userId])
+  @@index([widgetType])
+  @@unique([userId, position])
+  @@map("dashboard_widgets")
+}
+
+model DashboardLayout {
+  id                String   @id @default(cuid())
+  schoolId          String
+  userId            String
+  name              String   // "Default", "Teacher View", "Student View", etc
+  gridColumns       Int      @default(4) // Grid layout columns
+  isDefault         Boolean  @default(false)
+  widgets           String   // JSON: array of widget positions
+  theme             String?  // Dark, light, custom
+  createdAt         DateTime @default(now())
+  updatedAt         DateTime @updatedAt
+
+  school            School   @relation(fields: [schoolId], references: [id])
+  user              User     @relation(fields: [userId], references: [id])
+
+  @@index([schoolId])
+  @@index([userId])
+  @@map("dashboard_layouts")
+}
+
+model WidgetTemplate {
+  id                String   @id @default(cuid())
+  schoolId          String
+  widgetType        String   // Same types as DashboardWidget
+  name              String
+  description       String?
+  defaultConfig     String   // JSON: default configuration
+  thumbnail         String?  // URL to preview image
+  createdAt         DateTime @default(now())
+
+  school            School   @relation(fields: [schoolId], references: [id])
+
+  @@unique([schoolId, widgetType])
+  @@index([schoolId])
+  @@map("widget_templates")
+}