Role Management

Relevant source files

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

• src/handlers/roles/main-hub.ts
• src/handlers/roles/autorole/index.ts
• src/handlers/roles/create/index.ts
• src/handlers/roles/add-to-user/index.ts
• src/handlers/roles/cleanup/preview.ts
• src/handlers/roles/cleanup/parameter-handlers.ts
• src/events/interactions/interactionCreate.ts
• src/data/respAdmin.json

The Role Management system in Amina provides a comprehensive suite of tools for server administrators to create, assign, and maintain roles efficiently. Accessed via the /roles command, this feature is designed as an interactive, menu-driven hub that guides users through various role-related operations, from creating single roles with specific permissions to performing bulk actions like assigning roles to multiple users or cleaning up unused roles.

The system is composed of several modular handlers, each responsible for a specific function such as role creation, autorole configuration, bulk assignment, and cleanup. These handlers are triggered by user interactions (button clicks, menu selections) which are routed from the main interactionCreate event listener. This modular design allows for a clean separation of concerns and a guided, step-by-step user experience for complex operations.

Sources: src/handlers/roles/main-hub.ts, src/events/interactions/interactionCreate.ts:182-225

Main Hub

The entry point to the Role Management system is the main hub, which is presented to the user upon selecting the "Roles" option in the admin menu. This hub displays a select menu with all available role operations.

Sources: src/handlers/roles/main-hub.ts:12-39, src/data/respAdmin.json:20-44

The following diagram illustrates the user flow starting from the main hub.

The operations available in the hub are defined in respAdmin.json and dynamically loaded into the select menu.

