Notification Handler

Relevant source files

The following files were used as context for generating this wiki page:

• src/util/notificationHandler.ts
• src/db/db.ts
• src/commands/util/backend-manager.ts
• config.example.json
• src/util/logging/logAction.ts

The Notification Handler is a specialized utility system within the Poixpixel Discord Bot designed to manage and dispatch critical system-level alerts to bot administrators and staff. Its primary purpose is to ensure that infrastructure failures, such as database or cache connection issues, are immediately communicated to the relevant stakeholders via Direct Messages (DMs).

Unlike the general Audit Logging system which records server-wide events in a public channel, the Notification Handler focuses on the internal health of the bot and its backend services. It acts as an bridge between low-level database/Redis management and the human operators responsible for maintaining bot uptime.
Sources: src/util/notificationHandler.ts:1-15, src/db/db.ts:25-30

Architecture and Components

The system is built around a centralized dispatching mechanism that maps specific technical failure states to human-readable messages. It relies on the project's configuration to identify users with the "Manager" role and uses the Discord API to deliver private notifications.

Notification Types

Alerts are categorized by the NotificationType enumeration, covering three main domains: Redis connectivity, Database connectivity, and Bot lifecycle events.

Notification Type	Trigger Description	Severity
REDIS_CONNECTION_LOST	Bot fails to connect to Redis after multiple retries.	Warning
DATABASE_CONNECTION_LOST	Fatal failure to connect to PostgreSQL; triggers bot shutdown.	Critical
REDIS_CACHE_FLUSHED	Manual administrative action to clear the cache.	Info
BOT_RESTARTING	Triggered during planned system reboots.	Info
BOT_ERROR	Encountering a critical unhandled exception.	Critical

Sources: src/util/notificationHandler.ts:11-30, src/db/db.ts:515-525

Data Flow for Manager Notifications

When a system event occurs (e.g., in the database manager), the notifyManagers function is invoked. The following diagram illustrates the flow from a service failure to a manager receiving a DM.

The system ensures that only human users (non-bots) with the specific Manager role defined in config.json are notified.
Sources: src/util/notificationHandler.ts:60-120, config.example.json:80-85

Core Implementation Details

Manager Identification

The handler identifies recipients by searching for a role named "Manager" within the configured staff roles. It performs a guild member fetch to ensure the cache is up-to-date before filtering.

async function getManagers(guild: Guild): Promise<GuildMember[]> {
  const config = loadConfig();
  const managerRoleId = config.roles?.staffRoles?.find(
    (role) => role.name === 'Manager',
  )?.roleId;

  if (!managerRoleId) return [];

  await guild.members.fetch();
  return Array.from(
    guild.members.cache
      .filter((member) => member.roles.cache.has(managerRoleId) && !member.user.bot)
      .values(),
  );
}

Sources: src/util/notificationHandler.ts:59-86

Dispatch Mechanism

The notifyManagers function is the primary entry point. It constructs a message containing the base alert message, any custom details provided by the caller, and a Discord-formatted timestamp (e.g., <t:12345678:F>).

• Timestamping: Uses Math.floor(Date.now() / 1000) to create dynamic Discord timestamps that adapt to the viewer's timezone.
• Error Handling: If a DM fails for one manager (e.g., DMs disabled), the system logs the error and continues to the next manager in the list.
  Sources: src/util/notificationHandler.ts:46-52, src/util/notificationHandler.ts:95-135

System Integration

The Notification Handler is deeply integrated into the bot's backend management layers.

Database Integration

In src/db/db.ts, the database initializer tracks connectionAttempts. If MAX_DB_RETRY_ATTEMPTS is reached, it triggers a DATABASE_CONNECTION_LOST notification before exiting the process. Conversely, if a connection is restored after a previous failure, it sends a restoration alert.
Sources: src/db/db.ts:480-505, src/db/db.ts:510-520

Manual Backend Management

The backend-manager command allows administrators to manually trigger service reconnections or cache flushes. These actions utilize the Notification Handler to keep the staff informed of manual interventions.

Summary

The Notification Handler serves as a critical reliability component, ensuring that backend state changes and failures are not silent. By targeting specific human "Managers" through DMs and providing precise timestamps and error context, it enables rapid response to infrastructure issues that would otherwise render the bot non-functional.
Sources: src/util/notificationHandler.ts:140-155, src/db/db.ts:515-530