Refresh repository documentation
Some checks failed
Deploy to Production / test (push) Failing after 33s
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
This commit is contained in:
syntaxbullet
269
README.md
269
README.md
@@ -1,159 +1,180 @@
|
||||
# Aurora
|
||||
|
||||
> A comprehensive, feature-rich Discord RPG bot built with modern technologies.
|
||||
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
|
||||
|
||||
Aurora is a powerful Discord bot designed to facilitate RPG-like elements within a Discord server. It features a robust economy, class system, inventory management, quests, and more, all built on top of a high-performance stack using Bun and Drizzle ORM.
|
||||
- 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.
|
||||
|
||||
**New in v1.0:** Aurora now includes a fully integrated **REST API** for accessing bot data, statistics, and configuration, running alongside the bot in a single process.
|
||||
## Architecture
|
||||
|
||||
## ✨ Features
|
||||
```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
|
||||
```
|
||||
|
||||
### Discord Bot
|
||||
* **Class System**: Users can join different classes.
|
||||
* **Economy**: Complete economy system with balance, transactions, and daily rewards.
|
||||
* **Inventory & Items**: Sophisticated item system with rarities, types (Material, Consumable, etc.), and inventory management.
|
||||
* **Leveling**: XP-based leveling system to track user activity and progress.
|
||||
* **Quests**: Quest system with requirements and rewards.
|
||||
* **Trading**: Secure trading system between users.
|
||||
* **Lootdrops**: Random loot drops in channels to engage users.
|
||||
* **Admin Tools**: Administrative commands for server management.
|
||||
Important points:
|
||||
|
||||
### REST API
|
||||
* **Live Analytics**: Real-time statistics endpoint (commands, transactions).
|
||||
* **Configuration Management**: Update bot settings via API.
|
||||
* **Database Inspection**: Integrated Drizzle Studio access.
|
||||
* **WebSocket Support**: Real-time event streaming for live updates.
|
||||
- `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`.
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
Aurora uses a **Single Process Monolith** architecture to maximize performance and simplify resource sharing.
|
||||
|
||||
* **Unified Runtime**: Both the Discord Client and the REST API run within the same Bun process.
|
||||
* **Shared State**: This allows the API to access live bot memory (caches, gateways) directly without complex inter-process communication (IPC).
|
||||
* **Simplified Deployment**: You only need to deploy a single Docker container.
|
||||
|
||||
## 🛠️ Tech Stack
|
||||
|
||||
* **Runtime**: [Bun](https://bun.sh/)
|
||||
* **Bot Framework**: [Discord.js](https://discord.js.org/)
|
||||
* **API Framework**: Bun HTTP Server (REST API)
|
||||
* **UI**: Discord embeds and components
|
||||
* **Database**: [PostgreSQL](https://www.postgresql.org/)
|
||||
* **ORM**: [Drizzle ORM](https://orm.drizzle.team/)
|
||||
* **Validation**: [Zod](https://zod.dev/)
|
||||
* **Containerization**: [Docker](https://www.docker.com/)
|
||||
|
||||
## 🚀 Getting Started
|
||||
## Getting started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
* [Bun](https://bun.sh/) (latest version)
|
||||
* [Docker](https://www.docker.com/) & Docker Compose
|
||||
- Bun
|
||||
- Docker and Docker Compose
|
||||
- A Discord application with bot token, client ID, and client secret
|
||||
|
||||
### Installation
|
||||
### Setup
|
||||
|
||||
1. **Clone the repository**
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd aurora
|
||||
```
|
||||
1. Install dependencies.
|
||||
|
||||
2. **Install dependencies**
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
3. **Environment Setup**
|
||||
Copy the example environment file and configure it:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
Edit `.env` with your Discord bot token, Client ID, and database credentials.
|
||||
2. Create your environment file.
|
||||
|
||||
> **Note**: The `DATABASE_URL` in `.env.example` is pre-configured for Docker.
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
4. **Start the Database**
|
||||
Run the database service using Docker Compose:
|
||||
```bash
|
||||
docker compose up -d db
|
||||
```
|
||||
3. Start PostgreSQL.
|
||||
|
||||
5. **Run Migrations**
|
||||
```bash
|
||||
bun run migrate
|
||||
```
|
||||
OR
|
||||
```bash
|
||||
bun run db:push
|
||||
```
|
||||
```bash
|
||||
docker compose up -d db
|
||||
```
|
||||
|
||||
### Running the Bot & API
|
||||
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.
|
||||
|
||||
**Development Mode** (with hot reload):
|
||||
```bash
|
||||
bun run dev
|
||||
```
|
||||
* Bot: Online in Discord
|
||||
* API: http://localhost:3000
|
||||
|
||||
**Production Mode**:
|
||||
Build and run with Docker (recommended):
|
||||
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
|
||||
docker compose up -d app
|
||||
bun run panel:dev
|
||||
```
|
||||
|
||||
### 🔐 Accessing Production Services (SSH Tunnel)
|
||||
The panel dev server runs on `http://localhost:5173` and proxies `/api`, `/auth`, `/assets`, and `/ws` to `http://localhost:3000`.
|
||||
|
||||
For security, the Production Database and API are **not exposed** to the public internet by default. They are only accessible via localhost on the server.
|
||||
To build the panel for the integrated Bun server:
|
||||
|
||||
To access them from your local machine, use the included SSH tunnel script.
|
||||
|
||||
1. Add your VPS details to your local `.env` file:
|
||||
```env
|
||||
VPS_USER=root
|
||||
VPS_HOST=123.45.67.89
|
||||
```
|
||||
|
||||
2. Run the remote connection script:
|
||||
```bash
|
||||
bun run remote
|
||||
```
|
||||
|
||||
This will establish secure tunnels for:
|
||||
* **API**: http://localhost:3000
|
||||
* **Drizzle Studio**: http://localhost:4983
|
||||
|
||||
## 📜 Scripts
|
||||
|
||||
* `bun run dev`: Start the bot and API server in watch mode.
|
||||
* `bun run remote`: Open SSH tunnel to production services.
|
||||
* `bun run generate`: Generate Drizzle migrations.
|
||||
* `bun run migrate`: Apply migrations (via Docker).
|
||||
* `bun run db:studio`: Open Drizzle Studio to inspect the database.
|
||||
* `bun test`: Run tests.
|
||||
|
||||
## 📂 Project Structure
|
||||
|
||||
```
|
||||
├── bot # Discord Bot logic & entry point
|
||||
├── web # REST API Server
|
||||
├── shared # Shared code (Database, Config, Types)
|
||||
├── drizzle # Drizzle migration files
|
||||
├── scripts # Utility scripts
|
||||
├── docker-compose.yml
|
||||
└── package.json
|
||||
```bash
|
||||
bun run panel:build
|
||||
```
|
||||
|
||||
## 🤝 Contributing
|
||||
## Useful scripts
|
||||
|
||||
Contributions are welcome! Please feel free to submit a Pull Request.
|
||||
```bash
|
||||
# App
|
||||
bun run dev
|
||||
docker compose up
|
||||
docker compose up app
|
||||
docker compose up db
|
||||
|
||||
## 📄 License
|
||||
# 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
|
||||
|
||||
This project is licensed under the MIT License.
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user