SKOLE-ENGG — Engagement Module (Comments & Reactions)

Module ID: SKOLE-ENGG | Version: 1.0 | Status: Active
Products: Parent App (comment + react) · Teacher App (implicitly via engagement endpoints)

1. Overview

Field	Value
Module Name	Engagement
Module Code	ENGG
Business Value	Increases parent-school interaction quality. Parents can acknowledge, praise, or ask clarifying questions on activities, diary entries, and notices — all without leaving the app.

Scope In

Comments on any entity (activity, diary, write_to, noticeboard)
Reactions (like, love) on any entity
Reaction toggle (add if not exists, remove if already reacted)
Comment listing per entity

Scope Out

Moderating/flagging comments
Teacher commenting (API available but UI not yet built in teacher app)

2. Requirements

Functional Requirements (FR)

What the module must DO — actions, behaviors, and outcomes.

SKOLE-ENGG-FR001: The module shall allow parents to post comments on activities, diary entries, notices, and requests.
SKOLE-ENGG-FR002: The module shall enable parents to list all comments associated with a specific entity.
SKOLE-ENGG-FR003: The module shall allow parents to toggle reactions (like, love) on any supported entity.
SKOLE-ENGG-FR004: The module shall behave as a toggle when a parent reacts with the same type again, removing the previous reaction.
SKOLE-ENGG-FR005: The module shall show real-time reaction counts and the current user’s reaction state per entity.

Non-Functional Requirements (NFR)

How well the module must do it — performance, security, and reliability.

SKOLE-ENGG-NFR001: The module shall perform secure data scoping by ensuring all engagement records are partitioned by skole_id.
SKOLE-ENGG-NFR002: The module shall behave strictly by enforcing a unique constraint on the parent+entity+reaction type combination.
SKOLE-ENGG-NFR003: The module shall ensure that engagement queries (comments/reactions) are performant even for high-activity entities.

Constraints

Rules and boundaries — tech choices and platform restrictions.

C001: We must implement a generic entity-linking schema (entity_type + entity_id) to allow the engagement module to support new modules without schema changes.
C002: We must use a @@unique constraint on [entity_type, entity_id, parent_id, staff_id] to prevent duplicate engagement records.

3. Sub-modules / Backlog

ID	Sub-module	Priority	Status	Estimate	Linked FR
`SKOLE-ENGG-SM001`	Comment system	P1	Done	2d	FR001–FR002
`SKOLE-ENGG-SM002`	Reaction system	P1	Done	2d	FR003–FR005

4. Logical Implementation

Comment Flow

POST /parent-app/engagement/comment
  { entity_type, entity_id, content }
  -- INSERT comments (skole_id from JWT, parent_id from JWT sub)

GET /parent-app/engagement/comments/:type/:id
  -- SELECT * FROM comments WHERE entity_type = ? AND entity_id = ?
     AND deleted_status = 0 ORDER BY created_at ASC

Reaction Toggle Flow

POST /parent-app/engagement/react
  { entity_type, entity_id, reaction_type }
  ├─ Try UPSERT into reactions (unique on entity_type+entity_id+parent_id+staff_id)
  ├─ If existing record matches reaction_type → DELETE (toggle off)
  └─ If new or different type → INSERT/UPDATE

5. UI Requirements

Engagement components are embedded within Activity, Diary, Noticeboard, and Write-To screens.

Components:

ID	Component	Props
`SKOLE-ENGG-UC001`	`CommentInput`	`entityType`, `entityId`, `onSubmit`, `loading`
`SKOLE-ENGG-UC002`	`CommentFeed`	`comments[]`, `currentParentId`
`SKOLE-ENGG-UC003`	`CommentBubble`	`comment`, `isOwn`
`SKOLE-ENGG-UC004`	`ReactionBar`	`reactions`, `onReact`, `myReaction`
`SKOLE-ENGG-UC005`	`ReactionCount`	`likeCount`, `loveCount`

6. Conditional Expressions

ID	Expression	Trigger	True Action	False Action
`SKOLE-ENGG-CE001`	`existingReaction && reaction_type === same`	POST react	Delete reaction (toggle off)	Upsert reaction
`SKOLE-ENGG-CE002`	`myReaction === 'like'`	ReactionBar render	Filled like icon	Outline like icon
`SKOLE-ENGG-CE003`	`myReaction === 'love'`	ReactionBar render	Filled love icon	Outline love icon
`SKOLE-ENGG-CE004`	`comment.parent_id === jwt.sub`	CommentBubble	Align right, own color	Align left
`SKOLE-ENGG-CE005`	`comment.deleted_status === 1`	Comment query	Exclude	Include

7. Internal Module Connections

Direction	Module	Data / Event	Condition
ENGG → ACTV	Activities	Comments/reactions attach via entity_type=‘activity’	On engage
ENGG → DIRY	Diary	Comments/reactions via entity_type=‘diary’	On engage
ENGG → WRIT	Write-To	Comments via entity_type=‘write_to’	On engage
ENGG → NOTB	Noticeboard	Reactions via entity_type=‘noticeboard’	On react

8. Database Tables

ID	Table	Role
`SKOLE-ENGG-TB001`	`comments`	Comments on any entity
`SKOLE-ENGG-TB002`	`reactions`	Like/love reactions per entity

`reactions` Unique Constraint

@@unique([entity_type, entity_id, parent_id, staff_id])

This ensures one reaction per user+entity. Toggle is handled at service layer.

9. API Endpoints

ID	Method	Route	Auth	Description
`SKOLE-ENGG-EP001`	POST	`/parent-app/engagement/comment`	JWT (parent)	Post comment
`SKOLE-ENGG-EP002`	GET	`/parent-app/engagement/comments/:type/:id`	JWT (parent)	List comments
`SKOLE-ENGG-EP003`	POST	`/parent-app/engagement/react`	JWT (parent)	Toggle reaction
`SKOLE-ENGG-EP004`	GET	`/parent-app/engagement/reactions/:type/:id`	JWT (parent)	Reaction counts + own state

​SKOLE-ENGG — Engagement Module (Comments & Reactions)

​1. Overview

​Scope In

​Scope Out

​2. Requirements

​Functional Requirements (FR)

​Non-Functional Requirements (NFR)

​Constraints

​3. Sub-modules / Backlog

​4. Logical Implementation

​Comment Flow

​Reaction Toggle Flow

​5. UI Requirements

​6. Conditional Expressions

​7. Internal Module Connections

​8. Database Tables

​reactions Unique Constraint

​9. API Endpoints