Enterprise-Grade Discord Bot Framework
Modular · Scalable · Production-Ready
Quick Start · Architecture · Class Reference · Container · Config · Addon Guide · CLI Tools · Metrics
--- ## 📚 Documentation This README provides a quick overview and getting started guide. For comprehensive documentation: | Doc | Contents | |---|---| | **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** | System architecture, design patterns, data flow diagrams | | **[CONTAINER.md](./docs/CONTAINER.md)** | `KythiaContainer` — every property, availability timeline, usage patterns | | **[CONFIG.md](./docs/CONFIG.md)** | Full `kythia.config.js` field reference | | **[ADDON_GUIDE.md](./docs/ADDON_GUIDE.md)** | Step-by-step guide to creating addons (commands, events, DB, i18n) | | **[CLASS_REFERENCE.md](./docs/CLASS_REFERENCE.md)** | Full class and method API documentation | | **[CLI_REFERENCE.md](./docs/CLI_REFERENCE.md)** | CLI tools: migrate, make:model, lang:check, etc. | | **[METRICS.md](./docs/METRICS.md)** | Prometheus metrics and Grafana query examples | --- ## 🌟 What is Kythia Core? **Kythia Core** is a powerful, production-ready framework for building scalable Discord bots. Built on top of discord.js v14, it provides a complete ecosystem for bot development with: - 🔌 **Addon System** - Modular architecture with hot-loadable addons - 🗄️ **Advanced ORM** - Hybrid Redis/LRU caching with automatic invalidation - 🔄 **Migration System** - Laravel-style migrations with batch support - 🎯 **Smart Routing** - Automatic command, event, and component registration - 🛡️ **Middleware** - Flexible permission, cooldown, and validation system - 📦 **Dependency Injection** - Clean, testable architecture with DI container - 🔧 **CLI Tools** - Powerful development tools for scaffolding and management - 📊 **Telemetry** - Built-in monitoring with Sentry integration - 🌐 **i18n** - Complete localization system with auto-translation - ⏰ **Task Scheduler** - Cron and interval-based task system --- ## 🏗️ Core Architecture ``` ┌───────────────────────────────────────────────────────────┐ │ Kythia Core │ ├───────────────────────────────────────────────────────────┤ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Addon │ │ Interaction │ │ Event │ │ │ │ Manager │ │ Manager │ │ Manager │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Translator │ │ Shutdown │ │ Telemetry │ │ │ │ Manager │ │ Manager │ │ Manager │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ ├───────────────────────────────────────────────────────────┤ │ Database Layer │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Kythia │ │ Kythia │ │ Kythia │ │ │ │ Model │ │ Migrator │ │ Sequelize │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ ├───────────────────────────────────────────────────────────┤ │ Caching Layer │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Redis (Primary) ↔ LRU Map (Fallback) │ │ │ └──────────────────────────────────────────────────────┘ │ └───────────────────────────────────────────────────────────┘ ``` See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed system design. --- ## 🚀 Quick Start ### Installation ```bash npm install kythia-core discord.js # or yarn add kythia-core discord.js # or pnpm add kythia-core discord.js ``` ### Basic Setup ```javascript // index.js // index.js const { Client, GatewayIntentBits } = require('discord.js'); const { Kythia, KythiaModel, createSequelizeInstance } = require('kythia-core'); const config = require('./kythia.config.js'); // 1. Setup Client const client = new Client({ intents: [ GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent, GatewayIntentBits.GuildMembers, ], }); // 2. Setup dependencies const logger = require('./core/helpers/logger'); const translator = require('./core/helpers/translator'); const Redis = require('ioredis'); const redis = new Redis(config.db.redis, { lazyConnect: true }); // 3. Create Sequelize instance const sequelize = createSequelizeInstance(config, logger); // 4. Inject dependencies into KythiaModel KythiaModel.setDependencies({ logger, config, redis }); // 5. Create dependency container const dependencies = { client, config, logger, translator, redis, sequelize, models: {}, helpers: { // Your addon helpers }, appRoot: __dirname, }; // 6. Initialize and start const kythia = new Kythia(dependencies); await kythia.start(); ``` ### Sharding (Optional) For large bots, use the built-in `ShardingManager` to spawn shards easily. Create a new entry file (e.g., `sharding.js`): ```javascript // sharding.js const { ShardingManager } = require('kythia-core'); require('dotenv').config(); const manager = new ShardingManager({ scriptPath: 'dist/index.js', // Path to your compiled bot entry file token: process.env.DISCORD_TOKEN, totalShards: 'auto', }); await manager.spawn(); ``` The `ShardingManager` includes built-in production protections: - **Crash loop detection** — if a shard dies ≥ 3 times within 5 minutes, spawning is paused for 2 minutes before retrying - **OOM kill detection** — exit code 137 / SIGKILL triggers a distinct alert log with actionable advice - **Lifetime restart tracking** — `manager.getShardRestartCount(shardId)` and `manager.getShardStats()` expose per-shard restart history ### Project Structure ``` kythia-bot/ ├── addons/ │ ├── core/ # Core addon │ │ ├── addon.json # Addon metadata │ │ ├── commands/ # Slash commands │ │ ├── events/ # Discord events │ │ ├── buttons/ # Button handlers │ │ ├── modals/ # Modal handlers │ │ ├── select_menus/ # Select menu handlers │ │ ├── tasks/ # Scheduled tasks │ │ ├── database/ │ │ │ ├── models/ # Sequelize models │ │ │ └── migrations/ # Database migrations │ │ └── register.js # Addon initialization │ └── feature/ # Feature addon │ └── ... ├── kythia.config.js # Bot configuration ├── package.json └── index.js # Entry point ``` --- ## ⚙️ Configuration Create `kythia.config.js` in your project root: ```javascript // kythia.config.js require('@dotenvx/dotenvx').config(); module.exports = { env: process.env.NODE_ENV || 'production', // 'development' | 'production' licenseKey: process.env.LICENSE_KEY, legal: { acceptTOS: true, // Required — must be true dataCollection: true, // Required — must be true }, version: '1.0.0', bot: { name: 'MyBot', token: process.env.DISCORD_TOKEN, clientId: process.env.CLIENT_ID, clientSecret: process.env.CLIENT_SECRET, totalShards: 'auto', mainGuildId: process.env.MAIN_GUILD_ID, devGuildId: process.env.DEV_GUILD_ID, color: '#5865F2', prefixes: ['!'], status: 'online', activityType: 3, // 3 = Watching activity: 'the server', globalCommandCooldown: 3000, language: 'en', locale: 'en-US', timezone: 'UTC', }, db: { driver: 'sqlite', // 'sqlite' | 'mysql' | 'postgres' name: 'kythiadata.sqlite', timezone: '+00:00', redis: process.env.REDIS_URL, redisCacheVersion: 'v1', }, owner: { ids: process.env.OWNER_IDS, names: 'YourName', }, sentry: { dsn: process.env.SENTRY_DSN, }, addons: { core: { active: true }, economy: { active: true }, }, }; ``` See **[CONFIG.md](./docs/CONFIG.md)** for the complete field reference including MySQL/PostgreSQL, Redis, all addon configs, and antispam settings. --- ## 🔌 Creating Your First Addon ### 1. Create addon structure ```bash npx kythia make:addon --name myfeature ``` ### 2. Define addon metadata ```json // addons/myfeature/addon.json { "name": "myfeature", "version": "1.0.0", "priority": 50, "dependencies": ["core"] } ``` ### 3. Create a command ```javascript // addons/myfeature/commands/hello.js const { SlashCommandBuilder } = require('discord.js'); module.exports = { data: new SlashCommandBuilder() .setName('hello') .setDescription('Say hello!'), async execute(interaction) { const { logger } = interaction.client.container; logger.info('Hello command executed!'); await interaction.reply('Hello, World!'); } }; ``` ### 4. Create a scheduled task ```javascript // addons/myfeature/tasks/daily-report.js module.exports = { schedule: '0 0 * * *', // Daily at midnight async execute(container) { const { logger } = container; logger.info('Running daily report...'); } }; ``` See [ADDON_GUIDE.md](./docs/ADDON_GUIDE.md) for complete addon development guide. --- ## 🗄️ Database & Models ### Creating a Model ```bash npx kythia make:model --name User --addon myfeature ``` ```javascript // addons/myfeature/database/models/User.js const { KythiaModel } = require('kythia-core'); const { DataTypes } = require('sequelize'); class User extends KythiaModel { static tableName = 'users'; static init(sequelize) { return super.init({ userId: { type: DataTypes.STRING, unique: true, }, username: DataTypes.STRING, points: { type: DataTypes.INTEGER, defaultValue: 0, }, }, { sequelize, modelName: 'User', tableName: this.tableName, }); } } module.exports = User; ``` ### Using the Model with Cache ```javascript // In your command const { models } = interaction.client.container; const { User } = models; // Get with cache (auto Redis/LRU) const user = await User.getCache({ where: { userId: interaction.user.id } }); // Create with cache invalidation const newUser = await User.create({ userId: interaction.user.id, username: interaction.user.username, }); ``` ### Creating Migrations ```bash npx kythia make:migration --name create_users_table --addon myfeature ``` ```javascript // addons/myfeature/database/migrations/20250128000000_create_users_table.js module.exports = { up: async (queryInterface, DataTypes) => { await queryInterface.createTable('users', { id: { type: DataTypes.INTEGER, primaryKey: true, autoIncrement: true, }, userId: { type: DataTypes.STRING, unique: true, }, points: { type: DataTypes.INTEGER, defaultValue: 0, }, createdAt: DataTypes.DATE, updatedAt: DataTypes.DATE, }); }, down: async (queryInterface) => { await queryInterface.dropTable('users'); } }; ``` Run migrations: ```bash npx kythia migrate ``` --- ## 🛠️ CLI Tools Kythia Core includes powerful CLI tools: ```bash # Database npx kythia migrate # Run migrations npx kythia migrate --fresh # Fresh migration npx kythia migrate --rollback # Rollback last batch npx kythia make:migration # Create migration npx kythia make:model # Create model npx kythia cache:clear # Clear Redis cache # Localization npx kythia lang:check # Check translation keys npx kythia lang:translate --target ja # Auto-translate # Development npx kythia dev:namespace # Add JSDoc headers npx kythia gen:structure # Generate project tree npx kythia version:up # Sync version tags ``` See [CLI_REFERENCE.md](./CLI_REFERENCE.md) for complete command reference. --- ## 🎯 Key Features ### Addon Dependency Management ```json { "name": "analytics", "priority": 50, "dependencies": ["core", "database"] } ``` Addons are loaded in dependency order with automatic validation. ### Task Scheduling ```javascript // Cron-based module.exports = { schedule: '*/5 * * * *', // Every 5 minutes execute: async (container) => { /* ... */ } }; // Interval-based module.exports = { schedule: 60000, // Every 60 seconds execute: async (container) => { /* ... */ } }; ``` ### Middleware System ```javascript const { botPermissions } = require('kythia-core/middlewares'); module.exports = { data: /* ... */, middlewares: [ botPermissions(['SendMessages', 'EmbedLinks']), ], execute: async (interaction) => { /* ... */ } }; ``` ### Hybrid Caching Automatic Redis + LRU fallback with tag-based invalidation: ```javascript // Automatically uses Redis if available, falls back to LRU const user = await User.getCache({ where: { id: 1 } }); // Automatic cache invalidation on updates await user.update({ points: 100 }); // Cache auto-cleared ``` --- ## 📖 Advanced Topics - **[KythiaContainer Reference](./docs/CONTAINER.md)** — Every service, model, and helper available in the DI container - **[Configuration Reference](./docs/CONFIG.md)** — Every kythia.config.js field with types and examples - **[Addon Authoring Guide](./docs/ADDON_GUIDE.md)** — Commands, events, DB, i18n, tasks from scratch - **[Addon Architecture](./docs/ARCHITECTURE.md#addon-system)** — Dependency resolution and load order - **[Metrics & Monitoring](./docs/METRICS.md)** — Prometheus metrics and Grafana setup - **[Obfuscation](./docs/OBFUSCATION.md)** — Code obfuscation configuration --- ## 🤝 Contributing We welcome contributions! Please see our contributing guidelines. --- ## 📜 License This project is licensed under the CC BY NC 4.0 License - see the [LICENSE](./LICENSE) file for details. Copyright © 2025 Kythia Labs - All rights reserved. --- ## 🔗 Links - [Architecture](./docs/ARCHITECTURE.md) - [Container Reference](./docs/CONTAINER.md) - [Config Reference](./docs/CONFIG.md) - [Addon Guide](./docs/ADDON_GUIDE.md) - [Class Reference](./docs/CLASS_REFERENCE.md) - [CLI Reference](./docs/CLI_REFERENCE.md) - [Metrics](./docs/METRICS.md) - [GitHub Issues](https://github.com/kenndeclouv/kythia-core/issues) - [Discord Server](https://dsc.gg/kythia) ---Made with ❤️ by kenndeclouv