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

```javascript
// 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

```javascript
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

```javascript
// 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