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

Open dashboard → Your server

In the module grid, find the tile for the desired module

Click the toggle switch

Done — the change is instant

What happens after enabling?

The configuration is saved to the database (enabled_cogs)

The bot detects the change within 5 seconds (config polling)

Commands associated with the module are synced with the Discord API

Commands appear in the slash menu on the server

What happens after disabling?

The module is removed from enabled_cogs

The bot detects the change within 5 seconds

Commands disappear from the slash menu

Events (e.g., on_member_join for Welcome) stop responding

The module's configuration is not deleted — after re-enabling, all settings are preserved

Safe to disable

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:

Every 5 seconds the bot checks the database for changes to the updated_at column of any configuration

If a change is detected, it updates the in-memory cache

If the enabled_cogs list has changed, it emits an on_config_update event

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:

Checks enabled_cogs from the ConfigManager cache

If the module is not enabled → CheckFailure with a translated message

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

In the dashboard, click Edit on the module tile

Change settings

The UnsavedBar will appear at the bottom of the screen

Click Save to save or Cancel to revert changes

Don't forget to save!

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`

Missing permissions?

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.