DAC Academy — Module Deep Dive

MODULE 1: AUTHENTICATION

Login Flow

1. User enters email + password + "Remember Me" checkbox
2. Validated via signInSchema (Zod)
3. Rate-limited to prevent brute force
4. If parent role → redirect to /parent/dashboard
5. All other roles → redirect to /dashboard

Session Management

• JWT-based sessions via Better Auth
• Role, branchId, hostelId embedded in JWT token
• Token validated on each request

Password Reset Flow

1. Enter email on /forgot-password
2. Rate-limited per email
3. Email sent with reset link → /update-password?token=X
4. Enter new password + confirm

Logout

• Session destroyed, redirect to /login

---

MODULE 2: DASHBOARD

Dashboard Metrics (Admin/Counselor View)

Dashboard Metrics (Warden View)

---

MODULE 3: LEADS (CRM)

Lead Status Definitions

Probability Levels

Registration Flow (from lead)

1. Staff clicks "Register" on lead detail
2. Enter: amount, payment mode, transaction ID, payment screenshot (optional)
3. System creates receipt + registration record in a single transaction
4. Receipt PDF generated and WhatsApp notification sent after completion

---

MODULE 4: ADMISSIONS

Admission Form Sections

1. Student Details — Name, class, target exam, DOB, gender
2. Contact Details — Parent phone (required), email, father/mother/guardian phone
3. Academic Info — Course, batch, board, school, address, Aadhaar (hashed)
4. Hostel — Admission type, hostel assignment, room/bed/locker
5. Fee & Payment — Fee overrides, amount paid, payment mode, transaction ID
6. Installments — Optional custom schedule; auto-generated from batch defaults if omitted
7. Documents — Checklist item completion with uploaded images
8. Admission Items — Optional custom items; uses defaults if omitted
9. Student Photo — Optional, uploaded to cloud storage

Fee Calculation

admissionFeePaise = form value or batch defaults hostelFee = form value or batch default (if hostel type) totalFee = admissionFee + hostelFee remaining = totalFee - amountPaid

Batch Capacity

• Enforced with row lock to prevent overselling
• If batch has capacity limit and is full → error

Parent Account Auto-Creation

• If email provided: existing user is linked, or new user created
• Temp password generated, email auto-verified

---

MODULE 5: STUDENTS

Student Statuses

Edit Guardrails

• Batch changes rejected — Must use Batch Transfer workflow
• Branch changes rejected — Must use dedicated transfer workflow
• Hostel allocation auto-syncs with admission type changes

Action Buttons

• Edit Profile, Batch Transfer, Promote, Re-enroll, Reinstate
• Mark Left, Mark TC Issued, Mark Removed, Mark Completed
• Reset Parent Password, Create Parent Account

---

MODULE 6: FEES

Fee Record Lifecycle

1. Created at admission with initial totals
2. Installments generated from batch schedule or manual
3. Payments recorded against installments
4. Ad-hoc fees added to increase total fee
5. Installments voided to reverse payment

Payment Modes

Financial Invariants (DB-Enforced)

• totalFeePaise = totalPaidPaise + remainingPaise
• totalPaidPaise <= totalFeePaise
• All amounts >= 0

---

MODULE 7: HOSTEL

Hostel Directory

• Paginated table of hostel students
• Warden: sees only own hostel; Admin: sees all

Outing Management

• Parent: Request outing, cancel pending, view history
• Warden/Admin: View queue, approve/reject, mark returned
• WhatsApp notifications sent on request and review

Medical Request Tab

• Filters: status, search, pagination
• Acknowledge button per request

---

MODULE 8: MEDICAL

Request Pipeline

1. Parent submits request with disease, medicine, dose
2. Status: pending — visible in warden/admin queue
3. Warden/admin acknowledges → status 'acknowledged'
4. Warden/admin completes → status 'completed'
5. OR rejects → status 'rejected' (reason required)

WhatsApp Notifications

• On acknowledgment: notification to parent

---

MODULE 9: SESSIONS

Session Lifecycle

1. Create — Admin creates new session (name, start/end dates)
2. Activate — Single session activation (deactivates all others)
3. Deactivate — Blocked if students enrolled in that session

Rules

• Only ONE session can be active at any time
• Session name format: YYYY-YY

---

MODULE 10: RECEIPTS

Receipt Number Format

KIND/FINANCIAL-YEAR/SEQUENCE Examples: ADM/2025-26/0042, REG/2025-26/0015

Receipt Types

Receipt Immutability

• Receipts CANNOT be updated or deleted
• Can be voided (business marker only — does not reverse finances)
• Financial reversals happen via installment voiding

---

MODULE 11: SETTINGS

Tabs

Academy — Name, GST enabled/rate/GSTIN Branches — CRUD with active/inactive toggle Courses — CRUD with active/inactive toggle Batches — CRUD with fee fields, payment schedule JSON, capacity Sessions — Create/activate/deactivate Hostels — CRUD per branch Checklist — Document checklist items for admission WhatsApp — Notification toggles and alert phone numbers

---

MODULE 12: ANNOUNCEMENTS

Targeting

• Role, branch, course, batch, hostel status, class, status, admission type

Parent View

• Only matching announcements shown
• Parents see announcements for ALL linked students

---

MODULE 13: AUDIT LOG

• Immutable: Strictly insert-only
• Before/After snapshots: JSONB of state before and after each change
• Admin only: No other role can view
• Filterable by entity type, action, date range, and text search

---

MODULE 14: WHATSAPP NOTIFICATIONS

Templates

Delivery Architecture

1. Business logic enqueues notification into jobs table
2. Cron processes the queue in batches
3. On success: marked completed
4. On failure: retried with backoff (max 3 attempts)

---

MODULE 15: PARENT PORTAL

Pages

• /parent/dashboard — Overview with students, fees, outings, medical, receipts, announcements
• /parent/hostel-outing — Request/View outings
• /parent/medical — Submit/View medical requests
• /parent/receipts — View receipts

Permissions

---

MODULE 16: WARDEN PORTAL

Pages

• /warden → Dashboard
• /warden/students — Hostel student directory
• /warden/medical — Medical request queue
• /warden/export — Data export