Required Services (MongoDB & Lavalink)

Relevant source files

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

• src/database/mongoose.ts
• lavalink/application.yml
• src/config/config.ts
• src/structures/BotClient.ts
• app.json
• package.json
• src/database/schemas/Dev.ts

Amina's functionality relies on two critical external services: MongoDB for data persistence and Lavalink for audio playback. MongoDB serves as the bot's long-term memory, storing all configuration, user data, and guild-specific settings. Lavalink acts as a dedicated audio processing and sending node, enabling high-quality, stable music streaming without overloading the main bot process.

This document outlines the architecture, configuration, and role of each service within the Amina project. Proper setup of both MongoDB and Lavalink is essential for the bot's core features to operate correctly.

MongoDB

MongoDB is a NoSQL database used to store all persistent data for the Amina bot. This includes guild settings, user profiles, economy data, moderation logs, and more. The project uses the mongoose library to interact with MongoDB, providing schema validation, casting, and business logic hooks.

Sources: package.json:28, src/database/mongoose.ts

Connection

The bot establishes a connection to a MongoDB instance on startup. The connection string is retrieved from the MONGO_CONNECTION environment variable.

The following diagram illustrates the database connection flow.

The connection logic includes event listeners for connected, error, and disconnected states, ensuring robust handling of the database link.

Schemas

Mongoose schemas define the structure of documents within MongoDB collections. Amina defines several schemas for different data models, such as Guild, User, Member, and dev-config.

For example, the dev-config schema manages global bot configurations like presence, AI settings, and bot statistics.

Sources: src/database/schemas/Dev.ts, src/structures/BotClient.ts:50

The diagram below represents the structure of the dev-config collection.

Configuration

To connect to MongoDB, a single environment variable is required.

Variable	Description	Required	Example
MONGO_CONNECTION	The connection string for the MongoDB Atlas cluster or self-hosted instance.	Yes	mongodb+srv://user:pass@cluster.mongodb.net/db

Sources: app.json:10-14

Lavalink

Lavalink is a standalone audio sending node that handles music playback for Discord. By offloading audio processing to a separate service, Amina can deliver high-quality, reliable music streaming with minimal impact on the bot's primary operations. The bot communicates with the Lavalink server using the lavalink-client library.

Sources: package.json:26, src/structures/BotClient.ts:63-64

Architecture

The BotClient class initializes a Manager instance, which handles all communication with the configured Lavalink nodes. When a user requests a song, the bot sends a request to Lavalink, which in turn fetches the audio, processes it, and streams it to the Discord voice channel.

The following diagram shows the interaction between the user, Amina, Lavalink, and Discord.

Bot Configuration

The Lavalink nodes that the bot connects to are defined in src/config/config.ts under the MUSIC.LAVALINK_NODES array. These settings are populated from environment variables.

// src/config/config.ts:74-83
MUSIC: {
  ENABLED: true,
  // ...
  LAVALINK_NODES: secret.LAVALINK_NODES.map(node => ({
    id: node.id,
    host: node.host,
    port: node.port || 2333,
    authorization: node.authorization,
    secure: node.secure || false,
    // ...
  })).filter(node => node.id && node.host),
},

Sources: src/config/config.ts:74-83

The configuration for each node is as follows:

Key	Type	Description	Default
id	string	A unique identifier for the node.	-
host	string	The hostname or IP address of the Lavalink server.	-
port	number	The port number of the Lavalink server.	2333
authorization	string	The password for the Lavalink server.	-
secure	boolean	Whether to use a secure (SSL/TLS) connection.	false

Sources: types/config.d.ts:5-12, src/config/config.ts:74-83

Lavalink Server Configuration

The Lavalink server itself is configured via the lavalink/application.yml file. This file controls the server's port, password, enabled audio sources, and plugins.

Key configuration options include:

• server.password: Must match the authorization password in the bot's configuration.
• lavalink.server.sources: Enables or disables sources like YouTube, SoundCloud, and Bandcamp.
• lavalink.plugins: A list of plugins to be automatically downloaded and enabled on startup.

# lavalink/application.yml:1-5
server:
  port: 2333
  address: 0.0.0.0

# lavalink/application.yml:40-41
lavalink:
  server:
    password: "incorrect"

Sources: lavalink/application.yml

The project uses several plugins to enhance Lavalink's functionality:

Plugin	Repository	Purpose
youtube-plugin	dev.lavalink.youtube	Provides YouTube source support.
lavasrc-plugin	com.github.topi314.lavasrc	Adds support for Spotify, Apple Music, and Deezer.
lavasearch-plugin	com.github.topi314.lavasearch	Enables advanced search functionality.
sponsorblock-plugin	com.github.topi314.sponsorblock	Skips sponsored segments in YouTube videos.
LavaDSPX-Plugin	com.github.Devoxin	Adds extra DSP filters like high-pass and echo.
lavalyrics-plugin	com.github.topi314.lavalyrics	Provides a lyrics API.

Sources: lavalink/application.yml:8-38

Environment Variables

The following environment variables are used to configure the connection to Lavalink nodes. The system supports up to two nodes for fallback capability.

Variable	Description	Required	Default Value
LAVALINK_HOST_1	Host for the primary Lavalink node.	No	lavalink
LAVALINK_PORT_1	Port for the primary Lavalink node.	No	2333
LAVALINK_PASSWORD_1	Password for the primary Lavalink node.	No	incorrect
LAVALINK_ID_1	Identifier for the primary Lavalink node.	No	Lavalink
LAVALINK_SECURE_1	Whether the primary node uses a secure connection.	No	false
LAVALINK_HOST_2	Host for the secondary Lavalink node.	No	""
LAVALINK_PORT_2	Port for the secondary Lavalink node.	No	""
LAVALINK_PASSWORD_2	Password for the secondary Lavalink node.	No	""
LAVALINK_ID_2	Identifier for the secondary Lavalink node.	No	""
LAVALINK_SECURE_2	Whether the secondary node uses a secure connection.	No	false
SPOTIFY_CLIENT_ID	Spotify API client ID for the lavasrc plugin.	No	""
SPOTIFY_CLIENT_SECRET	Spotify API client secret for the lavasrc plugin.	No	""

Sources: app.json:24-82, lavalink/application.yml:102-103

Conclusion

MongoDB and Lavalink are indispensable components of Amina's architecture. MongoDB provides the essential data persistence layer, enabling the bot to remember settings, track user progress, and maintain state across sessions. Lavalink provides a robust, dedicated solution for audio playback, ensuring a high-quality user experience for music features. A functional deployment of Amina is not possible without correctly configuring and connecting to both of these services.