What is SuperStar?
SuperStar is a Discord bot that helps server members and moderators. Depending on what your server has enabled, you can use it to check your rank, earn Stars, give reputation, join activities, or get support from moderators.
These docs are public and written for people who use SuperStar—not developers building the bot. Server admins can also use them to understand available features and get their server set up.
/rank in your server to see what it does. Some features are available only when a server admin has enabled or configured them.What SuperStar does
Use these commands in Discord by typing / and choosing SuperStar from the command list. For example, /rank shows your level and progress.
Moderation and cases
Clear messages, kick, ban and unban users, timeout, warn, review warning history, remove warnings, lock or unlock channels, set slow mode, and inspect moderation cases. Runtime checks enforce Discord permissions, bot permissions, and role hierarchy.
/clear /kick /ban /timeout /warn /case
Security and protection
Scan public account signals, configure a security log, enable local AutoMod rules and escalation, detect raid-like join or message bursts, and monitor anti-nuke thresholds. Raid response can lock channels until a moderator ends lockdown.
/security /automod /raid /lockdown
Levels and reputation
Track message XP, show ranks and leaderboards, configure announcements and milestone roles, exclude selected users, roles, or channels, and let members give positive reputation. Daily quests and activity streaks add participation goals.
/levels /rank /rep /streak /quest
Stars economy
Members earn and spend Stars through daily rewards, jobs, a shop, and games. They can view balances and inventories, transfer Stars, earn achievements, and compare balances. Managers can grant Stars and configure reward limits.
/economy /profile
Community operations
Create private support tickets with claim and close controls, configure verification panels and roles, post welcome and leave messages, publish suggestions for voting, run giveaways, schedule reminders, create button roles, and maintain a starboard.
/ticketsetup /verification /welcome /suggest /giveaway
Analytics and custom tools
Opt in to server activity reporting, view activity rankings, build text-triggered custom commands, create join goals, and subscribe channels to SuperStar updates. Prefix commands can be disabled independently of slash commands.
/analytics /leaderboard /custom /goal /updates
Command guide
| Area | Commands |
|---|---|
| Getting started | /help, /info, /ping, /setup, /diagnose |
| Member and server info | /serverinfo, /userinfo, /avatar |
| Moderation | /clear, /kick, /ban, /unban, /timeout, /warn, /warnings, /unwarn, /lock, /unlock, /slowmode, /case |
| Safety | /security, /automod, /raid, /lockdown |
| Community and participation | /levels, /rank, /leaderboard, /rep, /rep-leaderboard, /streak, /quest, /profile, /economy, /birthday, /goal |
| Server features | /admins, /custom, /analytics, /connect, /giveaway, /suggest, /suggestion, /ticketsetup, /ticket, /verification, /welcome, /reactionrole, /schedule, /starboard, /updates, /trailer |
Analytics are opt-in. While enabled, the bot records join and leave events and message activity for reporting; disabling analytics removes collected per-server analytics data. See the Privacy Policy for the current data summary.
How the pieces fit
| Path | Responsibility |
|---|---|
discordbot/main.go | Loads configuration, opens the Discord session, registers commands, binds gateway events, and coordinates shutdown. |
discordbot/bot/ | Shared runtime: Bot and Config, event handlers, message workers, background sweeps, replies, moderation support, and feature state. |
discordbot/commands/ | Slash command schemas, routing, and handlers. Handlers operate on *bot.Bot. |
discordbot/services/storage.go | In-memory guild state and Supabase persistence. Rapid updates are coalesced before network writes. |
WebsiteSystems/superstarwebsite/ | Static public site, sign-in pages, dashboard UI, styles, and browser-side scripts. |
WebsiteSystems/backend/ | Go dashboard API for authentication, dashboard keys, linked servers, settings, and analytics reads. |
WebsiteSystems/web/ | Local static-file server with API proxying and live reload for website development. |
The dependency direction is main → bot, main → commands, and commands → bot. Keep Discord session wiring in main; the shared bot package should not import command handlers.
The bot listens for Discord gateway events, routes interactions to command handlers, and queues message work to bounded workers. The dashboard is a separate HTTP service. Its API reads bot state from the shared Supabase project and can request supported setting changes for the bot to apply.
Run the project
Install Go and clone the repository. Bun is only needed for the convenience scripts that launch website development. Keep credentials in local env files and never commit them.
Discord bot
Provide the bot's environment variables in local env files, then start the development bot from the repository root:
go -C discordbot run . --env-file=../.env.dev --supabase-env-file=../.env.supabaseTo register commands without keeping the gateway session open, add --register. Set DISCORD_GUILD_ID for quick guild-scoped development registration; leave it empty for global registration.
Website and dashboard API
Start the API and static website in separate terminals. The website dev server proxies /api/* to the API and reloads pages when files change.
go -C WebsiteSystems run ./backend -env-file=backend/.env.supabasego -C WebsiteSystems run ./webOr use bun run website:dev to launch both services with file watching. The default local origins are the website at http://localhost:4173 and API at http://localhost:8787.
Useful repository commands
bun run go
go -C discordbot vet ./...
go -C discordbot build ./...
go -C WebsiteSystems build ./...Run Go commands from the module they target. The root go.work ties the Go modules together for workspace-aware tooling.
Environment variables
Processes read environment variables first, then fill missing values from their selected env files. This table lists variable names and purpose only; put actual values in your local secret store.
| Service | Variable | Purpose |
|---|---|---|
| Bot | DISCORD_TOKEN | Bot authentication token. |
| Bot | DISCORD_CLIENT_ID | Discord application ID used for command registration. |
| Bot | SUPABASE_URL | Supabase project URL. |
| Bot | SUPABASE_SECRET_KEY or SUPABASE_SERVICE_ROLE_KEY | Server-side key used by the bot state store. |
| Bot | DISCORD_GUILD_ID | Optional development guild for fast command registration. |
| Bot | UPDATES_PUBLISHER_GUILD_ID | Guild allowed to receive the publisher-only updates command. |
| Bot | PREFIX | Prefix for custom text commands; defaults to !. |
| Bot | ENABLE_PREFIX_COMMANDS | Set false to turn off prefix commands without disabling slash commands. |
| Bot | ALERT_USER_ID | Recipient for rate-limited operational failure DMs; blank falls back to the built-in owner target. |
| Dashboard | SUPABASE_URL, SUPABASE_SECRET_KEY, SUPABASE_PUBLISHABLE_KEY | Supabase project and dashboard API configuration. |
| Dashboard | DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET, DISCORD_REDIRECT_URL | Discord OAuth application settings. The redirect URL ends in /api/auth/discord/callback. |
| Dashboard | DASHBOARD_WEBSITE_ORIGIN, PORT | Allowed site origin and API listen port; defaults to localhost and port 8787. |
| Website | WEB_PORT, SUPERSTAR_API_ORIGIN, WEBSITE_ROOT | Static server port, proxied API origin, and website directory. |
Bot startup flags choose env files: --env-file for Discord settings and --supabase-env-file for storage settings. The backend uses -env-file and loads a sibling Discord OAuth env file when present. Never put secret values in frontend assets.
Invite SuperStar to your server
A server owner or administrator can add SuperStar with the Add SuperStar button at the top of this page. Review the requested Discord permissions during the invite, then use /setup in your server for a setup checklist.
Some moderation and server management commands require administrator or moderator permissions. SuperStar may also need the relevant Discord permissions to carry out an action, such as managing messages or roles.
Privacy and data
Some features use information such as server activity to provide rankings or analytics. Analytics are opt-in for each server. Message content is not stored for dashboard analytics.
For details about what information SuperStar handles, see the Privacy Policy.
Website and dashboard
Visit the SuperStar website to learn about features and access the dashboard. Server managers can connect a server with /connect and follow the prompts. The dashboard provides access to supported server settings and analytics.
Need a hand?
Use /help to browse commands in Discord, /setup for a server checklist, or /diagnose if you manage the server and need to check its bot setup.