Project Structure

Relevant source files

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

• package.json
• release.config.js
• src/commands/bot/bot.ts
• src/database/schemas/Dev.ts
• types/config.d.ts
• CHANGELOG.md
• scripts/iamvikshan.sh
• app.json
• renovate.json
• src/handlers/roles/add-to-user/index.ts
• src/commands/admin/settings/status.ts

Introduction

The Amina project is a multipurpose, open-source Discord bot built with TypeScript and the discord.js library. Its structure is designed for modularity, maintainability, and scalability, supporting a wide range of features including moderation, entertainment, AI interaction, and server utilities. The architecture emphasizes a clear separation of concerns, with distinct modules for commands, event handlers, database schemas, and configuration.

The project leverages modern tooling such as bun for its runtime, semantic-release for automated versioning and changelog generation, and Mongoose for database interaction with MongoDB. This structured approach allows for consistent development patterns and simplifies the process of adding new features or fixing bugs. The major architectural refactoring to TypeScript and a modular handler system noted in the changelog highlights the project's commitment to code quality and maintainability.

Sources: package.json, README.md, CHANGELOG.md:80-111

Core Architecture

The project is organized into several key directories and components that work together to deliver the bot's functionality. The main entry point is src/index.ts, which initializes the bot client, loads all modules, and connects to Discord.

This diagram provides a high-level overview of the main components and their interactions.

Scripts and Tooling

The package.json file defines the core scripts for development, building, and running the application. The project uses bun as its primary runtime and package manager.

Script	Description
dev	Runs the bot in watch mode for development using bun --watch src/index.ts.
build	Runs bun check and prettier --check to ensure type safety and code formatting.
start	Starts the bot using bun src/index.ts.
check	Performs static analysis using tsc --noEmit and eslint.
prepare	Installs Husky for git hooks.

Sources: package.json:11-20

Development Environment Setup

The project includes a unique shell script, scripts/iamvikshan.sh, designed to configure a development environment (like GitHub Codespaces) to use a specific developer's Git and GitHub credentials (iamvikshan). This ensures that all commits and GitHub operations are correctly attributed, even in a shared or containerized environment. The script automates:

• Git global config (user.name, user.email).
• GitHub CLI authentication.
• SSH signing key generation and configuration for verified commits.
• Git remote and credential helper setup.

*Sources: scripts/iamvikshan.sh *

Configuration Management

Configuration is split between static configuration files, environment variables for secrets, and a dynamic developer configuration stored in the database.

Static and Secret Configuration

• types/config.d.ts: This file defines the TypeScript interfaces for all configuration objects, including Config for general settings and Secrets for sensitive data like API keys and tokens.
• app.json: Used for platforms like Heroku, this file defines the required environment variables, their descriptions, and default values. This serves as a manifest for all secret keys the application needs.

The following table outlines some of the key configuration areas defined in types/config.d.ts.

Category	Key Options	Description
BOT	DEV_IDS, SUPPORT_SERVER, DASHBOARD_URL	Core bot information and developer settings.
AI	MODEL, MAX_TOKENS, TEMPERATURE	Configuration for AI features, seeded from config.ts.
MUSIC	ENABLED, IDLE_TIME, LAVALINK_NODES	Settings for the music playback module.
AUTOMOD	ENABLED, anti_spam, anti_links	Toggles and settings for automated moderation.
ECONOMY	ENABLED, CURRENCY, DAILY_COINS	Settings for the server economy system.
MODERATION	ENABLED	Toggles the moderation feature set.

Sources: types/config.d.ts, app.json

Developer Configuration (Database)

A special dev-config collection in MongoDB stores settings that can be changed dynamically by developers at runtime. This includes bot presence (status, activity), AI model parameters, and feature flags. The src/database/schemas/Dev.ts file defines the schema for this collection, with default values often sourced from the static config.

This allows developers to adjust bot-wide behavior without requiring a code deployment.

Sources: src/database/schemas/Dev.ts:1-10

Command and Handler Structure

The project features a modular, file-based structure for commands and interactions.

Command Definition

