Aurora

Aurora is a Discord RPG bot, admin/player panel, and REST/WebSocket API that run as one Bun application. The Discord bot and HTTP server share the same database client, config, services, and domain events.

What exists today

• Discord slash commands for economy, inventory, quests, moderation, feedback, user profiles, and admin tooling.
• A Bun HTTP API under /api/*, Discord OAuth under /auth/*, and a WebSocket endpoint at /ws.
• A React panel for both admins and enrolled players.
• Shared domain services in shared/modules/* and reusable game plugins in shared/games/*.
• Built-in real-time games: chess and blackjack.

Architecture

bot/                 Discord bot entrypoint, commands, events, Discord-facing views/interactions
api/                 Bun HTTP server, route modules, WebSocket/game room server
panel/               React 19 + Vite + Tailwind v4 dashboard
shared/              Shared DB schema, services, config, events, utilities, game plugins
docs/                Product and design notes

Important points:

• bot/index.ts initializes DB-backed config, wires domain events, starts the API server, then logs into Discord.
• The API server also serves built panel assets from panel/dist when they exist.
• Bot commands, API routes, and the panel all rely on the same service layer in shared/modules/*.
• Runtime game config is loaded from the game_settings table into shared/lib/config.ts.

Getting started

Prerequisites

• Bun
• Docker and Docker Compose
• A Discord application with bot token, client ID, and client secret

Setup

1. Install dependencies.

bun install

2. Create your environment file.

cp .env.example .env

3. Start PostgreSQL.

docker compose up -d db

4. Initialize the schema.

bun run db:push:local

If you prefer running schema changes through Docker:

bun run migrate

5. Start the bot and API.

bun run dev

The Bun server listens on http://localhost:3000.

Panel development

The Bun server can serve a built panel, but day-to-day panel work is done with Vite:

bun run panel:dev

The panel dev server runs on http://localhost:5173 and proxies /api, /auth, /assets, and /ws to http://localhost:3000.

To build the panel for the integrated Bun server:

bun run panel:build

Useful scripts

# App
bun run dev
docker compose up
docker compose up app
docker compose up db

# Database
bun run db:push
bun run db:push:local
bun run db:generate
bun run db:migrate
bun run db:studio
bun run db:backup
bun run db:restore

# Panel
bun run panel:dev
bun run panel:build

# Tests
bun test
bun run test
bun run test:ci

# Ops
bun run remote
bun run deploy
bun run deploy:remote

Environment notes

The main variables you need in .env are:

• DISCORD_BOT_TOKEN
• DISCORD_CLIENT_ID
• DISCORD_CLIENT_SECRET
• DISCORD_GUILD_ID
• ADMIN_USER_IDS
• SESSION_SECRET
• DB_USER
• DB_PASSWORD
• DB_NAME
• DATABASE_URL
• PANEL_BASE_URL

Players can authenticate into the panel only after they exist in the users table. Admin access is determined by ADMIN_USER_IDS, and panel sessions are stored in signed cookies keyed by SESSION_SECRET.

API and panel summary

• Public routes: /auth/*, /api/health
• Player-accessible API routes: /api/stats, /api/health, /api/me, /api/me/inventory
• Admin-only API routes: the rest of /api/*
• WebSocket: /ws with cookie-based auth
• Static assets: /assets/*

Project structure

bot/
  commands/
  events/
  lib/
  modules/

api/
  src/
    routes/
    games/

panel/
  src/

shared/
  db/
  games/
  lib/
  modules/

Documentation

• AGENTS.md: repo-wide implementation guidance
• api/README.md: API surface and auth model
• docs/new-design/DESIGN.md: current panel design language