geocrop-platform./apps/nextgen/datacontrol.md

Database Control Matrix (datacontrol.md)

This document maps all available backend controllers to the SQLite database tables they interact with, detailing the operations performed (reads, writes, updates, soft-deletes) and the transaction patterns they use.

---

Design Principles & Patterns

• Write Operations (INSERT / UPDATE): Under nextgen server conventions, all direct write operations set sync_status = 'pending', generate a new UUIDv4 uid on creation, and stamp the local timestamp updated_at.
• Soft Deletes: Deletion operations do not drop DB table records. Instead, they run an UPDATE command setting is_deleted = 1 (and often set is_active = 0 or similar lifecycle flags when relevant).
• Transactional Integrity: Multi-step operations (e.g. bulk CSV marks upload in marks.controller.js, bulk attendance marks, or invoice calculations) use explicit database transactions (via better-sqlite3's db.transaction(...)) to guarantee all-or-nothing execution.
• Read Scoping: Read operations are filtered globally on is_deleted = 0 and scoped appropriately (e.g., student/parent portals only view records matched to their specific user or linked dependent IDs).
• Grading Scale Resolutions: Complex entities like grades.controller.js and exams.controller.js dynamically resolve percentages against a cascading grading-scale chain (specific row scale override -> default school configuration scale -> ZIMSEC standard fallback bands).

---

Controllers & Database Interactions

1. academic-rollover.controller.js

• academic_years:
  • SELECT (retrieve status, lists)
  • INSERT (create new year: uid, name, status = 'draft', start_date, end_date)
  • UPDATE (change status to 'active', 'completed'; soft-delete with is_deleted = 1)
• classes:
  • SELECT (fetch classes to rollover)
  • INSERT (clone/rollover classes into new academic year)
• subjects:
  • SELECT (fetch subjects to rollover)
  • INSERT (clone/rollover subjects into new academic year)
• enrollments:
  • SELECT (active enrollment state checks)
  • INSERT (auto-promote students to new classes in the rolling year)
• users:
  • SELECT (link student roles)

2. assignments.controller.js

• assignments:
  • SELECT (list active assignments with class/subject boundaries)
  • INSERT (create assignment: uid, title, description, subject_id, due_date, max_score, created_by)
  • UPDATE (edit fields; soft-delete with is_deleted = 1)
• submissions:
  • SELECT (check user submissions history)
  • INSERT (create draft/initial submission: uid, assignment_id, student_id, status = 'submitted', submitted_at)
  • UPDATE (grade submission: grade, feedback, graded_by, graded_at, status = 'graded'; soft-delete with is_deleted = 1)
• users:
  • SELECT (joining names for graders/students)
• enrollments:
  • SELECT (verify active student status in target class)

3. attendance.controller.js

• attendance_new:
  • SELECT (retrieve rosters, historical summaries)
  • INSERT (bulk insert roll-call records: uid, student_id, class_id, date, status, remarks, marked_by)
  • UPDATE (modify status, remarks, marked_by, or soft-delete with is_deleted = 1)
• users:
  • SELECT (verify students name)
• enrollments:
  • SELECT (active student list for class roster)
• classes:
  • SELECT (validate target class)
• parent_students:
  • SELECT (scoped lookup for parent portal self-read)

4. audit.controller.js

• audit_logs:
  • SELECT (list recent events filtered by email, action, date)
  • INSERT (log technical actions/events: uid, user_id, user_email, action, entity_type, entity_id, old_data, new_data, ip_address, user_agent)
• users:
  • SELECT (look up user emails)

5. calendar.controller.js

• events:
  • SELECT (list active events filterable by category, date range)
  • INSERT (create calendar event: uid, title, description, start_time, end_time, category, is_all_day, location, created_by)
  • UPDATE (modify properties; soft-delete with is_deleted = 1)
• users:
  • SELECT (join creator profile)

6. classes.controller.js

• classes:
  • SELECT (list active classes with counts)
  • INSERT (create class: uid, name, section, grade_level, room_number, class_teacher_id)
  • UPDATE (modify properties; soft-delete with is_deleted = 1)
• users:
  • SELECT (join teacher names)
• enrollments:
  • SELECT (calculate active student roll counts)

7. club-attendance.controller.js

• club_attendance:
  • SELECT (list roll-call entries)
  • INSERT (bulk insert club logs: uid, club_id, student_id, date, status, remarks, marked_by)
  • UPDATE (modify attendance details; soft-delete with is_deleted = 1)
• clubs:
  • SELECT (verify active status)
• users:
  • SELECT (verify students)

8. clubs.controller.js

• clubs:
  • SELECT (active clubs catalog list)
  • INSERT (create club: uid, name, type, description, teacher_in_charge_id, schedule, max_members)
  • UPDATE (modify properties, status; soft-delete with is_deleted = 1)
• club_memberships:
  • SELECT (check active student enrollments)
  • INSERT (join a club: uid, club_id, student_id, status = 'active', join_date = CURRENT_DATE)
  • UPDATE (re-enroll/join; leave a club: set status = 'inactive')
• club_announcements:
  • SELECT (list recent club notices)
  • INSERT (post notice: uid, club_id, title, content, created_by)
• club_attendance:
  • SELECT (active roll-call records)
  • INSERT / UPDATE (bulk upsert marks matching (club_id, student_id, date))
• club_chats:
  • SELECT (list messages)
  • INSERT (post message: uid, club_id, sender_id, message, image_url)
• users:
  • SELECT (joining names for dashboard/contacts)

9. courseGrades.controller.js

• course_grades:
  • SELECT (list student performance scores)
  • INSERT (record grade: uid, student_id, course_id, grade_letter, grade_points, percentage, remarks, graded_by)
  • UPDATE (modify grade letter, percentage, remarks, graded_by; soft-delete with is_deleted = 1)
• course_enrolments:
  • SELECT (verify active status in courses)
• courses:
  • SELECT (verify existence)
• users:
  • SELECT (verify roles)

10. course_enrolments.controller.js

• course_enrolments:
  • SELECT (active, pending, and filterable enrolment requests lists)
  • INSERT (create enrolment: uid, student_id, course_id, status, request_status, requested_at, approved_by, approved_at, progress = 0, sync_status = 'pending')
  • UPDATE (modify request_status to 'approved', 'rejected', or 'withdrawn'; modify status to 'active' or 'dropped'; modify approved_by, approved_at, rejection_reason, updated_at, sync_status = 'pending', soft-delete is_deleted = 1)
• courses:
  • SELECT (existence checks)
• users:
  • SELECT (joining student profiles)

11. courses.controller.js

• subjects: (Note: The routes query/modify subjects table name, not a courses table name directly, although the controller is called courses.controller.js).
  • SELECT (catalog list with filters)
  • INSERT (create course: uid, name, code, class_id, teacher_id, description, credit_hours)
  • UPDATE (modify attributes, or soft-delete with is_deleted = 1)
• classes:
  • SELECT (class details)
• users:
  • SELECT (teacher and student directories)
• enrollments:
  • SELECT (verify class list)
• grades:
  • SELECT (calculate percentage average and recent history list)

12. crossword.controller.js

• crossword_games:
  • SELECT (active games lists with role/status filters, metadata detail fetch)
  • INSERT (create game layout details: uid, title, description, subject_id, class_id, created_by, status = 'ready', grid_layout JSON, word_count, difficulty, reward_points, time_limit_seconds, is_published = 0, sync_status = 'pending', created_at, updated_at)
  • UPDATE (modify game attributes: title, description, reward_points, time_limit_seconds, is_published, updated_at, soft-delete with is_deleted = 1)
• crossword_clues:
  • SELECT (clues details for active games)
  • INSERT (create clues per placement: uid, game_id, clue_text, answer, direction, start_row, start_col, clue_number, hint, sync_status = 'pending', created_at, updated_at)
  • UPDATE (soft-delete with is_deleted = 1)
• crossword_sessions:
  • SELECT (active/completed history matching student user, leaderboard statistics)
  • INSERT (start new session: uid, game_id, student_id, current_state = '{}', correct_count = 0, total_count, points_earned = 0, sync_status = 'pending', created_at, updated_at)
  • UPDATE (save debounced state current_state; submit completion updates: correct_count, total_count, points_earned, time_taken_seconds, completed_at = CURRENT_TIMESTAMP, updated_at = CURRENT_TIMESTAMP, sync_status = 'pending')
• users:
  • SELECT (joining student profiles for dashboard ranking leaderboard counts)

13. dashboard.controller.js

(Note: Completely READ-ONLY SELECT operations)

• enrollments, attendance / attendance_new, grades, subjects_new / subjects, classes, users, payments, student_fees, audit_logs, courses, course_enrolments, course_grades, submissions, assignments, crossword_sessions, parent_students, messages, events:
  • SELECT (aggregate dashboard stats, unread announcements, schedule items)

14. departments.controller.js

• departments:
  • SELECT (flat lists and tree detail views)
  • INSERT (create department: uid, name, code, head_teacher_id, description)
  • UPDATE (modify attributes, or soft-delete with is_deleted = 1 if no active subjects link)
• subjects_new:
  • SELECT (active subject counts checks)
• staff_records:
  • SELECT (fetch head teachers), UPDATE (modify department name reference if changed)
• users:
  • SELECT (teacher links), UPDATE (modify department_id assignment)
• enrollments:
  • SELECT (count active students)

15. edutainment.controller.js

• edutainment_content:
  • SELECT (scramble and trivia pool lists)
  • INSERT (create catalog content: uid, game_type, subject_id, created_by, question_text, hint_text, options JSON, correct_answer)
  • UPDATE (soft-delete with is_deleted = 1)
• edutainment_games:
  • SELECT (list custom puzzles)
  • INSERT (create custom game template: uid, game_type, title, description, subject_id, created_by, difficulty, reward_points, time_limit_seconds, game_config JSON, is_published = 1)
  • UPDATE (soft-delete with is_deleted = 1)
• edutainment_sessions:
  • SELECT (attempt count summaries)
  • INSERT (record student game attempt session: uid, game_id, student_id, score, completed_at = CURRENT_TIMESTAMP, points_earned)
• subjects_new:
  • SELECT (joining subject names)
• users:
  • SELECT (joining teacher names)

16. enrollments.controller.js

• enrollments:
  • SELECT (enrolment request lists, active/pending profiles)
  • INSERT (create request: uid, student_id, class_id, roll_number, academic_year, section, status, request_status, requested_at, approved_by, approved_at, sync_status = 'pending')
  • UPDATE (approve request: status 'active', request_status 'approved'; reject request: status 'inactive', request_status 'rejected', rejection_reason; withdraw request: status 'inactive', request_status 'withdrawn'; soft-delete with is_deleted = 1 and status 'inactive')
• classes:
  • SELECT (checking class properties and sections)
• users:
  • SELECT (verifying active student roles)

17. exams.controller.js

• exam_groups:
  • SELECT (list templates)
  • INSERT (create exam group: uid, name, description, exam_type, duration_minutes, total_marks, passing_marks, is_random_order, show_results, allow_review, max_attempts, academic_year, term, grading_scale)
  • UPDATE (modify mutable fields, grading_scale; soft-delete with is_deleted = 1)
• question_banks:
  • SELECT (questions with difficulty lists)
  • INSERT (single and bulk insert: uid, exam_group_id, subject_id, question_type, question, options, correct_answer, marks, difficulty, tags)
  • UPDATE (modify question attributes; soft-delete with is_deleted = 1)
• exam_schedules:
  • SELECT (scheduled exams index)
  • INSERT (create schedule: uid, exam_group_id, class_id, subject_id, start_time, end_time, duration_minutes, instructions)
• exam_attempts:
  • SELECT (attempt counts and performance averages)
  • INSERT (start new attempt: uid, student_id, exam_group_id, schedule_id, started_at)
  • UPDATE (submit attempt: submitted_at, time_spent_seconds, total_marks, obtained_marks, percentage, status = 'submitted', ip_address, user_agent)
• exam_answers:
  • SELECT (fetch student answers)
  • INSERT / UPDATE (upsert answer: answer, answered_at / write grade results: is_correct, marks_obtained)
• enrollments, subjects, classes, users:
  • SELECT (verify relationship linkages)

18. fees.controller.js

• fee_groups:
  • SELECT (list definitions)
  • INSERT (create fee type: uid, name, description, amount, type, frequency, academic_year, due_date)
  • UPDATE (modify attributes; soft-delete with is_deleted = 1)
• student_fees:
  • SELECT (student ledger profiles list)
  • INSERT (assign fee type: uid, student_id, fee_group_id, amount, due_date)
• fee_plans:
  • SELECT (list schedules)
  • INSERT (create plan: uid, name, fee_group_id, total_amount, installments_count, start_date, end_date, academic_year, auto_apply_to_class_id, notes, created_by)
  • UPDATE (modify mutable fields; soft-delete with is_deleted = 1)
• fee_plan_installments:
  • SELECT (fetch split amounts)
  • INSERT (create installment rows: uid, fee_plan_id, sequence, label, amount, due_date)
  • UPDATE (soft-delete with is_deleted = 1 on plan delete/reset)
• discounts:
  • SELECT (list discounts)
  • INSERT (create discount rate: uid, name, kind, value, scope, scope_id, reason, valid_from, valid_to, academic_year, created_by)
  • UPDATE (modify details; soft-delete with is_deleted = 1)
• student_fee_discounts:
  • UPDATE (soft-delete with is_deleted = 1 on discount delete)
• users, enrollments, classes:
  • SELECT (validate student scopes)

19. finance-banking.controller.js

• bank_accounts:
  • SELECT (list cash/assets balances)
  • INSERT (create account: uid, name, bank_name, account_number, account_type, currency, opening_balance, current_balance, chart_account_id, is_active)
  • UPDATE (modify account settings; soft-delete with is_deleted = 1, is_active = 0)
• bank_reconciliations:
  • SELECT (list bank recon history)
  • INSERT (create draft recon: uid, bank_account_id, period_start, period_end, statement_balance, status = 'draft', created_by)
  • UPDATE (modify status: 'balanced' or 'discrepancy', setting book_balance)
• bank_reconciliation_lines:
  • SELECT (fetch lines list)
  • INSERT (auto-match statement lines: uid, reconciliation_id, payment_id, statement_date, statement_amount, statement_reference, match_status)
  • UPDATE (resolve line match: update match_status and payment_id)
• chart_of_accounts, payments:
  • SELECT (verify transaction linkages)

20. finance-coa.controller.js

• chart_of_accounts:
  • SELECT (ledger codes flat lists and tree hierarchies)
  • INSERT (create account: uid, code, name, type, parent_id, color, is_active)
  • UPDATE (modify codes attributes; soft-delete with is_deleted = 1, is_active = 0)
• bank_accounts:
  • SELECT (constraint validation checks)

21. finance-engine.controller.js

• student_groups:
  • SELECT (groups search and detail metrics)
  • INSERT (create student cohort: uid, name, description, type, color, class_id, capacity, auto_track_class, created_by)
  • UPDATE (modify properties; soft-delete with is_deleted = 1)
• student_group_members:
  • SELECT (member details and student count calculations)
  • INSERT (add member mapping: uid, group_id, student_id)
  • UPDATE (soft-delete with is_deleted = 1)
• student_fees:
  • SELECT (check applied plans)
  • INSERT (apply plan installment: uid, student_id, fee_group_id, plan_id, amount, due_date, status = 'pending', sync_status = 'pending')
  • UPDATE (re-aggregate discount_amount; soft-delete with is_deleted = 1 and sync_status = 'pending' when revoking unpaid plans)
• student_fee_discounts:
  • SELECT (applied discount lines checks)
  • INSERT (apply discount: uid, student_fee_id, discount_id, amount_applied, applied_by)
  • UPDATE (modify amount_applied, or soft-delete with is_deleted = 1)
• classes, users, enrollments, fee_plans, fee_plan_installments, discounts, fee_groups:
  • SELECT (scope verification checks)

22. finance-invoices.controller.js

• invoices:
  • SELECT (invoice search pages index)
  • INSERT (create invoice: uid, invoice_number, student_id, fee_group_id, plan_id, period_label, subtotal, discount_amount, total, paid_amount = 0, currency, status = 'issued', issued_at, due_date, notes, created_by)
  • UPDATE (modify status, notes, subtotal; soft-delete with is_deleted = 1 and status 'cancelled')
• users, fee_groups, student_fees, fee_plans:
  • SELECT (verify billing components)

23. finance-suppliers.controller.js

• suppliers:
  • SELECT (supplier details search catalog list)
  • INSERT (create supplier: uid, name, code, contact_person, email, phone, address, city, country, tax_id, bank_details, notes, is_active, sync_status = 'pending')
  • UPDATE (modify supplier details; soft-delete with is_deleted = 1, is_active = 0)

24. finance-trips.controller.js

• trips:
  • SELECT (bookings catalog)
  • INSERT (create field trip: uid, name, destination, departure_date, return_date, cost_per_student, total_capacity, status = 'draft', description, created_by)
  • UPDATE (modify trip details; soft-delete with is_deleted = 1, status = 'cancelled')
• trip_payments:
  • SELECT (passenger booking accounts checks)
  • INSERT (assign student passenger: uid, trip_id, student_id, invoiced_amount, status = 'pending', created_by)
  • UPDATE (pay/refund: paid_amount, status, paid_at, updated_at; soft-delete with is_deleted = 1 and status = 'cancelled')
• users, enrollments:
  • SELECT (look up student eligibility)

25. finance.controller.js

(Note: Proxies payroll routes to hr.controller.js)

• payments:
  • SELECT (sum payment amounts this month)
• student_fees:
  • SELECT (sum outstanding amount: amount - paid_amount)
• payroll_runs:
  • SELECT (details of latest run)
• expenses:
  • SELECT (list with filters/pagination)
  • INSERT (create expense: uid, category, subcategory, description, amount, expense_date, vendor, invoice_number, payment_method, status, receipt_image, created_by)
  • UPDATE (modify fields, change status to 'approved'/'rejected', or soft-delete with is_deleted = 1)
• invoices, trips, bank_reconciliations, student_groups:
  • SELECT (additional tile aggregations)

26. front-office.controller.js

• visitor_logs:
  • SELECT (visitor log registry)
  • INSERT (log visitor check-in: uid, visitor_name, visitor_type, phone, email, id_number, purpose, person_to_visit, badge_number, remarks, created_by)
  • UPDATE (check out: set check_out time; soft-delete with is_deleted = 1)
• admission_enquiries:
  • SELECT (enquiry follow-up checklist)
  • INSERT (create enquiry: uid, full_name, email, phone, address, class_interested, source, follow_up_date, notes, next_action, assigned_to)
  • UPDATE (modify enquiry details; soft-delete with is_deleted = 1)
• complaints:
  • SELECT (complaint tracking files)
  • INSERT (file complaint: uid, complainant_name, complainant_type, contact_phone, contact_email, category, priority, subject, description, assigned_to, status = 'open')
  • UPDATE (resolve complaint: set status = 'resolved', resolution, resolved_by, resolved_at)
• phone_call_logs:
  • SELECT (phone checklists logs)
  • INSERT (single / bulk record phone logs: uid, caller_name, caller_phone, caller_type, direction, call_time, duration_seconds, purpose, response, follow_up_required, follow_up_date, handled_by, notes)
  • UPDATE (modify details; clear follow-up: set follow_up_required = 0; soft-delete with is_deleted = 1)
• postal_dispatch:
  • SELECT (mailroom delivery registries)
  • INSERT (single / bulk log mail items: uid, type, reference_number, sender, receiver, address, courier, tracking_number, dispatch_date, description, status = 'pending', created_by)
  • UPDATE (modify details; mark sent: set status = 'sent'; mark delivered: set status = 'delivered', received_date; soft-delete with is_deleted = 1)
• users:
  • SELECT (consultant names check)

27. grades.controller.js

• grades:
  • SELECT (list results with filters, calculate average summaries)
  • INSERT (single and bulk: uid, student_id, subject_id, exam_type, marks, total_marks, grade, grading_scale, remarks, graded_by, academic_year, term)
  • UPDATE (modify marks, grade letter, remarks, grading_scale, graded_by; soft-delete with is_deleted = 1)
• users, subjects, classes, enrollments:
  • SELECT (verify relationships)

28. hostel-attendance.controller.js

• hostel_attendance:
  • SELECT (hostel attendance counts checklist)
  • INSERT (record check-in: uid, hostel_id, room_id, student_id, date, status, marked_by)
  • UPDATE (modify status, marked_by, updated_at)
• hostels, rooms, room_assignments:
  • SELECT (verify boarding occupancy)
• users, parent_students:
  • SELECT (verify child boundaries)

29. hostel.controller.js

• hostels:
  • SELECT (active hostels catalog list)
  • INSERT (create hostel: uid, name, code, type, address, warden_id, phone, description)
• rooms:
  • SELECT (rooms in hostel catalog)
  • INSERT (create room: uid, hostel_id, room_type_id, room_number, floor, bed_count, status = 'available', description)
  • UPDATE (change status to 'available'/'occupied')
• room_assignments:
  • SELECT (list assignments)
  • INSERT (assign student to bed: uid, student_id, room_id, bed_number, start_date, end_date, status = 'active', remarks, assigned_by)
  • UPDATE (check out assignment: set status = 'inactive', end_date = today)
• room_types:
  • SELECT (list room configurations)
• hostel_attendance:
  • SELECT (attendance logs index)
  • INSERT / UPDATE (bulk upsert hostel attendance matching (hostel_id, student_id, date))
• users:
  • SELECT (warden/student validation checks)

30. hr.controller.js

• staff_roles:
  • SELECT (list active roles)
  • INSERT (create role: uid, name, description, is_teaching_role, permissions)
• salary_grades:
  • SELECT (list pay grades)
  • INSERT (create salary grade: uid, name, grade_level, basic_salary, housing_allowance, transport_allowance, medical_allowance, other_allowances, description, effective_date)
• staff_records:
  • SELECT (list employment cards details)
  • INSERT (create record: uid, user_id, staff_number, role_id, salary_grade_id, employment_type, appointment_date, bank_name, account_number, department, designation)
  • UPDATE (modify role, pay scale, active status; soft-delete with is_deleted = 1)
• leave_types:
  • SELECT (list categories)
• leave_requests:
  • SELECT (requests history lists)
  • INSERT (submit request: uid, staff_id, leave_type_id, start_date, end_date, days_count, reason)
  • UPDATE (approve/reject: set status, rejection_reason, approved_by, approved_at)
• staff_attendance:
  • SELECT (roster index)
  • INSERT (log day check: uid, staff_id, date, status, remarks, marked_by)
• payroll_runs:
  • SELECT (list runs)
  • INSERT (create run: uid, period_month, period_year, description, status = 'draft', created_by)
  • UPDATE (calculate totals: total_gross, total_deductions, total_net, status = 'calculated'; mark paid: set status = 'paid', paid_at; cancel run: reset status to 'draft', zero out totals)
• payslips:
  • SELECT (list slips)
  • INSERT (generate payslips for run)
  • UPDATE (cascading update to status 'paid' and paid_at)
  • DELETE (recalculating run deletes old slips)
• vacancies:
  • SELECT (list vacancies)
  • INSERT (create job posting: uid, title, description, requirements, department, status = 'open', closing_date)
  • UPDATE (modify details, status; soft-delete with is_deleted = 1)
• applicants:
  • SELECT (list candidates)
  • INSERT (add applicant: uid, vacancy_id, first_name, last_name, email, phone, resume_url, status = 'pending', notes)
  • UPDATE (modify status, interview_date, notes)
• users:
  • SELECT (validate identities)

31. inventory.controller.js

• item_categories:
  • SELECT (list categories)
  • INSERT (create category: uid, name, code, description, parent_id)
• suppliers:
  • SELECT (list vendors)
  • INSERT (create vendor: uid, name, code, contact_person, email, phone)
• store_locations:
  • SELECT (list store spaces)
• items:
  • SELECT (list items)
  • INSERT (create item card: uid, name, code, barcode, description, category_id, unit, purchase_price, selling_price, reorder_level, supplier_id)
• item_stock:
  • SELECT (current inventory balances list)
  • INSERT (create stock row if missing)
  • UPDATE (increment/decrement quantity)
• stock_transactions:
  • INSERT (record ledger transaction: uid, item_id, store_id, type, quantity, unit_price, total_amount, reference_number, supplier_id, notes, created_by)
• item_issues:
  • SELECT (issued items tracking list)
  • INSERT (issue item: uid, item_id, issued_to_type, issued_to_id, quantity, purpose, return_due_date, notes, issued_by)
  • UPDATE (return items: update returned_quantity, returned_date, status = 'returned'|'partially_returned', condition_on_return)
• users:
  • SELECT (join issuer profile)

32. library.controller.js

• library_books:
  • SELECT (catalog lists)
  • INSERT (single and bulk book import: uid, isbn, title, author, category, publisher, year_published, total_copies, available_copies, shelf_location)
  • UPDATE (modify book attributes, increase/decrease total/available copies; soft-delete with is_deleted = 1)
• library_issues:
  • SELECT (borrow logs history)
  • INSERT (borrow book copy: uid, book_id, user_id, issue_date, due_date, status = 'issued', issued_by)
  • UPDATE (return book: set return_date, status = 'returned'|'lost')
• library_reservations:
  • SELECT (booking reserves lists)
  • INSERT (reserve copies: uid, book_id, user_id, notes)
  • UPDATE (auto-fulfill when book is issued: set status = 'fulfilled'; cancel reservation: set status = 'cancelled')
• library_fines:
  • SELECT (fine accounts details)
  • INSERT (fine citation: uid, issue_id, user_id, amount, reason, status = 'unpaid')
  • UPDATE (pay/waive: set status = 'paid'|'waived')
• users:
  • SELECT (verify member roles)

33. marks.controller.js

• assignments:
  • SELECT (caching max score scales verification checks)
• users:
  • SELECT (caching student roles checks)
• submissions:
  • SELECT (find existing submission matching student/assignment)
  • INSERT (create submission: uid, assignment_id, student_id, status = 'graded', grade, feedback, graded_by, graded_at)
  • UPDATE (grade modification: grade, feedback, graded_by, graded_at, status = 'graded')

34. medical.controller.js

• student_medical_profiles:
  • SELECT (retrieve student health profile cards)
  • INSERT (create profile: uid, student_id, blood_group, allergies, dietary_restrictions, contraindications, chronic_conditions, emergency_instructions, updated_by)
  • UPDATE (modify profile settings, emergency contacts; update last modifier updated_by)
• student_medication_logs:
  • SELECT (list administrations history)
  • INSERT (record dispensation: uid, student_id, medication_name, dosage, administered_at, administered_by, reason, notes)
• student_medical_history:
  • SELECT (illness/injury history)
  • INSERT (record diagnostic event: uid, student_id, event_type, description, severity, onset_date, resolution_date, treatment_details, doctor_notes, is_visible_to_teachers, reported_by)
• users, parent_students, enrollments, classes:
  • SELECT (verify student access scope boundaries)

35. messages.controller.js

• messages:
  • SELECT (inbox/sent directories index, conversations threads)
  • INSERT (send direct/group/announcement message: uid, sender_id, recipient_id, body, subject, is_announcement, attachment_url, attachment_name, attachment_type)
  • UPDATE (mark read: is_read = 1; mark delivered: is_delivered = 1; soft-delete with is_deleted = 1)
• chat_groups:
  • SELECT (conversations lists)
• chat_group_members:
  • SELECT (membership access checks)
• clubs, club_chats, club_memberships:
  • SELECT (extracurricular messages thread index)
• users:
  • SELECT (recipient search directories)

36. notices.controller.js

• notices:
  • SELECT (pinboard index, detail fetch with audience filters)
  • INSERT (create notice: uid, title, content, category, priority, audience, is_pinned, created_by, expiry_date)
  • UPDATE (modify notice attributes; soft-delete with is_deleted = 1)
• users:
  • SELECT (join creator names)

37. payments.controller.js

• payments:
  • SELECT (lists of invoices paid)
  • INSERT (record transaction payment: uid, student_fee_id, amount, payment_method, transaction_reference, payment_date, created_by, sync_status = 'pending')
  • UPDATE (modify notes details; soft-delete with is_deleted = 1)
• student_fees:
  • SELECT (check fee balances), UPDATE (increment paid_amount, modify status to 'paid' / 'partial')
• users:
  • SELECT (validate student name)

38. reports.controller.js

(Note: Completely READ-ONLY SELECT operations)

• grades, attendance_new, student_fees, enrollments, users, classes, subjects:
  • SELECT (aggregate term averages, attendance percentages, unpaid balances summaries)

39. schoolSettings.controller.js

• school_settings:
  • SELECT (get system details)
  • INSERT / UPDATE (upsert global key-value preferences: setting_key, setting_value, category, updated_by)

40. settings.controller.js

• settings:
  • SELECT (list system configuration keys)
  • INSERT / UPDATE (upsert preferences: key, value, category, description)

41. social.controller.js

• posts:
  • SELECT (feed index)
  • INSERT (create social post: uid, author_id, content, image_url)
  • UPDATE (modify post; soft-delete with is_deleted = 1)
• post_comments:
  • SELECT (comments for post)
  • INSERT (post comment: uid, post_id, author_id, content)
  • UPDATE (soft-delete with is_deleted = 1)
• post_likes:
  • SELECT (likes count checks)
  • INSERT (like a post: uid, post_id, user_id)
  • DELETE (unlike a post: remove row matching user/post)
• users:
  • SELECT (join author names)

42. staff-attendance.controller.js

• staff_attendance:
  • SELECT (attendance status details roster checklist)
  • INSERT / UPDATE (bulk upsert checklist logs: uid, staff_id, date, status, remarks, marked_by, sync_status = 'pending')
• users:
  • SELECT (joining active staff names)

43. students-fees.controller.js

(Note: Completely READ-ONLY SELECT operations)

• student_fees, fee_groups, fee_plans, student_fee_discounts, discounts, trip_payments, trips, users, parent_students:
  • SELECT (scoped lookup of child balances, travel bookings, installment plans)

44. students.controller.js

(Note: Completely READ-ONLY SELECT operations)

• users, parent_students, enrollments, subjects, grades, submissions, assignments, exam_attempts, exam_schedules, exam_groups, attendance_new:
  • SELECT (academic dashboard grade averages, term attendance percentages, exam schedule bounds)

45. subjects.controller.js

• subjects:
  • SELECT (list classes courses)
  • INSERT (create subject: uid, name, code, class_id, teacher_id, description, credit_hours)
  • UPDATE (modify subject details; soft-delete with is_deleted = 1)
• classes, users:
  • SELECT (validate bounds)

46. sync.controller.js

• SyncEngine Tables:
  • This controller initiates standard manual cloud sync cycles. Under the hood, the transaction engine targets all sync-aware tables having the sync_status column (including users, grades, attendance_new, student_fees, expenses, visitor_logs, notices, assignments, classes, etc.).
  • SELECT (fetch rows where sync_status = 'pending')
  • UPDATE (update target rows to sync_status = 'synced' or sync_status = 'conflict' upon completion)

47. sysadmin.controller.js

(Note: Technical infrastructure telemetry and diagnostics)

• audit_logs:
  • SELECT (count active logins last 24h, list recent technical audit lines)
• sqlite_master:
  • SELECT (find tables containing sync_status column to verify conflicts)

48. teacher.controller.js

• syllabuses:
  • SELECT (list syllabus catalog filterable by subject)
  • INSERT (create syllabus: uid, subject_id, title, description, file_path, version, created_by)
• schemes_of_work:
  • SELECT (list schemes)
  • INSERT (create scheme: uid, subject_id, teacher_id, term, academic_year, content)
• focus_points:
  • SELECT (topic items catalog)
  • INSERT (create focus point: uid, scheme_id, topic, objectives, key_concepts, resources_needed)
• lesson_plans:
  • SELECT (lesson plans details lists)
  • INSERT (create plan: uid, teacher_id, subject_id, scheme_id, focus_point_id, date, topic, objectives, introduction, development, conclusion, assessment_method, homework, reflections)
• departments, subjects_new, users:
  • SELECT (verify teacher departments constraints)

49. transport-attendance.controller.js

• transport_attendance:
  • SELECT (attendance logs lists)
  • INSERT / UPDATE (bulk upsert roll-call logs matching (route_id, student_id, date))
• routes, users, parent_students, transport_allocations:
  • SELECT (check active student allocations on route)

50. transport.controller.js

• vehicles:
  • SELECT (list vehicles catalog)
  • INSERT (create vehicle: uid, registration_number, model, capacity, vehicle_type, fuel_type, status = 'active', description)
• routes:
  • SELECT (list routes catalog)
  • INSERT (create route: uid, name, code, start_point, end_point, distance_km, estimated_time_minutes, status = 'active', description)
• vehicle_routes:
  • SELECT (active assignments catalog)
  • INSERT (create assignment: uid, vehicle_id, route_id, driver_id, start_time = '07:00', end_time = '16:00', is_active = 1)
  • UPDATE (modify vehicle/driver details)
• transport_allocations:
  • SELECT (active student passenger rolls)
  • INSERT (allocate student passenger: uid, student_id, route_id, pickup_point_id, vehicle_route_id, fee_amount, effective_from, effective_to, is_active = 1)
  • UPDATE (deallocate passenger: set is_active = 0, is_deleted = 1)
• pickup_points:
  • SELECT (list pickup locations)
• transport_attendance:
  • SELECT (list attendance)
  • INSERT / UPDATE (bulk upsert attendance matching (route_id, student_id, date))
• users:
  • SELECT (verify drivers/students)

51. users.controller.js

• users:
  • SELECT (list directory, authentication detail fetch)
  • INSERT (register user: uid, email, password, role, first_name, last_name, phone, is_active = 1, created_at)
  • UPDATE (modify user details, profile_image, active status, reset password; soft-delete with is_deleted = 1)
• parent_students:
  • SELECT (check linkages)
  • INSERT (link child student to parent: uid, parent_id, student_id)
  • UPDATE (unlink student: soft-delete with is_deleted = 1)