​

SKOLE-ENGG — Engagement Module (Comments & Reactions)

​

1. Overview

​

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)

• 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)

• 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

• 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

​

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.

​

6. Conditional Expressions

​

7. Internal Module Connections

​

8. Database Tables

​

reactions Unique Constraint

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

​

9. API Endpoints