Configuration

Relevant source files

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

• src/config/config.ts
• types/config.d.ts
• src/database/schemas/Dev.ts
• app.json
• package.json
• src/services/aiResponder.ts
• src/commands/bot/bot.ts

The configuration system in Amina is a multi-layered architecture designed for flexibility, security, and dynamic control. It combines static default values, environment-specific secrets, and a database-backed system for runtime modifications. This approach allows developers to set baseline behavior, securely manage API keys, and adjust critical parameters without requiring a full bot restart.

The system's core components are:

1. Static Configuration: Default application settings defined in code.
2. Secrets Management: Secure handling of sensitive data via environment variables.
3. Dynamic Configuration: A MongoDB collection (dev-config) that allows for live updates to specific settings, primarily for AI and bot presence.
4. Type Definitions: TypeScript interfaces that enforce structure and provide type safety across all configuration objects.

Configuration Loading Flow

The application loads configuration in a specific order, with later stages overriding earlier ones. Environment variables provide the foundation for secrets, which are then consumed by the static configuration file. Dynamic settings from the database are fetched at runtime to provide the most current values.

This diagram illustrates the flow of configuration data from its source to its use within the application.

Static Configuration

The primary static configuration is managed in src/config/config.ts. This file defines default values and feature flags for most of the bot's modules. These values serve as a baseline and can be overridden by dynamic configurations where applicable.

Sources: src/config/config.ts

Key Configuration Objects

The config object is divided into several sections, each corresponding to a major feature or system component.

Category	Description
BOT	Core bot settings like developer IDs, support server link, and dashboard URL.
AI	Default seed values for the AI system, including model name, token limits, and temperature. These are primarily for initial database setup.
SERVER	Server-related settings, such as the health check port.
MONITORING	Configuration for monitoring services, including environment name and application revision for services like Honeybadger.
INTERACTIONS	Flags to enable or disable slash commands and context menus, and to control global vs. guild-specific registration.
CACHE_SIZE	Defines the cache sizes for Discord objects like guilds, users, and members to manage memory usage.
ECONOMY	Settings for the economy module, such as currency symbol and daily coin amounts.
MUSIC	Configuration for the music system, including Lavalink node details, idle time, and default volume.
MODERATION	Feature flag for the moderation module.
STATS	Settings for the user statistics and leveling system, like XP cooldown.

Sources: src/config/config.ts:3-107

Example: Music Configuration

The MUSIC configuration block demonstrates how Lavalink nodes are configured by mapping over secrets loaded from the environment. It also sets default behaviors for the music player.

// src/config/config.ts:68-81
MUSIC: {
  ENABLED: true,
  IDLE_TIME: 60, // Time in seconds before the bot disconnects from an idle voice channel
  DEFAULT_VOLUME: 60, // Default player volume 1-100
  MAX_SEARCH_RESULTS: 5,
  DEFAULT_SOURCE: 'scsearch', // ytsearch = Youtube, ytmsearch = Youtube Music, scsearch = SoundCloud, spsearch = Spotify
  LAVALINK_RETRY_AMOUNT: 20,
  LAVALINK_RETRY_DELAY: 30000,
  LAVALINK_NODES: secret.LAVALINK_NODES.map(node => ({
    // ... mapping logic
  })).filter(node => node.id && node.host), // Only include nodes that are defined
},

Sources: src/config/config.ts:68-81

Secrets and Environment Variables

Sensitive information, such as API keys and tokens, is managed through environment variables. The app.json file defines the expected environment variables for deployment platforms like Heroku, serving as a template for the required secrets.

Sources: app.json, types/config.d.ts:109-135

Secrets Interface

The types/config.d.ts file defines the Secrets interface, which provides type safety for all environment variables used in the application.

// types/config.d.ts:109-135
interface Secrets {
  // Bot & Database
  readonly BOT_TOKEN: string
  readonly MONGO_CONNECTION: string
  readonly LOGS_WEBHOOK?: string

