admin/40227-vm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
40227-vm/backend/docs/database-schema.md
Dmitri 0d36322be9 backend migration
2026-06-10 18:27:19 +02:00

48 KiB
Raw Blame History

Database Schema

Generated from the Sequelize models (backend/src/db/models/*) — the source of truth. Regenerate after schema changes. Last generated: 2026-06-09.

Overview

  • Engine: PostgreSQL via Sequelize 6 (models in backend/src/db/models, typed data access in backend/src/db/api).
  • Models: 38 tables.
  • Primary keys: every table has a uuid id (default UUIDV4).
  • Soft delete: all tables are paranoid — rows are flagged with deletedAt instead of being physically removed.
  • Timestamps: createdAt / updatedAt are managed automatically.
  • Audit: createdById / updatedById reference users (aliases createdBy / updatedBy).
  • Multi-tenancy: tenant-owned tables carry organizationId and are scoped to the current user's organization in db/api (see full-integration-refactor-plan.md, tenant boundary workstream).
  • Import idempotency: importHash (unique) deduplicates seeded/imported rows.

Type notes

Types below are the SQL column types. A few Sequelize types are returned as JS string at runtime to preserve precision: DECIMAL, NUMERIC, BIGINT, and DATEONLY (date-only). DATE maps to a JS Date.

Domains

  • Tenancy & Access: organizations, users, roles, permissions
  • Campuses & People: campuses, students, guardians, staff
  • Academics: academic_years, grades, subjects, classes, class_enrollments, class_subjects, timetables, timetable_periods, assessments, assessment_results
  • Attendance: attendance_sessions, attendance_records, campus_attendance_config, campus_attendance_summaries, staff_attendance_records
  • Finance / Billing: fee_plans, invoices, payments
  • Communication: messages, message_recipients, communication_events
  • Content & Product modules: content_catalog, documents, frame_entries, user_progress, safety_quiz_results, walkthrough_checkins, personality_quiz_results
  • System: file, auth_refresh_tokens

Relationship graph (foreign keys)

Each edge is a belongsTo (the child holds the FK). createdBy / updatedBy edges to users are omitted for readability.

erDiagram
  organizations ||--o{ academic_years : "organization"
  organizations ||--o{ assessment_results : "organization"
  assessments ||--o{ assessment_results : "assessment"
  students ||--o{ assessment_results : "student"
  organizations ||--o{ assessments : "organization"
  class_subjects ||--o{ assessments : "class_subject"
  organizations ||--o{ attendance_records : "organization"
  attendance_sessions ||--o{ attendance_records : "attendance_session"
  students ||--o{ attendance_records : "student"
  organizations ||--o{ attendance_sessions : "organization"
  campuses ||--o{ attendance_sessions : "campus"
  classes ||--o{ attendance_sessions : "class"
  class_subjects ||--o{ attendance_sessions : "class_subject"
  staff ||--o{ attendance_sessions : "taken_by"
  users ||--o{ auth_refresh_tokens : "user"
  organizations ||--o{ auth_refresh_tokens : "organization"
  organizations ||--o{ campus_attendance_config : "organization"
  campuses ||--o{ campus_attendance_config : "campus"
  organizations ||--o{ campus_attendance_summaries : "organization"
  campuses ||--o{ campus_attendance_summaries : "campus"
  organizations ||--o{ campuses : "organization"
  organizations ||--o{ class_enrollments : "organization"
  classes ||--o{ class_enrollments : "class"
  students ||--o{ class_enrollments : "student"
  organizations ||--o{ class_subjects : "organization"
  classes ||--o{ class_subjects : "class"
  subjects ||--o{ class_subjects : "subject"
  staff ||--o{ class_subjects : "teacher"
  organizations ||--o{ classes : "organization"
  campuses ||--o{ classes : "campus"
  academic_years ||--o{ classes : "academic_year"
  grades ||--o{ classes : "grade"
  staff ||--o{ classes : "homeroom_teacher"
  organizations ||--o{ communication_events : "organization"
  campuses ||--o{ communication_events : "campus"
  organizations ||--o{ documents : "organization"
  campuses ||--o{ documents : "campus"
  organizations ||--o{ fee_plans : "organization"
  academic_years ||--o{ fee_plans : "academic_year"
  grades ||--o{ fee_plans : "grade"
  organizations ||--o{ frame_entries : "organization"
  campuses ||--o{ frame_entries : "campus"
  organizations ||--o{ grades : "organization"
  organizations ||--o{ guardians : "organization"
  students ||--o{ guardians : "student"
  organizations ||--o{ invoices : "organization"
  campuses ||--o{ invoices : "campus"
  students ||--o{ invoices : "student"
  fee_plans ||--o{ invoices : "fee_plan"
  organizations ||--o{ message_recipients : "organization"
  messages ||--o{ message_recipients : "message"
  organizations ||--o{ messages : "organization"
  campuses ||--o{ messages : "campus"
  users ||--o{ messages : "sent_by"
  organizations ||--o{ payments : "organization"
  invoices ||--o{ payments : "invoice"
  staff ||--o{ payments : "received_by"
  organizations ||--o{ personality_quiz_results : "organization"
  campuses ||--o{ personality_quiz_results : "campus"
  users ||--o{ personality_quiz_results : "user"
  organizations ||--o{ safety_quiz_results : "organization"
  campuses ||--o{ safety_quiz_results : "campus"
  users ||--o{ safety_quiz_results : "user"
  organizations ||--o{ staff : "organization"
  campuses ||--o{ staff : "campus"
  users ||--o{ staff : "user"
  organizations ||--o{ staff_attendance_records : "organization"
  campuses ||--o{ staff_attendance_records : "campus"
  users ||--o{ staff_attendance_records : "user"
  organizations ||--o{ students : "organization"
  campuses ||--o{ students : "campus"
  organizations ||--o{ subjects : "organization"
  organizations ||--o{ timetable_periods : "organization"
  timetables ||--o{ timetable_periods : "timetable"
  class_subjects ||--o{ timetable_periods : "class_subject"
  organizations ||--o{ timetables : "organization"
  campuses ||--o{ timetables : "campus"
  academic_years ||--o{ timetables : "academic_year"
  organizations ||--o{ user_progress : "organization"
  campuses ||--o{ user_progress : "campus"
  users ||--o{ user_progress : "user"
  roles ||--o{ users : "app_role"
  organizations ||--o{ users : "organizations"
  organizations ||--o{ walkthrough_checkins : "organization"
  campuses ||--o{ walkthrough_checkins : "campus"

Table reference

Tenancy & Access

organizations

Tenant root. Every tenant-owned row references an organization via organizationId.

Column Type Null Default Notes
id uuid no UUIDV4 PK
name text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • has many users as users_organizations (FK organizationId)
  • has many campuses as campuses_organization (FK organizationId)
  • has many academic_years as academic_years_organization (FK organizationId)
  • has many grades as grades_organization (FK organizationId)
  • has many subjects as subjects_organization (FK organizationId)
  • has many students as students_organization (FK organizationId)
  • has many guardians as guardians_organization (FK organizationId)
  • has many staff as staff_organization (FK organizationId)
  • has many classes as classes_organization (FK organizationId)
  • has many class_enrollments as class_enrollments_organization (FK organizationId)
  • has many class_subjects as class_subjects_organization (FK organizationId)
  • has many timetables as timetables_organization (FK organizationId)
  • has many timetable_periods as timetable_periods_organization (FK organizationId)
  • has many attendance_sessions as attendance_sessions_organization (FK organizationId)
  • has many attendance_records as attendance_records_organization (FK organizationId)
  • has many fee_plans as fee_plans_organization (FK organizationId)
  • has many invoices as invoices_organization (FK organizationId)
  • has many payments as payments_organization (FK organizationId)
  • has many assessments as assessments_organization (FK organizationId)
  • has many assessment_results as assessment_results_organization (FK organizationId)
  • has many messages as messages_organization (FK organizationId)
  • has many message_recipients as message_recipients_organization (FK organizationId)
  • has many documents as documents_organization (FK organizationId)

users

Authentication identities. email is required (login + primary contact). Belongs to one organization (organizationId, alias organizations), one app_role, and may hold direct custom_permissions.

Column Type Null Default Notes
id uuid no UUIDV4 PK
firstName text yes —
lastName text yes —
phoneNumber text yes —
email text no —
disabled boolean no false
password text yes —
emailVerified boolean no false
emailVerificationToken text yes —
emailVerificationTokenExpiresAt timestamptz yes —
passwordResetToken text yes —
passwordResetTokenExpiresAt timestamptz yes —
provider text yes —
importHash varchar yes — unique, audit
organizationId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
app_roleId uuid yes — FK

Relations:

  • many-to-many with permissions as custom_permissions (FK users_custom_permissionsId)
  • many-to-many with permissions as custom_permissions_filter (FK users_custom_permissionsId)
  • has many staff as staff_user (FK userId)
  • has many messages as messages_sent_by (FK sent_byId)
  • belongs to roles as app_role (FK app_roleId)
  • belongs to organizations as organizations (FK organizationId)
  • has many file as avatar (FK belongsToId)

roles

Named permission sets (RBAC). Linked to permissions M:N; globalAccess grants cross-tenant access.

Column Type Null Default Notes
id uuid no UUIDV4 PK
name text yes —
globalAccess boolean no false
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • many-to-many with permissions as permissions (FK roles_permissionsId)
  • many-to-many with permissions as permissions_filter (FK roles_permissionsId)
  • has many users as users_app_role (FK app_roleId)

permissions

Flat permission catalog. Permission names follow ${METHOD}_${ENTITY} (e.g. READ_CAMPUSES).

Column Type Null Default Notes
id uuid no UUIDV4 PK
name text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Campuses & People

campuses

A physical or online campus belonging to one organization. Parent of students, staff, classes, etc.

Column Type Null Default Notes
id uuid no UUIDV4 PK
name text yes —
code text yes —
address text yes —
phone text yes —
email text yes —
mascot text yes —
color text yes —
bgGradient text yes —
borderColor text yes —
textColor text yes —
bgLight text yes —
description text yes —
isOnline boolean no false
active boolean no false
importHash varchar yes — unique, audit
organizationId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit

Relations:

  • has many students as students_campus (FK campusId)
  • has many staff as staff_campus (FK campusId)
  • has many classes as classes_campus (FK campusId)
  • has many timetables as timetables_campus (FK campusId)
  • has many attendance_sessions as attendance_sessions_campus (FK campusId)
  • has many invoices as invoices_campus (FK campusId)
  • has many messages as messages_campus (FK campusId)
  • has many documents as documents_campus (FK campusId)
  • belongs to organizations as organization (FK organizationId)

students

Enrolled students. Belong to a campus and organization; have guardians, enrollments, attendance, results, invoices.

Column Type Null Default Notes
id uuid no UUIDV4 PK
student_number text yes —
first_name text yes —
last_name text yes —
gender enum yes —
date_of_birth timestamptz yes —
enrollment_date timestamptz yes —
status enum yes —
email text yes —
phone text yes —
address text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
campusId uuid yes — FK
organizationId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • has many guardians as guardians_student (FK studentId)
  • has many class_enrollments as class_enrollments_student (FK studentId)
  • has many attendance_records as attendance_records_student (FK studentId)
  • has many invoices as invoices_student (FK studentId)
  • has many assessment_results as assessment_results_student (FK studentId)
  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)
  • has many file as photo (FK belongsToId)

guardians

Guardians/contacts linked to a student.

Column Type Null Default Notes
id uuid no UUIDV4 PK
full_name text yes —
relationship enum yes —
phone text yes —
email text yes —
address text yes —
primary_contact boolean no false
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
studentId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to students as student (FK studentId)

staff

Staff members, optionally linked to a user account; can be homeroom teacher, subject teacher, attendance taker, payment receiver.

Column Type Null Default Notes
id uuid no UUIDV4 PK
employee_number text yes —
job_title text yes —
staff_type enum yes —
hire_date timestamptz yes —
status enum yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
campusId uuid yes — FK
organizationId uuid yes — FK
userId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • has many classes as classes_homeroom_teacher (FK homeroom_teacherId)
  • has many class_subjects as class_subjects_teacher (FK teacherId)
  • has many attendance_sessions as attendance_sessions_taken_by (FK taken_byId)
  • has many payments as payments_received_by (FK received_byId)
  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)
  • belongs to users as user (FK userId)
  • has many file as photo (FK belongsToId)

Academics

academic_years

School years (with current flag and effective dates) scoping classes, timetables, fee plans.

Column Type Null Default Notes
id uuid no UUIDV4 PK
name text yes —
start_date timestamptz yes —
end_date timestamptz yes —
current boolean no false
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • has many classes as classes_academic_year (FK academic_yearId)
  • has many timetables as timetables_academic_year (FK academic_yearId)
  • has many fee_plans as fee_plans_academic_year (FK academic_yearId)
  • belongs to organizations as organization (FK organizationId)

grades

Grade levels (with sort_order).

Column Type Null Default Notes
id uuid no UUIDV4 PK
name text yes —
code text yes —
sort_order integer yes —
description text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • has many classes as classes_grade (FK gradeId)
  • has many fee_plans as fee_plans_grade (FK gradeId)
  • belongs to organizations as organization (FK organizationId)

subjects

Academic subjects (Math, English, …).

Column Type Null Default Notes
id uuid no UUIDV4 PK
name text yes —
code text yes —
description text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • has many class_subjects as class_subjects_subject (FK subjectId)
  • belongs to organizations as organization (FK organizationId)

classes

Class/group: belongs to campus, academic year, grade, and a homeroom teacher.

Column Type Null Default Notes
id uuid no UUIDV4 PK
name text yes —
section text yes —
capacity integer yes —
status enum yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
academic_yearId uuid yes — FK
campusId uuid yes — FK
organizationId uuid yes — FK
gradeId uuid yes — FK
homeroom_teacherId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • has many class_enrollments as class_enrollments_class (FK classId)
  • has many class_subjects as class_subjects_class (FK classId)
  • has many attendance_sessions as attendance_sessions_class (FK classId)
  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)
  • belongs to academic_years as academic_year (FK academic_yearId)
  • belongs to grades as grade (FK gradeId)
  • belongs to staff as homeroom_teacher (FK homeroom_teacherId)

class_enrollments

Join of student ↔ class with enrolment dates and status.

Column Type Null Default Notes
id uuid no UUIDV4 PK
enrolled_on timestamptz yes —
ended_on timestamptz yes —
status enum yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
classId uuid yes — FK
studentId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to classes as class (FK classId)
  • belongs to students as student (FK studentId)

class_subjects

Join of class ↔ subject ↔ teacher; the unit that schedule, attendance, and assessments hang off.

Column Type Null Default Notes
id uuid no UUIDV4 PK
status enum yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
classId uuid yes — FK
subjectId uuid yes — FK
teacherId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • has many timetable_periods as timetable_periods_class_subject (FK class_subjectId)
  • has many attendance_sessions as attendance_sessions_class_subject (FK class_subjectId)
  • has many assessments as assessments_class_subject (FK class_subjectId)
  • belongs to organizations as organization (FK organizationId)
  • belongs to classes as class (FK classId)
  • belongs to subjects as subject (FK subjectId)
  • belongs to staff as teacher (FK teacherId)

timetables

A timetable for a campus + academic year, with effective dates.

Column Type Null Default Notes
id uuid no UUIDV4 PK
name text yes —
effective_from timestamptz yes —
effective_to timestamptz yes —
status enum yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
academic_yearId uuid yes — FK
campusId uuid yes — FK
organizationId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • has many timetable_periods as timetable_periods_timetable (FK timetableId)
  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)
  • belongs to academic_years as academic_year (FK academic_yearId)

timetable_periods

A single period (day/time/room) linking a timetable to a class_subject.

Column Type Null Default Notes
id uuid no UUIDV4 PK
day_of_week enum yes —
starts_at timestamptz yes —
ends_at timestamptz yes —
room text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
class_subjectId uuid yes — FK
organizationId uuid yes — FK
timetableId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to timetables as timetable (FK timetableId)
  • belongs to class_subjects as class_subject (FK class_subjectId)

assessments

Assessments for a class_subject (type, dates, max score, attachments).

Column Type Null Default Notes
id uuid no UUIDV4 PK
name text yes —
assessment_type enum yes —
assigned_at timestamptz yes —
due_at timestamptz yes —
max_score decimal yes —
status enum yes —
instructions text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
class_subjectId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • has many assessment_results as assessment_results_assessment (FK assessmentId)
  • belongs to organizations as organization (FK organizationId)
  • belongs to class_subjects as class_subject (FK class_subjectId)
  • has many file as attachments (FK belongsToId)

assessment_results

A student's result for an assessment (score, grade_letter).

Column Type Null Default Notes
id uuid no UUIDV4 PK
score decimal yes —
grade_letter enum yes —
remarks text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
assessmentId uuid yes — FK
studentId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to assessments as assessment (FK assessmentId)
  • belongs to students as student (FK studentId)

Attendance

attendance_sessions

An attendance session for a class/class_subject taken by a staff member.

Column Type Null Default Notes
id uuid no UUIDV4 PK
session_date timestamptz yes —
session_type enum yes —
notes text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
campusId uuid yes — FK
classId uuid yes — FK
class_subjectId uuid yes — FK
taken_byId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • has many attendance_records as attendance_records_attendance_session (FK attendance_sessionId)
  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)
  • belongs to classes as class (FK classId)
  • belongs to class_subjects as class_subject (FK class_subjectId)
  • belongs to staff as taken_by (FK taken_byId)

attendance_records

Per-student attendance within a session (status, minutes_late).

Column Type Null Default Notes
id uuid no UUIDV4 PK
status enum yes —
minutes_late integer yes —
remarks text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
attendance_sessionId uuid yes — FK
studentId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to attendance_sessions as attendance_session (FK attendance_sessionId)
  • belongs to students as student (FK studentId)

campus_attendance_config

Product-module config for campus attendance.

Column Type Null Default Notes
id uuid no UUIDV4 PK
campus_key text no —
attendance_link text yes —
updated_by_label text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
campusId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)

campus_attendance_summaries

Product-module aggregated campus attendance.

Column Type Null Default Notes
id uuid no UUIDV4 PK
campus_key text no —
attendance_date date no —
total_enrolled integer no —
total_present integer no —
total_absent integer no —
total_tardy integer no 0
attendance_percentage decimal no —
recorded_by_label text yes —
notes text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
campusId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)

staff_attendance_records

Staff attendance records (present/late/absent).

Column Type Null Default Notes
id uuid no UUIDV4 PK
attendance_date date no —
status enum no —
note text yes —
user_name text no —
user_role text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
campusId uuid yes — FK
userId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)
  • belongs to users as user (FK userId)

Finance / Billing

fee_plans

Fee/tuition plans (billing cycle, total amount) for a grade in an academic year. Invoices are generated from these.

Column Type Null Default Notes
id uuid no UUIDV4 PK
name text yes —
billing_cycle enum yes —
total_amount decimal yes —
active boolean no false
notes text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
academic_yearId uuid yes — FK
organizationId uuid yes — FK
gradeId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • has many invoices as invoices_fee_plan (FK fee_planId)
  • belongs to organizations as organization (FK organizationId)
  • belongs to academic_years as academic_year (FK academic_yearId)
  • belongs to grades as grade (FK gradeId)

invoices

Invoices issued to a student (amounts, status) — optionally from a fee_plan.

Column Type Null Default Notes
id uuid no UUIDV4 PK
invoice_number text yes —
issue_date timestamptz yes —
due_date timestamptz yes —
subtotal decimal yes —
discount_amount decimal yes —
tax_amount decimal yes —
total_amount decimal yes —
balance_due decimal yes —
status enum yes —
notes text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
campusId uuid yes — FK
fee_planId uuid yes — FK
organizationId uuid yes — FK
studentId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • has many payments as payments_invoice (FK invoiceId)
  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)
  • belongs to students as student (FK studentId)
  • belongs to fee_plans as fee_plan (FK fee_planId)
  • has many file as attachments (FK belongsToId)

payments

Payments against an invoice (amount, method, proof file).

Column Type Null Default Notes
id uuid no UUIDV4 PK
receipt_number text yes —
paid_at timestamptz yes —
amount decimal yes —
method enum yes —
reference_code text yes —
notes text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
invoiceId uuid yes — FK
organizationId uuid yes — FK
received_byId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to invoices as invoice (FK invoiceId)
  • belongs to staff as received_by (FK received_byId)
  • has many file as proof (FK belongsToId)

Communication

messages

In-app announcements/messages (subject/body/channel/audience) with attachments and recipients.

Column Type Null Default Notes
id uuid no UUIDV4 PK
subject text yes —
body text yes —
channel enum yes —
audience enum yes —
sent_at timestamptz yes —
status enum yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
campusId uuid yes — FK
organizationId uuid yes — FK
sent_byId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • has many message_recipients as message_recipients_message (FK messageId)
  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)
  • belongs to users as sent_by (FK sent_byId)
  • has many file as attachments (FK belongsToId)

message_recipients

Per-recipient delivery/read tracking for a message (in-app).

Column Type Null Default Notes
id uuid no UUIDV4 PK
recipient_type enum yes —
recipient_label text yes —
destination text yes —
delivery_status enum yes —
delivered_at timestamptz yes —
read_at timestamptz yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
messageId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to messages as message (FK messageId)

communication_events

Product-module communication events (meetings, drills, events, deadlines).

Column Type Null Default Notes
id uuid no UUIDV4 PK
title text no —
event_date date no —
event_type text no —
roles jsonb no Array
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
campusId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)

Content & Product modules

content_catalog

Product content catalog.

Column Type Null Default Notes
id uuid no UUIDV4 PK
content_type text no — unique
payload jsonb no —
active boolean no true
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit

documents

Polymorphic document records with a file attachment, scoped to organization/campus.

Column Type Null Default Notes
id uuid no UUIDV4 PK
entity_type enum yes —
entity_reference text yes —
name text yes —
category enum yes —
uploaded_at timestamptz yes —
notes text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
campusId uuid yes — FK
organizationId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)
  • has many file as file (FK belongsToId)

frame_entries

Product-module "frame" entries.

Column Type Null Default Notes
id uuid no UUIDV4 PK
week_of text no —
posted_date text no —
formal text no —
recognition text no —
application text no —
management text no —
emotional text no —
author text no —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
campusId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)

user_progress

Per-user progress (sign learning, zone check-ins).

Column Type Null Default Notes
id uuid no UUIDV4 PK
progress_type text no —
item_id text no —
value text yes —
score integer yes —
metadata jsonb yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
campusId uuid yes — FK
userId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)
  • belongs to users as user (FK userId)

safety_quiz_results

Product-module safety quiz results.

Column Type Null Default Notes
id uuid no UUIDV4 PK
quiz_id text no —
quiz_title text no —
week_of text no —
score integer no —
total_questions integer no —
answers jsonb no —
user_name text no —
user_role text no —
completed_at timestamptz no —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
campusId uuid yes — FK
userId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)
  • belongs to users as user (FK userId)

walkthrough_checkins

Product-module walkthrough check-ins.

Column Type Null Default Notes
id uuid no UUIDV4 PK
teacher_name text no —
classroom text no —
director_name text no —
check_in_date date no —
check_in_time time no —
attitude_rating integer no —
attitude_comment text yes —
classroom_management_rating integer no —
classroom_management_comment text yes —
cleanliness_rating integer no —
cleanliness_comment text yes —
vibes_rating integer no —
vibes_comment text yes —
team_dynamics_rating integer no —
team_dynamics_comment text yes —
emergency_exit_rating integer no —
emergency_exit_comment text yes —
lesson_plan_rating integer no —
lesson_plan_comment text yes —
overall_notes text yes —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
campusId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)

personality_quiz_results

Product-module personality quiz results.

Column Type Null Default Notes
id uuid no UUIDV4 PK
personality_type text no —
quiz_answers jsonb no —
completed_at timestamptz no —
importHash varchar yes — unique, audit
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
organizationId uuid yes — FK
campusId uuid yes — FK
userId uuid yes — FK
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

Relations:

  • belongs to organizations as organization (FK organizationId)
  • belongs to campuses as campus (FK campusId)
  • belongs to users as user (FK userId)

System

file

Polymorphic file/attachment store (belongsTo + belongsToColumn + belongsToId).

Column Type Null Default Notes
id uuid no UUIDV4 PK
belongsTo varchar yes —
belongsToId uuid yes — FK
belongsToColumn varchar yes —
name varchar no —
sizeInBytes integer yes —
privateUrl varchar yes —
publicUrl varchar no —
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit
deletedAt timestamptz yes — audit
createdById uuid yes — FK, audit
updatedById uuid yes — FK, audit

auth_refresh_tokens

Refresh-token rotation records for cookie-based auth (hash, family, expiry, revocation).

Column Type Null Default Notes
id uuid no UUIDV4 PK
userId uuid no — FK
organizationId uuid yes — FK
tokenHash text no — unique
familyId uuid no — FK
previousTokenId uuid yes — FK
userAgent text yes —
ipAddress text yes —
expiresAt timestamptz no —
revokedAt timestamptz yes —
replacedByTokenId uuid yes — FK
createdAt timestamptz yes — audit
updatedAt timestamptz yes — audit

Relations:

  • belongs to users as user (FK userId)
  • belongs to organizations as organization (FK organizationId)