A high-performance game engine API for BrandishBot, built with Go. Provides inventory management, crafting, economy, and statistics tracking for live chatroom gaming experiences.
- Inventory Management: Add, remove, trade, and track items
- Crafting System: Recipe-based item crafting and upgrading
- Economy: Buy/sell items with dynamic pricing
- Expeditions: Cooperative multiplayer adventures with procedural encounters
- Quests: Weekly challenges for rewards and XP
- Farming: Harvest resources over time
- Lootboxes & Quality: Open tiered lootboxes with item quality levels
- Slots Minigame: Play slots for money and XP
- Gamble: Wager lootboxes in winner-takes-all pools
- Jobs: RPG-style job progression (Blacksmith, Merchant, etc.)
- Daily Reset: Scheduled daily tasks and limit resets
- Subscriptions: Integration with Twitch/YouTube subscriptions
- Traps: Place hidden traps and mines on other users
- Statistics: User and system stats with leaderboards
- Composting: Recycle items for rewards
- Worker System: Background task processing for scheduled events
- In Development: Duels (PVP challenges)
- Discord Bot: Full-featured Discord integration with slash commands
- Admin Dashboard: Web-based GUI for system monitoring and admin commands
- Health Checks: Production-ready liveness and readiness endpoints
- API Documentation: Interactive Swagger UI at
/swagger/
BrandishBot includes a native Discord bot with 21 slash commands providing complete feature access directly in Discord!
- Configure (add to
.env):
DISCORD_TOKEN=your_bot_token
DISCORD_APP_ID=your_app_id
API_URL=http://localhost:8080- Start Discord Bot:
# Local development
make build
make discord-run
# Docker (with core API)
make docker-up- Use Commands:
/info- Get started/profile- View your profile/search- Find items/inventory- See your items/helpfor more!
Economy: /buy, /sell, /prices, /give
Inventory: /inventory, /search, /use
Crafting: /upgrade, /disassemble, /recipes
Expeditions: /explore, /expedition-journal
Quests: /quests, /claimquest
Farming: /harvest
Jobs: /job-progress
Linking: /link, /unlink
Gambling: /gamble, /join-gamble
Stats: /stats, /leaderboard
Progression: /vote
Admin: /add-item, /remove-item
See /info commands in Discord for full details.
BrandishBot includes a web-based admin dashboard for system monitoring and administration.
Access: http://localhost:8080/admin/ (or your configured port)
- Health Monitoring: Real-time server status, metrics, and performance stats
- Admin Commands: GUI for progression management, job XP, cache control, and scenarios
- Live Events: Real-time SSE event stream with filtering
- User Management: Search users, view profiles, manage inventory and XP
- Build the dashboard:
make admin-build # Build React frontend
make build # Build Go binary with embedded dashboard- Run the server:
./bin/app
# Dashboard available at http://localhost:8080/admin/- Login: Use your
API_KEYfrom.env
📖 Full Documentation: See docs/features/ADMIN_DASHBOARD_USAGE.md for detailed usage, configuration, and extensibility guide.
- Go 1.24+
- PostgreSQL 15+
- Docker & Docker Compose (recommended)
- Clone and configure:
cp .env.example .env
# Edit .env with your database credentials- Start database:
make docker-up- Run migrations:
make migrate-up- Start the server:
make run
# Server will start on http://localhost:8080- View API documentation: Visit http://localhost:8080/swagger/index.html
The project uses a centralized cmd/devtool utility for development tasks. Most make commands delegate to this tool.
See Devtool Documentation for detailed usage.
Migrations:
make migrate-up- Run all pending migrationsmake migrate-down- Rollback last migrationmake migrate-status- Show migration statusmake migrate-create NAME=<name>- Create new migration
Development:
make test- Run tests with coveragemake unit- Run unit tests (fast)make test-coverage- Generate HTML coverage reportmake build- Build all binariesmake swagger- Regenerate Swagger docs
Discord Bot:
make discord-run- Run Discord bot locallymake discord-logs- View Discord logs (Docker)make docker-discord-build- Build Discord imagemake docker-discord-up- Start Discord servicemake docker-discord-restart- Restart Discord bot
Docker:
make docker-up- Start servicesmake docker-down- Stop servicesmake docker-logs- View logs
├── cmd/ # Entry points
│ ├── app/ # Main application
│ ├── discord/ # Discord bot entry point
│ ├── setup/ # Database setup
│ ├── reset/ # Database reset utility
│ └── debug/ # Debug tools
├── internal/ # Application code
│ ├── handler/ # HTTP handlers
│ ├── domain/ # Domain models
│ ├── repository/ # Database interfaces
│ ├── database/ # SQLC and Postgres implementation
│ ├── user/ # User service
│ ├── economy/ # Economy service
│ ├── crafting/ # Crafting service
│ ├── harvest/ # Harvest (Farming) service
│ ├── progression/ # Progression tree service
│ ├── gamble/ # Gambling & Lootbox service
│ ├── job/ # Job & XP service
│ ├── stats/ # Statistics service
│ ├── discord/ # Discord bot implementation
│ └── cooldown/ # Cooldown service
├── migrations/ # SQL migrations
│ └── archive/ # Pre-v1 development migrations
├── web/
│ └── admin/ # Admin Dashboard (React)
└── docs/ # Documentation & Swagger
GET /healthz- Liveness checkGET /readyz- Readiness check (DB connectivity)
POST /user/register- Register userGET /user/inventory- Get inventoryPOST /user/item/add- Add itemPOST /user/item/use- Use item
POST /user/item/upgrade- Upgrade itemPOST /user/item/disassemble- Disassemble itemGET /recipes- Get crafting recipes
POST /user/item/buy- Buy itemPOST /user/item/sell- Sell itemGET /prices- Get market prices
POST /stats/event- Record eventGET /stats/user- Get user statsGET /stats/leaderboard- Get leaderboard
See /swagger/ for complete API documentation with request/response examples.
For detailed guidance, see Test Guidance and Running Tests.
# Run all tests
make test
# Generate coverage report
make test-coverage
# Open coverage.html in browserBrandishBot uses an asynchronous event-driven architecture for decoupled, reliable service communication:
📚 Documentation:
- Event Catalog - All 22+ event types with schemas and examples
- Architecture - Event bus, ResilientPublisher, retry logic
- Developer Guide - How to publish and subscribe to events
Key Features:
- 🔄 Automatic retry with exponential backoff (2s → 4s → 8s → 16s → 32s)
- 📝 Dead-letter logging for permanently failed events
- 🚫 Fire-and-forget: Domain operations never fail due to event errors
- 📊 Used for stats, notifications, audit logging, and cross-service communication
See AGENTS.md for development guidelines and architecture details.
MIT License