Learn_System/docs/classroom-split-plan.md

classroomController.js split plan

Source: backend/src/controllers/classroomController.js — 1618 lines, 70 functions
Target: backend/src/controllers/classroom/ — 8 files
Strategy: pure mechanical split, no behaviour changes, facade preserves compatibility

---

Target structure

backend/src/controllers/
  classroomController.js          ← 8-line re-export facade (unchanged public API)
  classroom/
    _shared.js                    ← shared helpers used by multiple files
    sessions.js                   ← session lifecycle + guest tokens
    strokes.js                    ← whiteboard strokes + cursor preview
    pages.js                      ← page CRUD + templates + board theme
    chat.js                       ← chat messages, reactions, attachments, export
    permissions.js                ← draw permissions, hand-raise, mute, screen, attendance
    sim.js                        ← simulation relay (simOpen/State/Mode/Annotate/Close)
    admin.js                      ← history, notes, templates, admin views

---

File mapping

classroom/_shared.js

Helpers used by 2+ files. Exports: { GUEST_EVENTS, emitToSession, hasAccess, canDraw }

Symbol	Lines	Used by
GUEST_EVENTS	21–27	sessions, strokes, pages, permissions, sim
emitToSession	31–34	sessions, strokes, pages, chat, permissions, sim
hasAccess	37–48	sessions, strokes, pages, chat, permissions, admin
canDraw	13–18	strokes

Imports: db, broadcastToSession from ws-server

---

classroom/sessions.js

Session lifecycle, signal (WebRTC), guest tokens.

Function	Lines
createSession	51–105
getSession	106–128
endSession	129–145
getActiveSession	146–163
getMyActive	164–177
joinSession	178–210
leaveSession	211–231
getMySession	385–433
signal	359–384
generateGuestToken	1520–1531
revokeGuestToken	1532–1542
getGuestToken	1543–end

Imports: db, crypto, invalidateSession, emitToUser (from ws-server), _shared

---

classroom/strokes.js

Whiteboard stroke CRUD + live cursor/preview broadcast.

Function	Lines
postStrokes	568–608
getStrokes	609–635
updateStroke	636–662
deleteStroke	663–686
clearPage	687–700
previewStroke	815–840
broadcastCursor	901–918

Imports: db, _shared

---

classroom/pages.js

Page CRUD, templates, board theme.

Function	Lines
getPages	701–723
addPage	449–472
changePage	473–488
updatePageTemplate	489–503
updateBoardTheme	504–518
renamePage	724–740
duplicatePage	741–769
deletePage	770–799

Imports: db, _shared

---

classroom/chat.js

Chat messages, reactions, file attachments, export, CHAT_UPLOADS_DIR setup.

Symbol	Lines
CHAT_UPLOADS_DIR	9–10
ALLOWED_REACTIONS	1027
sendChat	232–268
getChat	269–320
pinMessage	841–864
reactToMessage	1028–1074
uploadChatAttachment	1019–1026
exportChat	1244–1275

Imports: db, path, fs, crypto, emitToUser (from ws-server), _shared

---

classroom/permissions.js

Draw permits, hand-raise, mute, screen share, online students.

Function	Lines
getParticipants	321–340
getAttendance	341–358
getOnlineStudents	434–448
raiseHand	519–537
lowerHand	538–550
getHands	551–567
allowDraw	865–882
revokeDraw	883–900
mutePeer	800–814
screenStart	919–930
screenStop	931–941

Imports: db, emitToUser, invalidateDrawCache (from ws-server), getOnlineUserIds (from sse), _shared

---

classroom/sim.js

Simulation relay — teacher broadcasts sim events to students.

Function	Lines
simOpen	945–958
simState	961–976
simMode	979–991
simAnnotate	994–1004
simClose	1007–1018

Imports: db, _shared

---

classroom/admin.js

History, notes, board templates, admin dashboards.

Function	Lines
getNotes	1075–1082
saveNotes	1083–1097
getClassHistory	1098–1140
getMyHistory	1141–1188
getSessionSummary	1189–1243
getAllNotes	1276–1294
deleteHistorySession	1295–1320
adminGetActiveSessions	1321–1341
adminGetAllSessions	1342–1422
adminGetTeachersList	1423–1434
getTemplates	1435–1441
saveTemplate	1442–1473
deleteTemplate	1474–1479
loadTemplate	1480–1519

Imports: db, _shared

---

Facade (classroomController.js after split)

module.exports = {
  ...require('./classroom/sessions'),
  ...require('./classroom/strokes'),
  ...require('./classroom/pages'),
  ...require('./classroom/chat'),
  ...require('./classroom/permissions'),
  ...require('./classroom/sim'),
  ...require('./classroom/admin'),
};

routes/classroom.js imports from '../controllers/classroomController' — unchanged.

---

What does NOT change

• All function names — unchanged
• All route bindings in routes/classroom.js — unchanged
• All public exports from classroomController.js — same set
• DB queries — moved verbatim, not rewritten
• Error responses — unchanged

Risks

• simClose (line 1007) references emitToSession — must be imported from _shared
• sendChat builds URLs with req.protocol + '://' + req.get('host') — needs no extra imports
• getSessionSummary (line 1189) is 54 lines — complex, move carefully