6abbd4652a
Some checks failed
Deploy to Production / test (push) Failing after 33s
- Rewrite AGENTS and README files to match the current app layout - Document API routes, trivia UI, and the active panel design language
181 lines
3.8 KiB
Markdown
181 lines
3.8 KiB
Markdown
# 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
|