Skip to content
NHCarrigan Logo NHCarrigan Docs

Gwen Abalise

Gwen Abalise (hereinafter the “Application”) is a Discord bot that provides a private thread-based ticketing system for Discord communities. The bot enables users to create support tickets through a simple button interface, with tickets managed as private threads that include designated support staff roles.

1. User Documentation

This section is for those interacting with a live instance of the Application.

Getting Started

To use Gwen Abalise, add her to your Discord server.

Commands

The bot provides three slash commands:

  • /about - Learn more about the bot, including version information and helpful links
  • /start <channel> - Set up the ticket system in a specified text channel (requires MANAGE_GUILD permission)
  • /role <role> - Configure which role should be pinged and added to new tickets (requires MANAGE_GUILD permission)

Ticket System

The ticketing system works through a simple button interface:

  1. Administrators use /start to place a “Create Ticket” button in a channel
  2. Users click the button to open a private thread ticket
  3. The designated support role is automatically added to the thread
  4. Support staff can close tickets using the “Close Ticket” button within threads

Subscription Model

The bot operates on a subscription model with Discord’s premium features:

  • Servers require an active subscription to use the ticketing functionality
  • Entitled guilds (configured in the codebase) have access without subscription
  • Non-subscribed servers receive prompts to subscribe with premium buttons

2. Technical Documentation

This section is for those interested in running their own instance of the Application.

Architecture

The application is built with:

  • Runtime: Node.js with TypeScript
  • Discord Library: discord.js v14
  • Database: MongoDB with Prisma ORM
  • Web Server: Fastify (for health monitoring and landing page)
  • Logging: Custom logger utility

Core Components

Commands (src/commands/)

Command definitions for Discord slash commands:

  • about.ts - Bot information command
  • role.ts - Support role configuration command
  • start.ts - Ticket system initialization command

Modules (src/modules/)

Business logic implementations:

  • about.ts - Displays bot information with action buttons
  • close.ts - Handles ticket closure and thread management
  • open.ts - Creates new ticket threads and database records
  • role.ts - Manages support role configuration
  • start.ts - Sets up ticket creation interface in channels

Utilities (src/utils/)

  • isSubscribed.ts - Validates server subscription status
  • logger.ts - Logging functionality
  • replyToError.ts - Error handling for interactions

Database Schema

Two main models:

  • Tickets - Tracks ticket state (open/closed), thread IDs, and user associations
  • Roles - Maps server IDs to their designated support role IDs

Web Server (src/server/)

Provides health monitoring endpoint and informational landing page at port 5012.

Environment Requirements

  • DISCORD_TOKEN - Bot token from Discord Developer Portal
  • MONGO_URI - MongoDB connection string
  • npm_package_version - Automatically set by npm for version display

Permissions

The bot requires these Discord permissions:

  • Send Messages
  • Create Private Threads
  • Manage Threads
  • Use Slash Commands

This section is for expansions to our legal policies specific to the Application.

4. Contributing Documentation

This section is for documentation related to contributing to the Application’s codebase.

Development Setup

The project uses:

  • TypeScript with strict configuration
  • ESLint with @nhcarrigan/eslint-config
  • Prisma for database management
  • Vitest for testing (tests not yet implemented)
  • pnpm for package management

Build Process

Terminal window
pnpm build    # Compiles TypeScript to prod/ directory
pnpm lint     # Runs ESLint with zero warnings policy
pnpm start    # Runs the compiled application with 1Password secrets

Code Structure

The codebase follows a modular architecture with clear separation between:

  • Command definitions (registration data)
  • Command implementations (business logic)
  • Utility functions (shared functionality)
  • Database models (data persistence)
  • Web server (health monitoring)