Main Bot Application (app.ts)

Relevant source files

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

• src/app.ts
• src/interactions.ts
• src/env.ts
• package.json
• src/commands/join.ts
• docker-compose.prod.yml
• src/utils/AudioQueue.ts

The app.ts file is the main entry point and central orchestrator for the Discord Live Translator bot. It is responsible for initializing the Discord client, connecting to the Discord API, handling incoming slash command interactions, and managing the bot's lifecycle, including startup, error handling, and graceful shutdown. It integrates various modules, such as command handlers, environment configuration, and telemetry, to provide the bot's core functionality.

Sources: src/app.ts, package.json:3

Core Initialization

The application starts by creating a Discord.Client instance. This client is configured with specific intents required for the bot's operation: Guilds for server-related events and GuildVoiceStates to monitor users joining/leaving voice channels. The client logs in using the BOT_TOKEN from the environment variables.

Upon a successful connection, the ready event is fired. The bot logs its tag to the console and sets its activity to "Listening to your beautiful voice".

Sources: src/app.ts:13-16, src/app.ts:54-61, src/app.ts:65

System Architecture

The bot application (app.ts) acts as the central component, interacting with the Discord API and coordinating with several backend services for its translation pipeline. The docker-compose.prod.yml file defines these services, which include a Speech-to-Text (STT) service, a translation service (LibreTranslate), and a Redis instance for data persistence.

This diagram illustrates the high-level architecture of the bot and its dependencies.

Command Handling

All user interactions are received through the interactionCreate event listener. The application first verifies that the interaction is a slash command. It then uses a switch statement to route the command to the appropriate handler based on interaction.commandName. Before routing, a telemetry event is tracked to log command usage.

Sources: src/app.ts:18-20, src/app.ts:33-49

This diagram shows the flow of an incoming command interaction.

Registered Commands

The bot registers several slash commands, each with a dedicated handler function.

Command	Handler	Description
/join	joinCommandHandler	Moves the bot into the user's voice channel.
/leave	leaveCommandHandler	Moves the bot out of the voice channel.
/start	startCommandHandler	Starts translation for the user with a specified target language.
/stop	stopCommandHandler	Stops translation for the user.
/status	statusCommandHandler	Shows the user's current translation settings.
/languages	languagesCommandHandler	Shows all available languages for translation.

Sources: src/app.ts:35-48, src/interactions.ts:13-19

Slash Command Deployment

The application supports two methods for deploying slash commands to Discord: guild-specific for development and global for production.

Guild Command Deployment

If CLIENT_ID and GUILD_ID are present in the environment variables, the bot will automatically register/update slash commands for that specific guild on startup. This is useful for rapid development and testing on a single server. The initGuildCommands function from src/interactions.ts is called to perform this action.

Sources: src/app.ts:67-73, src/interactions.ts:22-34, src/env.ts:12-13

Global Command Deployment

Global commands are deployed manually by running pnpm run deploy. This script executes src/deploy.ts, which calls initGlobalCommands to register the commands for all servers the bot is in. This is the standard method for production.

Sources: package.json:13, src/deploy.ts, src/interactions.ts:36-48

This diagram shows the two deployment flows.

Environment Configuration

The bot's configuration is managed through environment variables, loaded via dotenv and validated using Zod by @t3-oss/env-core. The src/env.ts file defines the schema for all required and optional variables.

Variable	Type	Optional	Description
BOT_TOKEN	string	No	The Discord bot token.
CLIENT_ID	string	Yes	The Discord application client ID, used for command deployment.
GUILD_ID	string	Yes	The ID of a specific guild for automatic command deployment.
LOG_PATH	string	Yes	File path to write logs to.
POSTHOG_API_KEY	string	Yes	API key for PostHog telemetry.
REDIS_URL	string	Yes	Connection URL for the Redis server.
STT_HOST	string	No	Host URL for the Speech-to-Text service.
TRANSLATION_HOST	string	No	Host URL for the translation service.
HEARTBEAT_URL	string (url)	No	URL to send a periodic heartbeat POST request to.

Sources: src/env.ts:9-21

Ancillary Processes

The main application file also manages background processes critical for monitoring and stability.

Heartbeat Monitoring

If a HEARTBEAT_URL is provided, the application sets up an interval to send a POST request to that URL every 60 seconds. This is a common pattern for uptime monitoring services to ensure the bot process is running and responsive.

Sources: src/app.ts:75-90

Graceful Shutdown

The application listens for SIGTERM and SIGINT process signals to trigger a graceful shutdown. The handleShutdown function is called, which flushes any pending telemetry events via flushEvents() before exiting the process. This ensures that analytics data is not lost when the bot is stopped or restarted.

Sources: src/app.ts:92-98

Voice Processing Sequence

When a user speaks in a voice channel, a complex sequence of events is triggered, coordinated by the handlers initialized in app.ts. The core logic resides within the /join command handler.

This sequence diagram outlines the voice processing pipeline from speech to translated audio playback.