Commands are organized by category within the src/commands/ directory (e.g., admin, bot, utility). Each command is a file that exports a CommandData object.

The /mina command is a primary example, using subcommands to group related functionalities like stats, uptime, and invite.

// src/commands/bot/bot.ts:13-43
const command: CommandData = {
  name: 'mina',
  description: 'get info about me - stats, invite, uptime, and more',
  category: 'INFO',
  botPermissions: ['EmbedLinks'],
  slashCommand: {
    enabled: true,
    options: [
      {
        name: 'invite',
        description: 'get a link to add me to your server',
        type: ApplicationCommandOptionType.Subcommand,
      },
      {
        name: 'stats',
        description: 'view system stats like memory, cpu, and server count',
        type: ApplicationCommandOptionType.Subcommand,
      },
      // ... other subcommands
    ],
  },
  // ...
}

Sources: src/commands/bot/bot.ts:13-43

Interaction Handling

The interactionRun function within a command file is the entry point for handling a slash command. For component interactions (buttons, select menus), the project uses a handler-based approach, often organized in the src/handlers/ directory.

For example, the roles:user:select interaction is handled by functions in src/handlers/roles/add-to-user/index.ts, which guide the user through a multi-step process of selecting users, then roles, and finally confirming the action.

The following sequence diagram illustrates the flow for the /mina stats command.

Database Schemas

The project uses Mongoose to model data for a MongoDB database. Schemas are located in src/database/schemas/. A key schema for developer-level configuration is Dev.ts.

Dev Schema

The dev-config schema manages global bot settings that are intended to be modified by developers without a new deployment. This includes the bot's presence, AI configuration, and cached bot statistics.

This Entity-Relationship diagram shows the structure of the dev-config document.

Dependencies and Automation

The project relies on a rich ecosystem of dependencies and automation tools to streamline development and maintenance.

Key Dependencies

The package.json file lists all project dependencies.

Package	Purpose
discord.js	The core library for interacting with the Discord API.
mongoose	An Object Data Modeling (ODM) library for MongoDB.
@google/generative-ai	Client for Google's Gemini AI models.
@upstash/vector	Client for Upstash Vector database, likely for AI memory.
lavalink-client	Client for a Lavalink node to provide music playback.
pino	A fast, low-overhead logger.
@semantic-release/*	A suite of tools for automated version management and package publishing.
eslint, prettier	Code linting and formatting to maintain code quality.

Sources: package.json:29-61

Automation with Renovate

The renovate.json file configures the Renovate bot to automatically manage dependency updates. It is configured to:

• Group related updates (e.g., eslint, semantic-release, discord.js).
• Automerge patch and minor devDependency updates to reduce maintenance overhead.
• Run on a schedule to avoid constant notifications.

*Sources: renovate.json *

CI/CD and Release Process

The project uses semantic-release with gitmoji to fully automate the release process. This is configured in release.config.js.

Release Workflow

The release process is triggered on every push to the main branch.

1. Commit Analysis: semantic-release analyzes commit messages. The type of release (major, minor, patch) is determined by the gitmoji used in the commits.
2. Changelog Generation: A CHANGELOG.md file is automatically updated based on the commits.
3. Version Bump: package.json version is updated.
4. Git Tagging: A new Git tag is created for the release.
5. GitHub Release: A new release is created on GitHub with generated release notes.

This diagram illustrates the automated release flow.

Gitmoji Release Rules

The release type is determined by specific gitmojis in commit messages.

Release Type	Gitmoji
patch	:bug:, :ambulance:, :lock:, :adhesive_bandage:
minor	:sparkles:, :rocket:, :lipstick:, :zap:
major	:boom:, :warning:

Sources: release.config.js:6-23

Conclusion

The Amina project is a well-structured and modern application that demonstrates best practices in Discord bot development. Its modular architecture, reliance on TypeScript for type safety, and extensive automation for testing, dependency management, and releases make it a robust and developer-friendly codebase. The clear separation of concerns between commands, handlers, configuration, and database schemas allows for efficient maintenance and future expansion.