teto_ai/docs/architecture.md

Discord Teto Bot - Services Documentation

This directory contains the core services and business logic for the Discord Teto bot, separated from the event handling for better maintainability and testability.

Architecture Overview

The bot has been refactored into a modular architecture with the following components:

Services (/src/services/)

videoRecording.js

The main video recording service that handles all video recording functionality.

Key Features:

• Voice channel joining and leaving
• Video stream creation and management
• File output handling
• Recording state management
• Auto-stop functionality (30-second demo limit)

Main Methods:

• startRecording({ client, voiceChannel, user, textChannel }) - Starts recording
• stopRecording(voiceChannelId, textChannel, message) - Stops recording
• getStatus() - Returns recording status and file information
• isRecording(voiceChannelId) - Checks if channel is being recorded
• getRecordingInfo(voiceChannelId) - Gets recording details

commandHandler.js

Handles all bot commands in a modular way, making it easy to add, remove, or modify commands.

Registered Commands:

• dm_pickup - Responds to "teto" mentions in DMs
• start_recording - Handles "xbox record that" command
• stop_recording - Handles "stop recording" and "xbox stop" commands
• status - Handles "teto status" command
• hello - Handles "hello teto" messages

Key Methods:

• processMessage(msg, context) - Processes incoming messages and executes matching commands
• addCommand(name, command) - Dynamically add new commands
• removeCommand(name) - Remove existing commands
• getAvailableCommands() - List all registered commands

Configuration (/src/config/)

videoConfig.js

Centralized configuration for all video recording settings.

Configuration Sections:

• File Paths: Output directories for container and host
• Recording Settings: Timeouts, delays, and limits
• Voice Settings: Discord voice connection parameters
• FFmpeg Options: Video and audio encoding settings
• Error Messages: Standardized error messages
• Success Messages: User-friendly feedback messages
• Status Templates: Formatted status report templates

Events (/src/events/)

messageCreate.js (Refactored)

Now focuses solely on message routing and basic logging. All command logic has been moved to the command handler.

Responsibilities:

• Message logging
• Bot message filtering
• Command routing to commandHandler
• Action logging

Benefits of the New Architecture

1. Separation of Concerns

• Event handling is separate from business logic
• Video recording logic is isolated in its own service
• Commands are modular and self-contained

2. Maintainability

• Easy to add new commands without touching event handlers
• Configuration is centralized and easy to modify
• Each service has a single responsibility

3. Testability

• Services can be unit tested independently
• Mock dependencies are easier to inject
• Command logic is isolated and testable

4. Reusability

• Video recording service can be used by multiple commands
• Command handler can be extended for different event types
• Configuration can be shared across services

5. Error Handling

• Centralized error messages and handling
• Better error isolation between services
• Consistent user feedback

Usage Examples

Adding a New Command

// In commandHandler.js
this.commands.set('new_command', {
  trigger: (msg) => msg.content.toLowerCase() === 'my new command',
  execute: async (msg, context) => {
    msg.channel.send('Response to new command!');
    return {
      action: {
        message: `New command executed by ${msg.author.tag}`,
        channel: `#${msg.channel.name}`,
        icon: "🆕",
      }
    };
  }
});

Using the Video Recording Service

import videoRecordingService from './videoRecording.js';

// Start recording
const result = await videoRecordingService.startRecording({
  client: discordClient,
  voiceChannel: userVoiceChannel,
  user: discordUser,
  textChannel: messageChannel
});

// Check recording status
const status = videoRecordingService.getStatus();
console.log(`Active recordings: ${status.activeRecordings}`);

// Stop recording
await videoRecordingService.stopRecording(
  voiceChannelId,
  textChannel,
  'Recording stopped manually'
);

Modifying Configuration

// In videoConfig.js
export const VIDEO_CONFIG = {
  AUTO_STOP_TIMEOUT: 60_000, // Change to 60 seconds
  MAX_RECORDING_DURATION: 600_000, // 10 minutes
  // ... other settings
};

File Structure

src/
├── config/
│   └── videoConfig.js          # Configuration constants
├── events/
│   └── messageCreate.js        # Refactored event handler
└── services/
    ├── commandHandler.js       # Command routing and execution
    ├── videoRecording.js       # Video recording business logic
    └── README.md              # This documentation

Docker Integration

The video recording service is designed to work in a Docker environment:

• Container Output: /tmp/output/ (temporary storage)
• Host Volume: ./output/ (persistent storage via volume mount)
• File Format: MKV (supports both audio and video)
• Processing: FFmpeg-based encoding

Future Improvements

1. Database Integration: Store recording metadata
2. User Permissions: Role-based command access
3. Recording Quality Settings: Configurable video quality
4. Multiple Format Support: MP4, WebM export options
5. Recording Scheduling: Timed recordings
6. Webhook Integration: External notifications
7. Analytics: Usage statistics and monitoring

Contributing

When adding new features:

1. Keep services focused on single responsibilities
2. Add configuration to videoConfig.js rather than hardcoding
3. Use the command handler pattern for new commands
4. Follow the existing error handling patterns
5. Update this documentation