Assessment Module

The Assessment module is a comprehensive evaluation system for the Comdeall platform that manages the complete lifecycle of child developmental assessments. It handles assessment creation, question management, assignment to children, completion tracking, and automatic notification workflows for therapists and parents to monitor a child's developmental progress.

Table of Contents

1. Module Structure
2. Assessment Endpoints
3. Core Features
4. Assessment Lifecycle
5. Question Management
6. Assignment System
7. Subscription Integration
8. Database Triggers & Functions
9. Notification System
10. Data Models
11. Security & Validation

---

Module Structure

The Assessment module follows a layered architecture pattern:

@Module({
  imports: [DBModule, AuthModule, BackgroundModule],
  controllers: [AssessmentController],
  providers: [AssessmentService, JwtService],
})
export class AssessmentModule {}

Components:

• AssessmentController: API endpoints and request handling
• AssessmentService: Business logic and validation
• AssessmentDBService: Database abstraction layer
• AssessmentRepository: Data access and raw queries
• BackgroundServiceManager: Notification jobs and async processing

---

Assessment Endpoints

Core Assessment Operations

Endpoint	Method	Description	Auth Required
/create-assessment	POST	Create new assessment	No
/update-assessment	POST	Update existing assessment	No
/assign-assessment	POST	Assign assessment to child	JWT + Roles
/get-all-child-assessments	POST	Fetch child's assessments	JWT
/assessment-completion	POST	Handle completion webhook	None

Questions Management

Endpoint	Method	Description	Auth Required
/create-question	POST	Add question to assessment	No
/update-question	POST	Update existing question	No

---

Core Features

1. Assessment Creation & Management

• Multi-field assessments with rich metadata (name, description, tags, age ranges)
• Media integration with validation for images and question attachments
• Specialty targeting for specific therapist types
• Subscription-based access control
• Lesson plan linking for targeted interventions

2. Question Types & Validation

enum AnswerType {
  SINGLE_CHOICE = "SINGLE_CHOICE",
  MULTIPLE_CHOICE = "MULTIPLE_CHOICE", 
  TEXT_INPUT = "TEXT_INPUT",
  SCALE = "SCALE"
}

3. Assignment Logic

• Subscription verification before assignment
• Duplicate prevention for already assigned assessments
• Bulk assignment with individual validation
• Role-based assignment (Admin/Therapist only)

4. Smart Filtering System

• Age-based filtering using child's birth date
• Specialty matching for therapist-specific assessments
• Completion status tracking
• Domain filtering by assessment type
• Subscription plan compatibility

---

Assessment Lifecycle

1. Creation Phase

// Validation steps during creation:
1. Verify subscription plans exist
2. Validate media attachments
3. Check lesson plan references
4. Create assessment with questions
5. Link specialties and subscriptions

2. Assignment Phase

// Assignment validation:
1. Check child subscription features
2. Verify assessment exists
3. Prevent duplicate assignments
4. Create child_assessment record

3. Completion Phase

// Multiple automated workflows:
1. Webhook notification to backend
2. Database trigger for lesson plan assignment
3. Therapist notifications for review
4. Parent notifications for completion

---

Question Management

Question Structure

interface QuestionData {
  order: number;
  text: string;
  answer_type: AnswerType;
  isRequired: boolean;
  section?: string;
  description?: string;
  lesson_plan_id?: string;
  options: string[];
  question_media: string[];
}

Media Validation

• Existence check for all referenced media IDs
• Count validation to ensure all media exists
• Cleanup handling for media replacement

Option Management

• Dynamic options based on question type
• Validation for required vs optional questions
• Update logic with existing option cleanup

---

Assignment System

Subscription Feature Validation

// Checks if child has assessment assignment feature
async allowedMapping(child_id: string): Promise<boolean> {
  // 1. Get child's active subscriptions
  // 2. Extract subscription features
  // 3. Verify ASSESSMENT_ASSIGNMENT feature
  // 4. Return authorization status
}

Assignment Rules

• Parent access: Only own children
• Therapist access: Children with matching specialties
• Admin access: All children
• Subscription validation: Feature-based permission

Bulk Assignment Logic

// Handles multiple assessments efficiently:
1. Validate all assessments exist
2. Check existing assignments
3. Create only new assignments
4. Return summary of actions taken

---

Subscription Integration

Feature-Based Access Control

enum SubscriptionFeature {
  ASSESSMENT_ASSIGNMENT = "ASSESSMENT_ASSIGNMENT"
}

Access Matrix

User Role	Access Level	Restrictions
Parent	Own children only	Must have subscription
Therapist	Assigned children	Specialty matching
Admin	All children	No restrictions

Free Plan Integration

• Always includes free plan assessments
• Combines with paid subscription plans
• Removes duplicates across plans

---

Database Triggers & Functions

1. Auto Lesson Plan Assignment Trigger

Function: auto_assign_lesson_plans_on_assessment_completion() Trigger: auto_assign_lesson_plans_trigger

Purpose: Automatically assigns lesson plans based on poor assessment scores