Operation	Description	Handler File
Cleanup Roles	Bulk delete roles based on various criteria.	cleanup/*
Create Role	Create a new role with basic or advanced options.	create/index.ts
Autorole	Manage automatic role assignment for new members.	autorole/index.ts
Add to User	Assign one or more roles to multiple users at once.	add-to-user/index.ts

Sources: src/data/respAdmin.json:28-44, src/handlers/roles/main-hub.ts:41-58

Role Creation

This feature allows for the creation of new server roles through a guided interface. It offers two distinct paths: "Basic" and "Advanced".

Sources: src/handlers/roles/create/index.ts

Basic vs. Advanced Setup

• Basic Setup: A streamlined process that prompts the user for only the role name and an optional color via a modal. The role is created immediately upon submission with no special permissions.
• Advanced Setup: In addition to the name and color, this path allows the user to select a permission preset (e.g., Administrator, Moderator) after submitting the initial modal.

Sources: src/handlers/roles/create/index.ts:19-41, src/handlers/roles/create/index.ts:133-140

The flow for creating a role is as follows:

Permission Presets (Advanced)

In the advanced flow, users can choose from predefined sets of permissions to quickly configure a role for a common purpose.

Preset	Description	Key Permissions Granted
Administrator	Full server permissions.	Administrator (1n << 3n)
Moderator	Manage messages, members, and channels.	KickMembers, BanMembers, ManageMessages, ManageChannels, ModerateMembers, ViewAuditLog
Support	Manage messages and view logs.	ManageMessages, ViewAuditLog
None	No special permissions.	None

Sources: src/handlers/roles/create/index.ts:182-191, src/handlers/roles/create/index.ts:208-233

Autorole

The Autorole system automatically assigns a specified role to new members when they join the server. The configuration is managed through an interactive menu where an administrator can enable, disable, or change the role being assigned.

Sources: src/handlers/roles/autorole/index.ts

Configuration

The main autorole menu displays the current status (enabled with a specific role, or disabled). From here, an admin can:

1. Enable/Change: Opens a role selection menu to choose the role to be assigned.
2. Disable: Presents a confirmation prompt to turn off the autorole feature.

The selected role's ID is stored in the guild's settings in the database.

Sources: src/handlers/roles/autorole/index.ts:19-61, src/handlers/roles/autorole/index.ts:121-124

Validation

Before a role can be set as the autorole, it must pass several validation checks to ensure the bot can assign it correctly and to prevent misconfiguration.

Rule	Reason for Failure
Cannot be @everyone	This role is assigned to all members by default.
Bot needs ManageRoles permission	The bot lacks the fundamental permission to assign any roles.
Role position must be lower than bot's highest role	The bot cannot assign roles that are at or above its own position in the role hierarchy.
Role cannot be managed by an integration	Roles managed by other bots or applications (e.g., server booster roles) cannot be assigned manually.

Sources: src/handlers/roles/autorole/index.ts:219-254

The following sequence diagram shows the process when a new member joins a server with autorole enabled.

Bulk Role Assignment (Add to User)

This feature provides a powerful way to assign one or more roles to up to 25 users simultaneously. The process is broken down into a three-step wizard to ensure accuracy.

Sources: src/handlers/roles/add-to-user/index.ts

The user flow is as follows:

1. Select Users: The admin is presented with a user select menu.
2. Select Roles: After selecting users, a role select menu appears, showing only roles that the bot can assign (i.e., roles below its own highest role).
3. Preview & Confirm: A summary embed is shown, detailing which users will receive which roles, how many new assignments will occur, and how many are skipped because the user already has the role. The admin must click a final confirmation button to execute the changes.

State Management

To pass the list of selected users from the user selection step to the role selection step, and then both users and roles to the confirmation step, the data is serialized and encoded. The user IDs are stringified into a JSON array, which is then converted to a Base64 string and embedded in the custom_id of the next component (e.g., the role select menu or the confirmation button). This allows the state to be passed through the interaction flow without needing a separate storage mechanism.

Sources: src/handlers/roles/add-to-user/index.ts:90-93, src/handlers/roles/add-to-user/index.ts:129-133, src/handlers/roles/add-to-user/index.ts:221-226

Role Cleanup

The Role Cleanup utility allows for the bulk deletion of roles based on a set of predefined criteria. This helps server administrators maintain a clean and manageable role list.

Sources: src/handlers/roles/cleanup/preview.ts, src/handlers/roles/cleanup/parameter-handlers.ts

Cleanup Methods

The system provides several methods for identifying roles to be deleted.

Method	Description	Parameters
empty	Deletes roles that have zero members.	None
prefix	Deletes roles whose names start with a specific prefix.	prefix (string)
below	Deletes roles that are below a certain position in the hierarchy.	position (number)
older	Deletes roles that were created more than a specified number of days ago.	days (number)

Sources: src/handlers/roles/cleanup/preview.ts:22-51, src/handlers/roles/cleanup/parameter-handlers.ts:28-102

Deletion Logic & Safety

Before deletion, the system filters the matched roles to prevent accidental deletion of important or unmanageable roles.

• Skipped Roles: @everyone, managed roles (e.g., from integrations), and roles at or above the bot's highest role position are automatically skipped.
• Exclusions: Admins can manually select specific roles to "keep" (exclude from deletion) during the setup process.
• Safety Cap: A hard limit of 250 roles is enforced for a single cleanup operation to prevent catastrophic mistakes. If more than 250 roles are matched for deletion, the operation is blocked.

Sources: src/handlers/roles/cleanup/preview.ts:65-87, src/handlers/roles/cleanup/preview.ts:109-110

The following diagram outlines the cleanup process.

Interaction Routing

All interactions within the Role Management system are routed through the interactionCreate event handler. It uses the custom_id of components (buttons, menus) to determine which specific handler function to execute. The custom_ids follow a consistent pattern, typically roles:<type>:<action>, which allows for clear and efficient routing.

For example:

• A button click with custom_id: 'roles:btn:create_basic' is routed to showCreateRoleModal.
• A menu selection with custom_id: 'roles:menu:operation' is routed to handleRolesOperationMenu.
• A role selection with custom_id: 'roles:role:autorole_select' is routed to handleAutoroleRoleSelect.

This centralized routing logic connects the UI components with their corresponding business logic in the various handler files.

Sources: src/events/interactions/interactionCreate.ts:182-225, src/events/interactions/interactionCreate.ts:468-487, src/events/interactions/interactionCreate.ts:690-705

Conclusion

The Role Management feature is a powerful and user-friendly tool for server administration in Amina. By leveraging Discord's interactive components, it provides guided workflows for complex tasks like bulk role assignment and cleanup, while implementing crucial safety checks to prevent errors. Its modular architecture, with distinct handlers for each operation and a central routing system, makes the feature robust, maintainable, and easy to extend. The system effectively abstracts away the complexity of the Discord API, allowing administrators to manage their server's roles with confidence and ease.