Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Support Module

The Support module provides a ticket-based customer support system enabling two-way communication between users and administrators. It handles ticket creation, message threading, status management, and access control for both user-facing and admin-facing operations.

Core Features

Ticket Management

Tickets are conversation threads with lifecycle management:

  • Priority Levels: Three priority levels (Low, Medium, High) to help admins triage support requests
  • Status Transitions: Automatic status updates based on who sends messages (Open → Pending → Resolved → Closed)
  • Ownership Validation: Each ticket is tied to a specific user; access control ensures users can only see their own tickets
  • Title-based Organization: Each ticket has a title for quick identification in lists

Messaging System

Real-time threaded messaging within tickets:

  • Dual-author Model: Messages can be authored by either users or admins (never both on same message)
  • Message Editing: Both users and admins can edit their own messages (with edit timestamp tracking)
  • Admin-only Deletion: Admins can delete their own messages only (not for general moderation)
  • Status-aware Sending: Messages cannot be sent to Resolved or Closed tickets

Message Lists

Messages are returned with a simple limit-based approach:

  • User-facing API: Returns messages with enriched author metadata (name, avatar, email) via FrontendTicketMessage type
  • Admin-facing API: Returns plain TicketMessage objects without enriched metadata
  • Default Limit: Both APIs use a 100-message limit per request

Architecture

Services

The module exposes two gRPC services:

  1. SupportService: User-facing API for creating tickets, viewing own tickets, sending messages, and closing own tickets
  2. SupportAdminService: Admin-facing API with capabilities including viewing all tickets, sending responses, editing/deleting own messages, and manually resolving/closing any ticket

All service methods follow the Processor pattern for consistency with the rest of the codebase.

RBAC Integration

Admin operations integrate with the manage module’s role-based access control system:

  • Allowed Roles: SuperAdmin, Moderator, CustomerSupport, and SupportBot can access all admin operations
  • Audit Logging: All admin operations are automatically logged via the RecordedAdminOperation wrapper
  • Operation Validation: Each operation validates the admin’s role before execution

Status Transition Logic

Ticket statuses automatically transition based on message activity:

  • User sends message: Pending/Resolved tickets become Open (indicating new user activity requiring attention)
  • Admin replies: Open tickets become Pending (indicating admin has responded)
  • Admin closes ticket: Any non-Closed ticket can be closed manually
  • Closed/Resolved tickets: Cannot receive new messages (enforced by validation)

This state machine ensures tickets naturally reflect their support workflow status without manual updates.

Input Validation

The module includes comprehensive input validation:

  • Content validation: Message length limits, empty content checks (enforced at gRPC layer)
  • Ownership checks: Users can only access their own tickets and messages
  • Status checks: Operations respect ticket status (e.g., no messages on closed tickets)

Integration Points

With Auth and Manage Modules

  • Ticket ownership is tied to user UUIDs from the auth system
  • User authentication context is passed through auth::rpc::middleware::UserId to determine ticket access
  • Admin authentication is passed through manage::rpc::middleware::AdminId for admin operations
  • Admin authorization is verified through the manage module’s RBAC system

Database Schema

The module uses its own support PostgreSQL schema with:

  • ticket table: Core ticket data with status enum and priority enum
  • ticket_message table: Threaded messages with dual-author columns (user_author_id OR admin_author_id)
  • Foreign key relationships to auth module’s user tables

Development Notes

  • All APIs follow the Processor pattern (not OOP) [[memory:6079830]]
  • The module does NOT use static lifetimes for database connections [[memory:7107428]]
  • Ticket IDs are UUIDs, but message IDs are auto-incrementing integers for simpler database management
  • Message ownership validation happens at the service layer, not database layer
  • The FrontendTicketMessage type includes enriched author metadata (name, avatar, email) joined from auth module tables
  • Admin operations use the impl_recorded_admin_processor! macro to automatically wrap operations with audit logging