Database Schema
Relevant source files
The following files were used as context for generating this wiki page:
The Amina bot utilizes MongoDB as its database, with Mongoose serving as the Object Data Modeling (ODM) library to define and interact with the data. This structure provides a robust and scalable persistence layer for all bot functionalities, from guild-specific configurations and user profiles to AI memories and moderation logs.
The schemas are defined in the src/database/schemas/ directory, and their corresponding TypeScript interfaces are located in types/schemas.d.ts. This ensures type safety and clear data contracts throughout the application. The core entities are Guild, User, and Member, which form the foundation for storing server, user, and per-server user data, respectively. Additional schemas support specific features like AI, reminders, and games.
Entity Relationship Diagram
The following diagram illustrates the primary relationships between the core database collections.
Core Schemas
These schemas represent the fundamental entities within the bot's data model.
Guild Schema
This collection stores all settings and configurations specific to a Discord server (guild). The _id of each document is the Discord Guild ID.
Sources: types/schemas.d.ts:11-125
| Field | Type | Description |
|---|---|---|
_id | string | The Discord Guild ID. |
server | object | Core server information like name, region, owner, and setup status. |
stats | object | Configuration for the server statistics and leveling system. |
ticket | object | Settings for the ticket system, including log channel, limit, and topics. |
automod | object | Auto-moderation rules, such as anti-invite, anti-spam, and strike limits. |
invite | object | Settings for invite tracking and invite-based ranks. |
logs_channel | string | The channel ID for general-purpose logs. |
logs | object | Granular settings for logging specific events (message edits, role changes, etc.). |
max_warn | object | Defines the action (TIMEOUT, KICK, BAN) to take when a member reaches the warning limit. |
counters | Array<object> | Configuration for member-count or other dynamic channel-name counters. |
greeting | object | Settings for the welcome message for new members. |
farewell | object | Settings for the farewell message when members leave. |
autorole | string | The role ID to automatically assign to new members. |
reaction_roles | Array<object> | Configuration for reaction-based role assignment. |
suggestions | object | Settings for the server suggestion system. |
aiResponder | object | Configuration for the AI responder, including free-will channels and mention-only mode. |
colors | Array<object> | Custom color roles that members can assign to themselves. |
User Schema
This collection stores global data for a Discord user, independent of any specific guild. The _id is the Discord User ID.
Sources: types/schemas.dts:127-195
| Field | Type | Description |
|---|---|---|
_id | string | The Discord User ID. |
username | string | The user's Discord username. |
discriminator | string | The user's Discord discriminator (e.g., #0001). |
coins | number | The user's on-hand currency for the economy system. |
bank | number | The user's banked currency for the economy system. |
minaAi | object | User-specific preferences for the AI, such as ignoreMe and allowDMs. |
reputation | object | Tracks reputation points given and received. |
daily | object | Tracks the user's daily reward streak and timestamp. |
redflags | Array<object> | A list of "red flags" given to the user by others. |
flags | Array<object> | A list of administrative flags placed on the user's account. |
afk | object | Stores the user's AFK status, reason, and timing. |
profile | object | Contains user-provided profile information like pronouns, bio, interests, and privacy settings. |
Member Schema
This collection acts as a join table between User and Guild, storing data about a user's status within a specific guild. The _id is a composite key of guild_id:member_id.
Sources: types/schemas.d.ts:197-214
| Field | Type | Description |
|---|---|---|
_id | string | Composite key in the format guild_id:member_id. |
guild_id | string | The ID of the guild the member belongs to. |
member_id | string | The ID of the user. |
strikes | number | The number of automod strikes the member has received. |
warnings | number | The number of warnings the member has received. |
invite_data | object | Data related to invites, including the inviter and counts of tracked, fake, and left invites. |
created_at | Date | Timestamp of when the member document was created. |
updated_at | Date | Timestamp of when the member document was last updated. |
Feature-Specific Schemas
These schemas support discrete features within the bot.
AiMemory Schema
This schema is central to the AI's long-term memory capabilities. It stores facts and information extracted from conversations, which are then used to provide more contextually aware responses. Each memory is also associated with a vector in an Upstash Vector database for efficient similarity searches.
Sources: src/database/schemas/AiMemory.ts:5-28
| Field | Type | Description |
|---|---|---|
userId | string | The user associated with the memory. Indexed. |
guildId | string | The guild where the memory was created (null for DMs). Indexed. |
memoryType | string | The type of memory (user, guild, topic). Indexed. |
key | string | The key or subject of the memory (e.g., "Favorite Color"). |
value | string | The value of the memory (e.g., "Blue"). |
context | string | A snippet of the conversation that generated the memory. |
importance | number | A score from 1-10 indicating the memory's importance. |
vectorId | string | The unique ID of the corresponding vector in Upstash. |
lastAccessedAt | Date | Timestamp of the last time this memory was recalled. |
accessCount | number | A counter for how many times the memory has been accessed. |
The schema includes several compound indexes to optimize queries for recalling memories based on user, guild, and importance.
Sources: src/database/schemas/AiMemory.ts:31-33
Reminder Schema
This schema stores user-created reminders. It includes a caching layer (lru-cache) to reduce database lookups for frequently accessed reminders.
Sources: src/database/schemas/Reminder.ts:8-29
| Field | Type | Description |
|---|---|---|
_id | string | A unique ID in the format user_id:reminder_id. |
user_id | string | The ID of the user who created the reminder. Indexed. |
reminder_id | number | A sequential ID for the reminder, unique per user. |
message | string | The content of the reminder message. |
remind_at | Date | The timestamp when the reminder should be sent. Indexed. |
channel_id | string | The channel where the reminder was created and should be sent. |
guild_id | string | The guild where the reminder was created (null for DMs). |
notified | boolean | A flag to indicate if the user has been notified. Indexed. |
A background scheduler queries for documents where remind_at is in the past and notified is false to send out due reminders.
Sources: src/database/schemas/Reminder.ts:145-151
Dev Schema
This special collection, dev-config, stores global configurations managed by the bot developers. It is a singleton document that centralizes settings for the bot's presence, AI behavior, and internal statistics. On first run, it is seeded with default values from src/config/config.ts.
Sources: src/database/schemas/Dev.ts:9-105
| Field | Type | Description |
|---|---|---|
PRESENCE | object | Controls the bot's Discord presence (status, activity message, etc.). |
DEV_COMMANDS | object | A toggle to enable or disable developer-only commands. |
AI_CONFIG | object | Global configuration for the AI, including the model, token limits, system prompt, and temperature. |
BOT_STATS | object | Caches bot-wide statistics like guild count, user count, and ping, which are periodically updated. |
TruthOrDare Schema
This schema stores the questions for the "Truth or Dare" and related games.
Sources: src/database/schemas/TruthOrDare.ts:3-16
| Field | Type | Description |
|---|---|---|
category | string | The game category (e.g., dare, paranoia, wyr). |
questionId | string | A unique, prefixed ID for the question (e.g., D123). |
question | string | The text of the question. |
rating | string | The age rating of the question (PG, PG-16, R). Legacy questions may be null. |
Conclusion
The database schema of Amina is well-structured and modular, using Mongoose to enforce data consistency. The separation of concerns between global user data (User), server-specific settings (Guild), and contextual user data (Member) provides a flexible and scalable foundation. Feature-specific schemas like AiMemory and Reminder are self-contained, allowing for independent development and maintenance. The use of TypeScript interfaces and strategic indexing further enhances the reliability and performance of the data persistence layer.