Naru Bot

A feature-rich Discord bot built with Bun, TypeScript, and Discord.js v14, featuring AI chat capabilities, comprehensive logging, and modular architecture.

Features

• AI Chat Integration: Powered by Google's Gemini AI with dynamic persona/prompt system
• Comprehensive Logging: Track all server activities (messages, members, roles, channels, voice, etc.)
• Message Archival: Automatic attachment preservation for deleted messages
• Modular Architecture: Clean kernel-based subsystem management
• Modern UI: Discord.js v14 ComponentsV2 with clean, styled responses
• Real-time Updates: File watching for persona/prompt configuration changes

Prerequisites

• Bun v1.3.0 or higher
• MySQL database
• Redis server
• Discord Bot Token
• Google AI API Key (for Gemini)

Installation

1. Clone the repository:

git clone <repository-url>
cd naru-bot

2. Install dependencies:

bun install

3. Configure environment variables:

cp .env.example .env

Edit .env with your configuration:

# Server Configuration
SERVER_PORT=3000
SERVER_ID=0

# Discord Bot
BOT_TOKEN=<your_discord_bot_token>
CLIENT_ID=<your_discord_client_id>
BOT_PREFIX=나루쨘

# Google AI
GOOGLE_API_KEY=<your_google_api_key>
GEMINI_MODEL=gemini-2.5-flash

# Database
DB_HOST=localhost
DB_PORT=3306
DB_NAME=naru_bot
DB_USER=<your_db_user>
DB_PASSWORD=<your_db_password>

# Redis
REDIS_URL=redis://localhost:6379

4. Initialize the database:

# Run migrations in src/modules/database/migrations/
# 001_initialize_tables.sql - Core tables
# 002_logging_tables.sql - Logging system tables

5. (Optional) Create custom persona and prompt files:

mkdir -p .narudata
# Files will be auto-generated on first run if missing
# Edit .narudata/persona.txt - Bot personality
# Edit .narudata/prompt.txt - Additional context (supports {timestamp}, {username})

Usage

Development Mode

Run with hot-reload:

bun run dev

Run without watch mode:

bun run dev:nowatch

Generate version file for development:

bun run build:version

Production Build

Build production binary:

bun run build

This will:

1. Generate version file with git information
2. Compile binary with version in filename: naru-bot-v{version}-{commit}
3. Output to dist/ directory

Run production binary:

./dist/naru-bot

Linting

Check code style:

bun run lint

Auto-fix issues:

bun run lint:fix

Architecture

Kernel System

The bot uses a modular kernel architecture with subsystems:

• FileSubsystem: Manages persona.txt and prompt.txt with auto-reload
• DatabaseSubsystem: MySQL connection and query management
• RedisSubsystem: Caching and temporary data storage
• GenAISubsystem: Google Gemini AI integration
• ServerSubsystem: HTTP/WebSocket backend server
• DiscordSubsystem: Discord bot client and event handling

Services

• UserService: User management and authentication
• GuildService: Server (guild) configuration
• LoggingService: Comprehensive activity logging system

Project Structure

src/
├── core/           # Kernel and module system
├── modules/        # Subsystem implementations
│   ├── database/   # MySQL database module
│   ├── discord/    # Discord bot module
│   │   ├── commands/   # Slash commands
│   │   ├── events/     # Event handlers
│   │   │   └── log/    # Comprehensive logging events
│   │   └── types/      # Type definitions
│   ├── fs/         # File system (persona/prompt)
│   ├── genai/      # Google AI integration
│   ├── redis/      # Redis cache module
│   └── server/     # Backend server
├── services/       # Business logic services
│   ├── guild/      # Guild management
│   ├── logging/    # Logging configuration
│   └── user/       # User management
├── shared/         # Shared utilities
└── version.ts      # Auto-generated version info

Commands

/나루쨘관리 (Server Management)

Discord Server Owner-only command

• /나루쨘관리 등록 - Register server for bot services
• /나루쨘관리 로깅 활성화 - Enable logging system
• /나루쨘관리 로깅 비활성화 - Disable logging system
• /나루쨘관리 로깅 채널설정 - Configure logging channel
• /나루쨘관리 로깅 상태 - Check logging status

/ping

Check bot latency and status

AI Chat

Mention the bot with prefix (default: 나루쨘) to chat with AI Requires ROOT user role

Logging System

The bot logs all server activities:

• Messages: Create, update, delete (with attachment preservation)
• Members: Join, leave, update, ban, unban
• Roles: Create, delete, update
• Channels: Create, delete, update
• Voice: Join, leave, move, mute/unmute
• Guild: Update settings
• Invites: Create, delete
• Threads: Create, delete, update
• Scheduled Events: Create, update, delete
• Webhooks: Create, update, delete
• Stage Instances: Create, update, delete

Message Deletion with Attachments

When messages with attachments are deleted:

1. Attachments are downloaded immediately when messages are created
2. Files are cached in Redis with local paths
3. On deletion, cached files are retrieved (not re-downloaded from Discord CDN)
4. Deleted messages are logged with preserved attachments

This ensures 100% file preservation even after Discord CDN URLs expire.

Development

Adding New Commands

Create a new file in src/modules/discord/commands/:

import type { NaruKernel } from "@/core";
import type { ChatInputCommandInteraction } from "discord.js";
import type { CommandExecutor } from "../types/command";

const MyCommand: CommandExecutor = {
  data: {
    name: "mycommand",
    description: "My command description"
  },
  async execute(kernel: NaruKernel, interaction: ChatInputCommandInteraction) {
    // Implementation
  }
};

export default MyCommand;

Adding New Event Handlers

Create a new file in src/modules/discord/events/:

import type { NaruKernel } from "@/core";
import type { EventHandler } from "../types/event";

const MyEvent: EventHandler = {
  name: "eventName",
  once: false,
  async execute(kernel: NaruKernel, ...args: any[]) {
    // Implementation
  }
};

export default MyEvent;

Versioning

Version information is auto-generated:

• Development: Shows "Development" marker
• Production: Shows build timestamp in KST

Format: v{version} ({commit}) [{branch}]

Example:

• Dev: v1.0.0 (abc1234) [master] - Development
• Prod: v1.0.0 (abc1234) [master] - Built at 2025. 10. 12. 오전 12:00:00

Contributing

[Contributing guidelines]

Support

For issues or questions, contact: devproje on Discord