Home

Relevant source files

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

• README.md
• package.json
• src/commands/bot/bot.ts
• CHANGELOG.md
• src/data/prompt.md
• src/helpers/mina.ts
• src/services/aiResponder.ts
• app.json
• release.config.js

Amina is a multipurpose open-source Discord bot designed to be a "Guardian Companion." It combines robust server moderation and administration tools with entertainment features and a unique, AI-driven personality. The project's core philosophy is to provide not just a utility, but a companion with a "heart" that protects communities while also fostering joy and engagement.

A significant architectural overhaul in version 3.0.0 introduced Mina's unified personality system, standardizing the bot's voice and interaction style across all features. This system is central to the bot's identity, ensuring a consistent and recognizable character. Amina is built using TypeScript and the discord.js library, leveraging a range of modern technologies for its features.

Sources: README.md, CHANGELOG.md:16-21, package.json

Core Identity & Personality

Amina's most defining characteristic is its carefully crafted personality, which is intentionally sharp, energetic, and blunt. The bot prefers to be called mina (all lowercase) and is designed to feel less like a cold robot and more like a companion with opinions. This identity is enforced through a combination of a core AI prompt, a static response helper, and a generative AI service.

Sources: src/data/prompt.md, src/helpers/mina.ts, src/services/aiResponder.ts

Personality Rules

The bot's voice is governed by a strict set of rules defined in its core AI prompt. These rules apply to both static and AI-generated responses.

Rule	Description
Name	Prefers mina. Corrects users who call her 'Amina'.
Case	all lowercase. always. No capital letters are used, even for 'i'.
Brevity	Responses are almost always a single, short sentence.
Slang	Uses Gen Z and common internet slang (e.g., wyd, ngl, cringe, w/l).
Emojis	Avoids emojis. Rarely uses ASCII emoticons like (¬_¬) or (◕‿◕✿) for strong emotion.
Tone	Opinionated, blunt, sassy, and impatient, but can be secretly caring.

Sources: src/data/prompt.md:3-33

The mina Helper

The mina helper, located in src/helpers/mina.ts, is the programmatic foundation of the bot's personality for static responses. It provides a centralized system for generating responses, accessing themed colors, and formatting text consistently with mina's voice.

Key functions include:

• mina.say(path): Retrieves a random response string from a nested JSON object using dot notation.
• mina.sayf(path, vars): Retrieves a response and formats it with placeholder variables.
• mina.emote(mood): Gets a random ASCII emoticon based on a mood.
• mina.quote(): Fetches a random anime quote.
• mina.color: Provides access to a standardized color palette for embeds.

Sources: src/helpers/mina.ts:80-256, CHANGELOG.md:29-37

The following diagram illustrates the flow of retrieving a static response using the mina.say() function.

AI Responder

For dynamic conversations, Amina uses the AiResponderService, which integrates with Google's Generative AI. This service determines when and how the bot should respond to messages, leveraging the core identity defined in prompt.md. It handles DMs, mentions, and "free-will" conversations in designated channels. The service builds a rich context for the AI, including conversation history, user profiles, and relevant "memories" (facts stored about users).

Sources: src/services/aiResponder.ts

This sequence diagram shows the process of generating an AI-driven response.

Key Features

Amina's functionality is organized into three main categories, reflecting its role as a "Guardian Companion."

Category	Description
Defense Protocols	Moderation and administrative tools, including anti-spam, a ticket system, and role management.
Morale Operations	Entertainment features such as high-quality music playback, mini-games, an economy system, and image manipulation.
Intelligence Reports	Utility functions like server analytics, invite tracking, a suggestion system, and multi-language support.

Sources: README.md:63-95

Core /mina Command

The /mina command serves as a central hub for users to get information about the bot itself. It provides access to vital links, statistics, and project updates.

Sources: src/commands/bot/bot.ts

Subcommands

Subcommand	Description
invite	Get a link to add Amina to a server.
stats	View system stats like memory, CPU, and server count.
uptime	Check how long the bot has been running.
donate	Get links to support development.
docs	Access the official documentation wiki.
ping	Check the bot's response latency to Discord.
changelog	See the latest updates and changes from the CHANGELOG.md file.

Sources: src/commands/bot/bot.ts:18-49

Changelog Fetching Logic

The /mina changelog subcommand dynamically fetches the CHANGELOG.md file directly from the GitHub repository using the @octokit/rest library. It then parses the content to display the two most recent versions to the user.

This diagram shows the workflow for the changelog subcommand.

Project Structure & Dependencies

Amina is a TypeScript project managed with bun. It relies on semantic-release for automated versioning, package publishing, and changelog generation.

Sources: package.json, release.config.js

Key Dependencies

Package	Purpose
discord.js	The core library for interacting with the Discord API.
@google/generative-ai	Client for the Google Gemini API, powering the AI responder.
mongoose	Object Data Modeling (ODM) library for MongoDB, used for all database schemas.
lavalink-client	Powers the music playback feature.
@upstash/vector	Used for the AI's memory system to find relevant information.
@octokit/rest	Used to interact with the GitHub API, primarily for the changelog command.
@honeybadger-io/js	Integrated for real-time error tracking.

Sources: package.json:26-51

Configuration & Deployment

The project is designed for deployment on platforms like Heroku and is configured via environment variables. The app.json file defines the necessary variables for a Heroku deployment.

Sources: app.json

Core Environment Variables

Variable	Description	Required
BOT_TOKEN	The Discord bot token.	Yes
MONGO_CONNECTION	The connection string for the MongoDB database.	Yes
GEMINI_KEY	API key for Google Gemini, required for the AI features.	No
UPSTASH_VECTOR	Token for the Upstash Vector database for AI memory.	No
LAVALINK_HOST_1	Host for the primary Lavalink node for music.	No
GH_TOKEN	GitHub token for fetching the changelog.	No
HONEYBADGER_API_KEY	API key for Honeybadger error tracking.	No

Sources: app.json:4-86