Velox Bot

A Discord bot written in Go with a PostgreSQL backing store.

It currently includes:

• Fun commands (/ping, /joke, /dice, /rps, …)
• Leveling system (opt-in per server via /slvl toggle)
• Meeting rooms (voice lobby → auto-created temporary voice channels)
• Scheduling (1:1 sessions with DM invites + reaction-based accept/decline/reschedule)
• Projects (list/create projects + helpers)
• Support tickets (a panel with categories, a private thread per ticket, claim/close, transcripts to a log channel)
• Music (Lavalink-powered /play, /queue, /volume)
• Twitch live notifications (per-guild /config setup)
• Welcome messages, DMs, and default role assignment (per-guild /config setup)
• Focused moderation tools (/moderation purge|timeout|untimeout|kick|ban|unban|slowmode)
• Server logging system (edits/deletes/joins/leaves/roles/ban/kick/mod actions)

When the bot is added to a new server for the first time, toggleable systems are defaulted to disabled and a setup DM is sent to the inviter (or server owner fallback) with enable instructions.

Requirements

• Go (see go.mod)
• PostgreSQL 16+ (or use the provided docker-compose.yml)
• (Optional) Air for live reload during development
• (Optional) Lavalink if you want music commands

Configuration

The app loads environment variables from .env (see internal/config/config.go).

Required:

• BOT_TOKEN: Discord bot token
• APP_ID: Discord application ID
• GUILD_ID: Target guild/server ID (commands are registered per-guild)
• DB_HOST: Postgres connection string (pgx), e.g. postgres://velox:velox_pwd@localhost:5432/velox?sslmode=disable

Optional (music):

• LAVALINK_HOST: Lavalink WebSocket/HTTP host (depends on your Lavalink setup)
• LAVALINK_PASSWORD: Lavalink password

Optional (Twitch live notifications):

• TWITCH_CLIENT_ID: Twitch Client ID used to query live status

Database setup

If you use the compose file:

docker compose up -d

Then apply the schema:

psql "postgres://velox:velox_pwd@localhost:5432/velox?sslmode=disable" -f schema.sql

Run

Plain Go:

go run .

With live reload (Air):

air

If you use just, a small workflow is included:

just up      # start postgres
just start   # start postgres + run air
just down    # stop postgres

Commands (high-level)

• Fun
  • /ping, /joke [type], /coinflip, /dice <expr>
  • /rps <hand>, /rpsstats, /rpsleaderboard (server only)
• Help
  • /help (sends a DM with command reference)
• Leveling
  • /slvl ... admin/config
  • /rank, /leaderboard, /rewards
• Meetings (Manage Server)
  • /meeting set-lobby, /meeting lock, /meeting lock-private, /meeting unlock, /meeting invite, /meeting uninvite
• Timezone
  • /timezone set, /timezone show
• Scheduling
  • /schedule create, /schedule list, /schedule reschedule
• Projects
  • /projects list, /projects create, /projects add-helper
• Tickets
  • /tickets setup channel:#tickets [log-channel] [staff-role] — Where tickets open and closed ones are logged (Manage Server)
  • /tickets category add|remove|list — One panel button per category, each with its own staff role (Manage Server)
  • /tickets panel — Post or refresh the panel (Manage Server)
  • /ticket add, /ticket close [reason] — Opener or staff; /ticket claim, /ticket remove — staff
  • The bot needs View Channel, Send Messages, Embed Links, Create Private Threads, Send Messages in Threads and Manage Threads in the ticket channel, and Attach Files in the log channel. Give the staff role Manage Threads there too, so staff see every ticket.
• Music (requires DJ role)
  • /play, /queue, /volume
• Moderation (focused + practical)
  • /moderation purge amount:<1-100> — Fast recent message cleanup (Manage Messages)
  • /moderation timeout user:@someone duration:<10m|1h|...> [reason] — Temporary member timeout (Moderate Members)
  • /moderation kick user:@someone [reason] — Kick member (Kick Members)
  • /moderation ban user:@someone [delete_days] [reason] — Ban member (Ban Members)
  • /moderation unban user_id:<id> [reason] — Unban by user ID (Ban Members)
  • /moderation untimeout user:@someone [reason] — Remove timeout (Moderate Members)
  • /moderation slowmode channel:#channel seconds:<0-21600> — Control channel flood (Manage Channels)
• Twitch live notifications (Manage Server)
  • /config addstreamer username:<twitch-name> — Add a streamer for notifications
  • /config removestreamer username:<twitch-name> — Remove a streamer
  • /config settwitchnotificationchannel channel:#channel — Channel for live pings
• Welcome / onboarding (Manage Server)
  • /config setwelcomechannel channel:#channel — Channel for welcome messages
  • /config setwelcomemessage message:"..." — Server welcome template (supports {user}, {server})
  • /config setwelcomedm message:"..." — DM welcome template (supports {user}, {server})
  • /config setwelcomegif url:<image-url> — GIF/image used in welcome embed
  • /config setdefaultrole role:@role — Role automatically granted on join
• Logging (Manage Server)
  • /config setlogchannel channel:#channel — Set where logs are sent
  • /config enablelogging — Enable event/moderation logs
  • /config disablelogging — Disable event/moderation logs

Notes

• Slash commands are registered to the configured GUILD_ID on startup.
• Some features require server permissions (e.g. Manage Server) or roles (e.g. DJ for music).