FernandoJVideiraandClaude Sonnet 5.5
fefa74e045
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
77 lines
4.8 KiB
Markdown
77 lines
4.8 KiB
Markdown
# Velox Bot
|
|
|
|
Velox is a Discord bot written in Go, backed by PostgreSQL. It covers server security (anti-raid and anti-nuke), support tickets, moderation, leveling, music, meeting rooms, scheduling, Twitch alerts and a few games. Every module is off until a server turns it on.
|
|
|
|
This repository is the bot. It has two companions that live in their own repositories:
|
|
|
|
- **velox-dashboard-api**: a Go REST API behind the web dashboard. It owns most of the database schema and runs the migrations.
|
|
- **velox-dashboard-web**: the Vue dashboard and public website.
|
|
|
|
The bot and the API share one PostgreSQL database. They never call each other over HTTP. The dashboard writes settings and requests into tables, and the bot reads them (and is woken through Postgres `NOTIFY` where it has to react at once). See [Architecture](docs/architecture.md).
|
|
|
|
## Documentation
|
|
|
|
This README is the front page. The rest of the documentation lives in [`docs/`](docs/), organised like a wiki:
|
|
|
|
| Page | What is in it |
|
|
| --- | --- |
|
|
| [Getting started](docs/getting-started.md) | Requirements, creating the Discord application, configuration, database, running locally |
|
|
| [Deployment](docs/deployment.md) | Docker, Compose, upgrade order, backups |
|
|
| [Architecture](docs/architecture.md) | How the code is laid out, how an interaction flows through it, background loops, the link to the dashboard |
|
|
| [Features](docs/features.md) | What each module does and how it behaves |
|
|
| [Command reference](docs/commands.md) | Every slash command, its options and who may run it |
|
|
| [Database](docs/database.md) | Who owns the schema, the tables, the `NOTIFY` channels, how to change them |
|
|
| [Development guide](docs/development.md) | How to add commands, subcommands, buttons, events, background jobs, settings and tables; testing; code style |
|
|
| [Beta features](docs/beta-features.md) | How features are tried by a few testers before release |
|
|
| [Troubleshooting](docs/troubleshooting.md) | Common problems and what they mean |
|
|
|
|
## Quick start
|
|
|
|
You need Go (the version in `go.mod`), PostgreSQL 16 or newer, and a Discord application with a bot token.
|
|
|
|
```bash
|
|
git clone <this repository>
|
|
cd velox-bot
|
|
# create .env with BOT_TOKEN, APP_ID, GUILD_ID, DB_HOST and TWITCH_CLIENT_ID (see docs/getting-started.md)
|
|
docker compose up -d db # PostgreSQL on localhost:5432
|
|
psql "postgres://velox:velox_pwd@localhost:5432/velox?sslmode=disable" -f schema.sql
|
|
go run .
|
|
```
|
|
|
|
On start the bot registers its slash commands in the server named by `GUILD_ID` (or globally if that is empty). The full walkthrough, including the Discord side, is in [Getting started](docs/getting-started.md).
|
|
|
|
## What it does
|
|
|
|
- **Security**: Join Gate, raid mode, anti-nuke with quarantine, lockdowns, snapshots and restore, and a spam "heat" system, modelled on Wick.
|
|
- **Tickets**: a panel with categories, a private thread per ticket, claim and close, transcripts to a log channel.
|
|
- **Moderation**: purge, timeout, kick, ban, unban, slowmode, plus server logs for edits, deletes, joins, leaves, role changes, bans and mod actions.
|
|
- **Leveling**: XP per message, level cards, leaderboard, role rewards.
|
|
- **Music**: Lavalink-powered playback with a queue, controlled from Discord or the dashboard.
|
|
- **Meeting rooms**: join a lobby voice channel and get a temporary room you can lock and invite people to.
|
|
- **Scheduling and projects**: 1:1 sessions with DM invites and reminders, and a simple project list.
|
|
- **Twitch alerts, welcome messages, default role**: per-server setup through `/config`.
|
|
- **Fun**: `/ping`, `/joke`, `/coinflip`, `/dice`, `/rps` with stats and a leaderboard.
|
|
|
|
When the bot joins a server for the first time, toggleable systems start **disabled** and the person who invited it gets a DM with setup instructions.
|
|
|
|
## Repository layout
|
|
|
|
```
|
|
main.go wiring: config, database, repos, services, bot
|
|
internal/config environment variables
|
|
internal/bot Discord session, intents, event registration, startup
|
|
internal/commands slash commands, one package per feature, plus the dispatcher
|
|
internal/events handlers for gateway events and background loops
|
|
internal/db connection, repos (SQL), services (rules)
|
|
internal/security anti-raid and anti-nuke engine
|
|
internal/tickets ticket flows
|
|
internal/music Lavalink player, queue, buttons
|
|
internal/beta beta access gate
|
|
internal/modlog, rankcard small shared helpers
|
|
schema.sql mirror of the tables the bot reads and writes
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Start with the [Development guide](docs/development.md). In short: keep a command's definition and its handler in one package, keep SQL in a repo and rules in a service, and run `go build ./... && go vet ./... && go test ./...` before opening a pull request.
|