🤖 Bot Overview

This page gives a high-level overview of the live Magikal Discord bot.

It is based on the current live project structure from:

/home/magikalbot/magikal-bot

What the bot does

The Magikal bot is a private Discord server management bot.

It provides:

• moderation tools
• tickets and recruitment applications
• Temp VC management
• modlogs and event logs
• reaction roles
• welcome/introduction tools
• Star Citizen ship, market, item, RSI, and UEX features
• AI assistant features
• XP/rank features
• event tools
• banking tools
• admin configuration
• diagnostics and command auditing

Main project path

Live bot project:

/home/magikalbot/magikal-bot

Main entry point:

bot/main.py

Cogs:

bot/cogs/

Shared utilities:

bot/utils/

Storage adapters:

bot/storage/

Database and models:

bot/database.py

Alembic migrations:

migrations/versions/

Runtime

The live bot runs from the VPS using systemd.

Service name:

magikal-bot

Restart:

sudo systemctl restart magikal-bot

Check status:

sudo systemctl status magikal-bot --no-pager

Check logs:

sudo journalctl -u magikal-bot -n 120 --no-pager

Current cog loading

The bot loads cogs from the initial_extensions list in:

bot/main.py

Current loaded cogs include:

Cog	Purpose
moderation	Warnings, timeouts, bans, quarantine, purge, locks, slowmode
autoroles	Auto role assignment tools
reaction_roles	Reaction role panels and role assignment
tempvc_v2	Temporary voice channels and owner controls
basic	Core commands, help, sync, healthcheck
admin_config	Server configuration commands
diag_storage	Storage diagnostics
tickets	Ticket panels and recruitment applications
shipinfo_uex	Star Citizen ship lookup
market_uex	UEX market/item/refinery/commodity tools
embed_tools	Embed creation/editing tools
rsi_profile	RSI profile lookup
welcome	Welcome, rules, and introduction flow
diag_commands	Command diagnostics
help_auditor	Help command auditing
help_panel	Role-aware help panels
event_modal	Discord event creation modal flow
automod	Automated moderation checks
modlog_events	Discord event logging
voice_events	Voice channel event logging
banking	Org banking and loan tools
recruit_config	Recruitment configuration tools
events	Event signup/role tools
xp	XP, rank, leaderboard, and voice XP
command_dump	Command dump/debug helper
roles_config	Role/capability configuration
rsi_status	RSI status tools
ai_assistant	AI assistant commands and channel replies

Live cog list

This list should be checked against bot/main.py when the bot changes.

Do not treat old documentation as the source of truth.

Storage model

Postgres is the primary source of truth.

The normal cog access layer is:

self.config_storage

or:

self.bot.config_storage

The current main adapter is:

PgConfigStorage

State storage is exposed through:

self.bot.state_storage

The bot also has storage adapters for:

• Postgres config
• Postgres state
• Redis
• in-process ephemeral fallback storage

Storage rule

New persistent features should use Postgres-backed storage.

Do not introduce SQLite unless explicitly approved.

Privacy model

The bot follows a privacy-first logging and storage model.

User-related logs and records should use privacy-safe PIDs.

Helper:

make_pid(guild_id, user_id)

Common fields:

• guild_pid
• user_pid
• actor_pid
• channel_pid
• member_pid

Do not log:

• raw Discord user IDs
• raw Discord mentions
• bot tokens
• OAuth secrets
• database URLs
• full Discord objects
• private message contents

Logging model

The bot uses structlog.

Common pattern:

import structlog

logger = structlog.get_logger(__name__)

Use stable event names:

logger.info(event="feature.action")
logger.warning(event="feature.failed", error=str(e))

Logs should be useful for debugging without exposing private data.

Database and migrations

Database models and database manager logic live in:

bot/database.py

Alembic migrations live in:

migrations/versions/

Migration commands must use the bot virtual environment and project Alembic config.

See:

Operations -> Migrations

Migration safety

Before any real migration, confirm the documented migration process still matches the live VPS setup.

Also confirm the latest database backup is non-zero.

Bot configuration

Bot configuration comes from:

/etc/magikal-bot.env

This environment file is loaded by the systemd service and is also used before Alembic commands.

Do not paste or expose secrets from this file.

Web panel relationship

The web panel is separate from the bot project.

Panel project:

/home/magikalbot/magikal-panel

The panel should save settings into Postgres-backed config.

Expected flow:

Web panel -> FastAPI -> Postgres/cfg tables -> bot reads config

Single source of truth

The panel must not create a separate config source that disagrees with the bot.

Safe change workflow

Before changing live bot code:

1. Check the live file.
2. Check Git status.
3. Create or confirm a restore point.
4. Make one focused change.
5. Restart the bot if needed.
6. Check logs.
7. Commit the completed change.
8. Update docs if behaviour changed.

Check Git:

cd /home/magikalbot/magikal-bot
git status --short

Create restore point:

git add .
git commit -m "restore point before bot change"

Useful docs

Related pages:

• Developer Guide -> Coding Rules
• Developer Guide -> Logging & Privacy
• Developer Guide -> Database Rules
• Developer Guide -> Adding a Cog
• Operations -> Restart Services
• Operations -> Logs
• Operations -> Backups
• Operations -> Migrations

Rule

The bot should stay simple, privacy-safe, Postgres-backed, and documented from the current live files.