# 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

```text
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.

```bash
bun install
```

2. Create your environment file.

```bash
cp .env.example .env
```

3. Start PostgreSQL.

```bash
docker compose up -d db
```

4. Initialize the schema.

```bash
bun run db:push:local
```

If you prefer running schema changes through Docker:

```bash
bun run migrate
```

5. Start the bot and API.

```bash
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:

```bash
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:

```bash
bun run panel:build
```

## Useful scripts

```bash
# 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`
- `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`.

## 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

```text
bot/
  commands/
  events/
  lib/
  modules/

api/
  src/
    routes/
    games/

panel/
  src/

shared/
  db/
  games/
  lib/
  modules/
```

## Documentation

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