CREATE TRIGGER auto_assign_lesson_plans_trigger
AFTER INSERT OR UPDATE ON assessment_response
FOR EACH ROW
EXECUTE FUNCTION auto_assign_lesson_plans_on_assessment_completion();

Logic Flow:

1. Triggers on: Assessment completion (status = 'COMPLETED')
2. Assessment Types: Only processes ORO, PLS, and CDDC assessments
3. Score Analysis: Identifies questions with poor scores (scale responses ≤ 2)
4. Lesson Plan Assignment: Automatically assigns linked lesson plans for remediation
5. Duplicate Prevention: Checks existing assignments before creating new ones
6. Progress Tracking: Creates child_lesson_plan_progress records with source = 'GENERATED'

Key Features:

• Smart filtering by assessment type and score thresholds
• Order preservation using question order for lesson plan priority
• Bulk processing for efficient database operations
• Audit trail with detailed logging of assignments

2. Assessment Response Event Trigger

Hasura Event Trigger: assessmentCompleted Webhook: http://webserver/api/assessment/assessment/webhook/assessment-completion

Configuration:

event_triggers:
  - name: assessmentCompleted
    definition:
      insert:
        columns: '*'
      update:
        columns:
          - status
    webhook: http://webserver/api/assessment/assessment/webhook/assessment-completion

Purpose: Notifies therapists when assessments are completed

Workflow:

1. Event Detection: Triggered on assessment_response status changes
2. Therapist Matching: Finds therapists with specialties matching the assessment
3. Notification Dispatch: Sends personalized notifications via background jobs
4. Child Context: Includes child name for personalized messaging

---

Notification System

Assessment Completion Workflow

// Triggered by Hasura webhook
handleAssessmentCompletedEvent() {
  1. Validate completion event
  2. Get child name for personalization
  3. Find therapists with matching specialties
  4. Send targeted notifications
  5. Log notification delivery
}

Notification Targeting

• Specialty matching: Only notify relevant therapists
• Personalization: Include child name when available
• Delivery tracking: Background job processing
• Fallback handling: Graceful degradation for missing data

Dual Notification Strategy

1. Real-time notifications via webhook for immediate therapist alerts
2. Lesson plan assignments via database trigger for automated intervention

---

Data Models

Core Assessment Model

interface Assessment {
  id: string;
  name: string;
  description: string;
  tags: string[];
  key_pointers: string;
  min_age: number;
  max_age: number;
  approx_time: number;
  is_private: boolean;
  type: string; // ORO, PLS, CDDC, etc.
  image: string;
  language_id: string;
}

Assignment Tracking

interface ChildAssessment {
  child_id: string;
  assessment_id: string;
  assigned_by: UserRole;
  status: UserAssessmentStatus;
  created_at: Date;
  completed_at?: Date;
}

Response Data

interface AssessmentResponse {
  id: string;
  assessment_id: string;
  child_id: string;
  status: 'IN_PROGRESS' | 'COMPLETED';
  taken_by: string;
  report_media_id?: string;
  consolidate_report_media_id?: string;
}

Status Management

enum UserAssessmentStatus {
  IN_PROGRESS = "IN_PROGRESS",
  COMPLETED = "COMPLETED"
}

---

Security & Validation

Input Validation

• DTO validation using class-validator decorators
• UUID validation for all entity references
• Media existence verification before processing
• Subscription verification for feature access

Authorization Patterns

@Roles(UserRole.ADMIN, UserRole.THERAPIST)
@Auth(AuthType.JWT)

Database Security

• Row-level security in Hasura for role-based data access
• Foreign key constraints with CASCADE operations for data integrity
• Trigger-based validation for business rule enforcement

Error Handling

• Structured error responses with specific messages
• Validation failure handling with detailed feedback
• Database constraint violation management
• Graceful degradation for missing dependencies

---

Key Implementation Details

Age-Based Filtering

// Converts birth date to months for comparison
const childAge = getAgeInMonths(child.dob);

// Filters assessments based on age ranges
age_filter.includes(childAge)

Media Management

// Validates all media exists before processing
const db_media_count = await getMediaCount(question_media);
if (db_media_count !== question_media.length) {
  throw new BadRequestException("MEDIA_NOT_FOUND");
}

Subscription Validation

// Checks subscription features for assignment permission
const hasFeature = child_subscribed_features.includes(
  SubscriptionFeature.ASSESSMENT_ASSIGNMENT
);

Trigger-Based Automation

The Assessment module leverages PostgreSQL triggers for critical automation:

• Immediate lesson plan assignment based on assessment results
• Automatic progress tracking with proper source attribution
• Real-time notifications for stakeholder engagement

The Assessment module provides a robust, scalable system for managing developmental assessments with comprehensive validation, role-based access control, intelligent automation through database triggers, and multi-channel notification systems to support child development tracking across the Comdeall platform.

---

Conclusion

The Assessment module serves as a critical component for developmental evaluation in the Comdeall ecosystem, providing therapists and parents with powerful tools to track, assign, and monitor child assessments while maintaining strict security and subscription-based access controls. The integration of database triggers and Hasura event systems ensures automated workflows for lesson plan assignments and stakeholder notifications, creating a comprehensive assessment management system.