  // API Keys & Tokens
  readonly GEMINI_KEY?: string
  readonly UPSTASH_VECTOR?: string
  readonly WEATHERSTACK_KEY?: string
  readonly STRANGE_API_KEY?: string
  readonly GH_TOKEN?: string
  readonly SPOTIFY_CLIENT_ID?: string
  readonly SPOTIFY_CLIENT_SECRET?: string
  readonly OPENAI?: string
  readonly HONEYBADGER_API_KEY?: string
  readonly WEBHOOK_SECRET?: string

  // Lavalink Nodes
  readonly LAVALINK_NODES: Array<{
    id?: string
    host?: string
    port?: number
    authorization?: string
    secure?: boolean
  }>
}

Sources: types/config.d.ts:109-135

Environment Variables defined in app.json

The following table lists the environment variables expected by the application.

Variable	Description	Required
BOT_TOKEN	Bot Token from Discord Developer Portal.	Yes
MONGO_CONNECTION	MongoDB Connection String.	Yes
WEBHOOK_SECRET	Secure random string for dashboard webhook authentication.	No
LOGS_WEBHOOK	Discord webhook URL for bot logs.	No
LAVALINK_HOST_1	Primary Lavalink node host.	No
LAVALINK_PORT_1	Primary Lavalink node port.	No
LAVALINK_PASSWORD_1	Primary Lavalink node password.	No
GEMINI_KEY	Google Gemini API Key.	No
UPSTASH_VECTOR	Upstash Vector Database token.	No
WEATHERSTACK_KEY	Weather command API key.	No
STRANGE_API_KEY	Image manipulation commands API key.	No
GH_TOKEN	GitHub token for the changelog command.	No
HONEYBADGER_API_KEY	Honeybadger error tracking API key.	No

Sources: app.json:4-87

Dynamic Database Configuration

For settings that require frequent changes without redeployment, Amina uses a MongoDB collection named dev-config. This is primarily used for the AI Responder system and the bot's presence (status message). The schema and access functions are defined in src/database/schemas/Dev.ts.

Sources: src/database/schemas/Dev.ts

dev-config Schema

The schema defines the structure of the single document in the dev-config collection. It uses default values from the static config.ts file to seed the database on its first run.

This diagram shows the entity relationship for the dev-config schema.

AI Configuration (AI_CONFIG)

The AI_CONFIG object within the dev-config document holds all runtime parameters for the AI responder. The aiResponder service fetches this configuration upon initialization and uses it to configure the AI client. Any changes made via developer commands update this document, allowing for live adjustments to the AI's behavior.

The static config.AI object in config.ts only serves to seed these values into the database on the first run. After that, all AI configuration is sourced from MongoDB.

Sources: src/database/schemas/Dev.ts:40-78, src/config/config.ts:11-19, src/services/aiResponder.ts:59-83

Database Helper Functions

The Dev.ts file provides several exported functions to interact with the dev-config document, abstracting the database logic from the rest of the application.

Function	Description
getPresenceConfig()	Fetches the PRESENCE configuration object.
updatePresenceConfig(update)	Updates fields within the PRESENCE object.
getAiConfig()	Fetches the AI_CONFIG object.
updateAiConfig(update)	Updates fields within the AI_CONFIG object.
updateBotStats(stats)	Updates the BOT_STATS object with current bot metrics.
getBotStats()	Fetches the BOT_STATS object.

Sources: src/database/schemas/Dev.ts:104-189

Summary

Amina's configuration system is robust and layered. It effectively separates static defaults (config.ts), sensitive secrets (app.json and environment variables), and dynamic, hot-reloadable settings (dev-config in MongoDB). This separation provides a secure and maintainable foundation while giving developers the power to tune performance-critical and behavior-defining parameters in real-time. The use of TypeScript with types/config.d.ts ensures that all parts of the application handle configuration data in a consistent and error-free manner.