Support Module

The Support module is a comprehensive customer support system for the Comdeall platform that manages the complete lifecycle of support tickets, notes, and communication between users and administrators. It handles ticket creation, status management, note addition, automated notifications, and email workflows to provide efficient customer support for parents, therapists, and administrators.

Table of Contents

1. Module Structure
2. Support Endpoints
3. Core Features
4. Support Lifecycle
5. Database Functions & Triggers
6. Background Jobs & Notifications
7. Security & Authorization
8. Technical Implementation

---

Module Structure

@Module({
  imports: [BackgroundModule, DBModule],
  controllers: [SupportController],
  providers: [SupportService],
})
export class SupportModule {}

Architecture Components

• SupportController - REST API endpoints (/api/communication)
• SupportService - Business logic and workflow orchestration
• SupportDBService - Database operation abstraction layer
• SupportRepository - Raw database queries and data access

---

Support Endpoints

Method	Endpoint	Auth	Roles	Description
POST	/mark-ticket-resolved	JWT	ADMIN, THERAPIST, PARENT	Mark tickets as resolved
POST	/support/add-note	None	Webhook	Add note to ticket (Hasura webhook)

Mark Ticket Resolved

Resolves support tickets and triggers notifications.

// Request
{
  "input": {
    "ticket_ids": ["uuid1", "uuid2"]
  }
}

// Response
{
  "success": "SUCCESS",
  "message": "Tickets resolved successfully",
  "data": {}
}

Add Note Webhook

Hasura event trigger endpoint for note additions.

// Webhook Payload (Auto-generated by Hasura)
{
  "event": {
    "data": {
      "new": {
        "id": "note-uuid",
        "support_id": "ticket-uuid", 
        "description": "Note content",
        "created_at": "2024-01-01T00:00:00Z"
      }
    }
  }
}

---

Core Features

1. Ticket Management

• Multi-Role Creation - Parents, therapists, and admins can create tickets
• Subject Categorization - Predefined support subjects for organization
• Status Lifecycle - PENDING → RESOLVED workflow
• User Assignment - Tickets linked to specific users with role-based access

2. Note System

• Admin Notes - Administrators can add notes to any ticket
• Real-time Updates - Hasura event triggers for instant processing
• User Notifications - Automatic alerts when notes are added
• Email Integration - Email notifications for note additions

3. Notification Workflows

• Ticket Creation - Admin notifications for new tickets
• Note Addition - User notifications and emails
• Ticket Resolution - User notifications and email confirmations
• Multi-channel Delivery - Push notifications and email alerts

4. Access Control

• Role-based Permissions - Different access levels per user type
• Data Isolation - Users can only access their own tickets
• Admin Override - Full access for administrative users

---

Support Lifecycle

Ticket Creation Process

User Request → Subject Validation → User Verification → Ticket Creation → Admin Notification → Active Ticket

Key Steps:

1. Input Validation - Subject ID and description validation
2. Authorization Check - User role and session verification
3. Database Transaction - Ticket insertion with automatic ID generation
4. Admin Alerts - Notifications sent to all admin users
5. Response Generation - Ticket details returned to client

Note Addition Workflow

Admin Adds Note → Database Insert → Hasura Event Trigger → Webhook Call → User Notification → Email Sent

Processing Flow:

1. Note Creation - Admin adds note through Hasura console/GraphQL
2. Event Trigger - Automatic webhook trigger on database insert
3. Notification Processing - Background job for push notifications
4. Email Delivery - Template-based email to ticket owner

Resolution Process

Mark Resolved Request → Bulk Update → Status Change → User Notifications → Email Confirmations → Closed Tickets

Resolution Logic:

1. Batch Processing - Multiple tickets resolved simultaneously
2. Status Update - RESOLVED status with timestamp
3. Conditional Notifications - Only admin-resolved tickets trigger alerts
4. Email Templates - Standardized resolution confirmation emails

---

Database Functions & Triggers

Hasura Function: create_support_ticket

Custom function for secure ticket creation with built-in validation.

CREATE OR REPLACE FUNCTION create_support_ticket(
    hasura_session JSON,
    input_subject_id UUID,
    input_description TEXT
) RETURNS SETOF support_ticket

Function Features:

• Session Authentication - JWT token validation from Hasura session
• Role Authorization - ADMIN, THERAPIST, PARENT role verification
• Input Sanitization - Description trimming and validation
• Referential Integrity - User and subject existence verification
• Atomic Operations - Transaction-safe ticket creation
• Auto-notifications - Admin user notifications on creation

Error Handling:

• Unauthorized access attempts
• Missing or invalid subject IDs
• Empty descriptions
• Non-existent users or subjects

Event Trigger: addNoteSupportTicket

Real-time webhook trigger for note additions.

event_triggers:
  - name: addNoteSupportTicket
    definition:
      insert:
        columns: '*'
    webhook: http://webserver/api/communication/support/add-note
    retry_conf:
      num_retries: 10
      interval_sec: 10
      timeout_sec: 60

Trigger Configuration:

• Event Type - INSERT operations on notes table
• Webhook URL - Internal backend endpoint
• Retry Logic - 10 retries with 10-second intervals
• Payload Transform - Formatted event data structure

---

Background Jobs & Notifications

Email Templates

Support Ticket Resolved

JobName.SUPPORT_TICKET_RESOLVED_EMAIL
// Template: 'support-ticket-resolved'
// Triggers: When admin marks ticket as resolved
// Recipients: Ticket owner

Note Added

JobName.NOTE_ADDED_EMAIL  
// Template: 'note-added'
// Triggers: When admin adds note to ticket
// Recipients: Ticket owner
// Variables: Note content included

Push Notifications

Custom Notification System

// Ticket resolution notification
{
  user_ids: [ticket_owner_id],
  subject: "Support Ticket Resolved",
  description: "Your support ticket has been resolved by admin."
}

// Note addition notification  
{
  user_ids: [ticket_owner_id],
  subject: "New Note Added",
  description: "A new note has been added to your support ticket."
}

Background Processing

• Async Execution - Non-blocking notification delivery
• Retry Logic - Failed jobs automatically retried
• Queue Management - Redis-backed job queue system
• Error Handling - Failed notifications logged but don't block workflow

---

Security & Authorization

Permission Matrix

Resource	ADMIN	THERAPIST	PARENT	PUBLIC
Create Ticket	✗	✓	✓	✗
View Own Tickets	✗	✓	✓	✗
View All Tickets	✓	✗	✗	✗
Mark Resolved	✓	✗	✗	✗
Add Notes	✓	✗	✗	✗
Delete Tickets	✓	✗	✗	✗

Data Access Control

• Row-level Security - Users can only access their own tickets
• Role-based Filtering - Hasura permissions enforce access control
• Session Validation - JWT tokens required for authenticated operations
• Input Sanitization - All user inputs validated and sanitized

Webhook Security

• Internal Network - Webhook endpoints only accessible internally
• No Authentication - Hasura event triggers use internal communication
• Request Validation - Webhook payloads validated before processing

---

Technical Implementation

Service Architecture

@Injectable()
export class SupportService {
  async markAsResolved(ticket_ids: string[], user_data: UserData) {
    // Update ticket status in database
    await this.supportDBService.markAsResolved(ticket_ids);
    
    // Send notifications only for admin resolutions
    if (user_data.user_role === UserRole.ADMIN) {
      for (const id of ticket_ids) {
        const ticket = await this.supportDBService.getSupportTicket(id);
        // Queue notification and email jobs
        await this.queueNotifications(ticket);
      }
    }
  }
}

Repository Pattern

@Injectable() 
export class SupportRepository {
  async markAsResolved(ticket_ids: string[]) {
    return await this.prisma.support_ticket.updateMany({
      where: { id: { in: ticket_ids } },
      data: { 
        status: 'RESOLVED',
        resolved_at: new Date()
      }
    });
  }
}

Error Handling Strategy

• Validation Layers - Input validation at controller and service levels
• Database Constraints - Foreign key and check constraints enforce data integrity
• Exception Handling - Comprehensive try-catch blocks with detailed logging
• User Feedback - Clear error messages returned to clients
• Graceful Degradation - Core functionality continues even if notifications fail

---

This Support module provides a robust, scalable customer support system that integrates seamlessly with Comdeall's existing infrastructure, leveraging Hasura's real-time capabilities and comprehensive notification systems for efficient support management.