Module System (Cogs)

ArcBot is built with a modular architecture. Each feature is a separate module (cog) that can be independently enabled and disabled per-server.

What is a Cog?

A cog (short for "cogwheel") is a self-contained bot module containing:

• Slash commands (e.g., /ban, /poll)
• Event listeners (e.g., member join)
• Scheduled tasks (e.g., checking expired polls)
• Configuration stored in the database

Available Modules

Administration

Module	Description
Settings	Server settings (language, color, dashboard users) — always enabled
Moderation	Ban, kick, mute, warn, clear, setnick, role

Community

Module	Description
Welcome	Welcome and goodbye messages
Reaction Roles	Self-assign roles via buttons, dropdown, reactions
Suggestions	Suggestion system with voting
Polls	Polls with buttons and timer
Duel Reminder	Daily duel strategy reminders
Schedule Events	Scheduled events with reminders

Utilities

Module	Description
Logs	Configurable action logging
Translation	Message translation (DeepL) and audio transcription (Groq Whisper)
Message Builder	Creating and sending embeds from templates

Dark War Survival

Module	Description
Alliances	Alliance management with R1–R5 ranks
Presidents	Server president system
Armory	Armory rotation with alliance assignments

Enabling and Disabling Modules

Via dashboard

1. Open dashboard → Your server
2. In the module grid, find the tile for the desired module
3. Click the toggle switch
4. Done — the change is instant

What happens after enabling?

1. The configuration is saved to the database (enabled_cogs)
2. The bot detects the change within 5 seconds (config polling)
3. Commands associated with the module are synced with the Discord API
4. Commands appear in the slash menu on the server

What happens after disabling?

1. The module is removed from enabled_cogs
2. The bot detects the change within 5 seconds
3. Commands disappear from the slash menu
4. Events (e.g., on_member_join for Welcome) stop responding
5. The module's configuration is not deleted — after re-enabling, all settings are preserved

tip

Disabling a module does not delete its configuration. You can safely disable a module "for a while" and re-enable it with the same settings.

Config Polling — How Does the Bot Detect Changes?

ArcBot uses a polling mechanism to synchronize configuration:

1. Every 5 seconds the bot checks the database for changes to the updated_at column of any configuration
2. If a change is detected, it updates the in-memory cache
3. If the enabled_cogs list has changed, it emits an on_config_update event
4. This event triggers command resynchronization for the given server

Dashboard → User clicks toggle
    ↓
API → Updates `enabled_cogs` + `updated_at` in DB
    ↓ (max 5 seconds)
Bot → Config polling detects `updated_at` change
    ↓
Bot → Updates cache, emits `on_config_update`
    ↓
Bot → Syncs commands for the given server
    ↓
Discord → Commands appear / disappear from the slash menu

Propagation Time

Between clicking the toggle in the dashboard and the command appearing on the server, it usually takes 5–10 seconds. This is the time needed for: DB write + polling + Discord API sync.

The "Settings" Module — Pseudo-cog

The Settings tile in the dashboard is special:

• Has no toggle — it's always enabled
• Contains no slash commands
• Manages server settings: language, default embed color, dashboard_users list

Protection Against Executing Disabled Commands

Even if a command remained in Discord's cache after disabling a module, the @guild_cog_enabled decorator blocks its execution:

1. Checks enabled_cogs from the ConfigManager cache
2. If the module is not enabled → CheckFailure with a translated message
3. The user sees an ephemeral message "This module is disabled"

Module Configuration

Each module stores its configuration in the cog_settings column (JSONB) of the guild_configs table:

{
  "moderation": {
    "moderation_roles": ["123456789"],
    "warning_threshold": 3,
    "dm_on_action": true,
    "auto_delete_warnings_days": 0
  },
  "welcome": {
    "welcome": { "enabled": true, "channel_id": "...", "type": "embed", ... },
    "goodbye": { "enabled": true, "channel_id": "...", ... }
  },
  "logs": {
    "moderation": { "enabled": true, "channel_id": "...", "color": "#5865F2" },
    "welcome": { "enabled": false, "channel_id": null, "color": "#22C55E" }
  }
}

Editing Configuration

1. In the dashboard, click Edit on the module tile
2. Change settings
3. The UnsavedBar will appear at the bottom of the screen
4. Click Save to save or Cancel to revert changes

warning

Don't close the page without saving changes! The dashboard will warn you with a flashing bar, but changes will be lost.

Discord Permissions Required by Modules

Each module declares a list of Discord permissions it needs to function:

Module	Required Bot Permissions
Moderation	ban_members, kick_members, moderate_members, manage_messages, manage_nicknames, manage_roles
Welcome	send_messages, embed_links
Logs	send_messages, embed_links
Reaction Roles	manage_roles, send_messages, add_reactions
Suggestions	send_messages, embed_links, create_public_threads, add_reactions
Polls	send_messages, embed_links
Message Builder	send_messages, embed_links
Translation	— (requires DeepL API key)
Alliances	manage_roles
Presidents	manage_roles
Armory	manage_roles
Duel Reminder	send_messages
Schedule Events	send_messages, manage_messages

tip

If the bot doesn't have the required permission, the action will fail with a "Missing permission" error. Make sure the bot's role has the appropriate permissions on the channels where it should operate.