syntaxbullet/aurorabot
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update documentation to reflect headless API-only web service
All checks were successful
Deploy to Production / test (push) Successful in 44s
Details

Browse Source 
- AGENTS.md: Update project description from web dashboard to REST API

- README.md: Replace Web Dashboard section with REST API, update tech stack

- docs/main.md: Refactor Web Dashboard section to REST API documentation

- web/README.md: Rewrite from React setup to API endpoint documentation

All React/UI references removed - web is now API-only
This commit is contained in:
syntaxbullet
2026-02-12 12:30:43 +01:00
parent 9c7f1e4418
commit 73ad889018
4 changed files with 71 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
AGENTS.md
View File

@@ -2,13 +2,13 @@
## Project Overview ## Project Overview
AuroraBot is a Discord bot with a web dashboard built using Bun, Discord.js, React, and PostgreSQL with Drizzle ORM. AuroraBot is a Discord bot with a REST API built using Bun, Discord.js, and PostgreSQL with Drizzle ORM.
## Build/Lint/Test Commands ## Build/Lint/Test Commands
```bash ```bash
# Development # Development
bun --watch bot/index.ts # Run bot + web dashboard with hot reload bun --watch bot/index.ts # Run bot + API server with hot reload
# Testing # Testing
bun test # Run all tests bun test # Run all tests
@@ -24,8 +24,8 @@ bun run db:push:local # Push schema changes (local)
bun run db:studio # Open Drizzle Studio bun run db:studio # Open Drizzle Studio
# Docker (recommended for local dev) # Docker (recommended for local dev)
docker compose up # Start bot, web, and database docker compose up # Start bot, API, and database
docker compose up app # Start just the app (bot + web) docker compose up app # Start just the app (bot + API)
docker compose up db # Start just the database docker compose up db # Start just the database
``` ```
@@ -44,10 +44,8 @@ shared/ # Shared between bot and web
├── lib/ # Utils, config, errors, types ├── lib/ # Utils, config, errors, types
└── modules/ # Domain services (economy, user, etc.) └── modules/ # Domain services (economy, user, etc.)
web/ # React dashboard web/ # API server
├── src/pages/ # React pages └── src/routes/ # API route handlers
├── src/components/ # UI components (ShadCN/Radix)
└── src/hooks/ # React hooks
``` ```
## Import Conventions ## Import Conventions
@@ -224,9 +222,9 @@ describe("serviceName", () => {
- **Runtime:** Bun 1.0+ - **Runtime:** Bun 1.0+
- **Bot:** Discord.js 14.x - **Bot:** Discord.js 14.x
- **Web:** React 19 + Bun HTTP Server - **Web:** Bun HTTP Server (REST API)
- **Database:** PostgreSQL 16+ with Drizzle ORM - **Database:** PostgreSQL 16+ with Drizzle ORM
- **UI:** Tailwind CSS v4 + ShadCN/Radix - **UI:** Discord embeds and components
- **Validation:** Zod - **Validation:** Zod
- **Testing:** Bun Test - **Testing:** Bun Test
- **Container:** Docker - **Container:** Docker

32
README.md
View File

@@ -7,11 +7,9 @@
![Discord.js](https://img.shields.io/badge/Discord.js-14.x-5865F2) ![Discord.js](https://img.shields.io/badge/Discord.js-14.x-5865F2)
![Drizzle ORM](https://img.shields.io/badge/Drizzle_ORM-0.30+-C5F74F) ![Drizzle ORM](https://img.shields.io/badge/Drizzle_ORM-0.30+-C5F74F)
![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-336791) ![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-336791)
![React](https://img.shields.io/badge/React-19-61DAFB)
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. 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.
**New in v1.0:** Aurora now includes a fully integrated **Web Dashboard** for managing the bot, viewing statistics, and configuring settings, running alongside the bot in a single process. **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.
## ✨ Features ## ✨ Features
@@ -25,26 +23,26 @@ Aurora is a powerful Discord bot designed to facilitate RPG-like elements within
* **Lootdrops**: Random loot drops in channels to engage users. * **Lootdrops**: Random loot drops in channels to engage users.
* **Admin Tools**: Administrative commands for server management. * **Admin Tools**: Administrative commands for server management.
### Web Dashboard ### REST API
* **Live Analytics**: View real-time activity charts (commands, transactions). * **Live Analytics**: Real-time statistics endpoint (commands, transactions).
* **Configuration Management**: Update bot settings without restarting. * **Configuration Management**: Update bot settings via API.
* **Database Inspection**: Integrated Drizzle Studio access. * **Database Inspection**: Integrated Drizzle Studio access.
* **State Monitoring**: View internal bot state (Lootdrops, etc.). * **WebSocket Support**: Real-time event streaming for live updates.
## 🏗️ Architecture ## 🏗️ Architecture
Aurora uses a **Single Process Monolith** architecture to maximize performance and simplify resource sharing. Aurora uses a **Single Process Monolith** architecture to maximize performance and simplify resource sharing.
* **Unified Runtime**: Both the Discord Client and the Web Dashboard run within the same Bun process. * **Unified Runtime**: Both the Discord Client and the REST API run within the same Bun process.
* **Shared State**: This allows the Dashboard to access live bot memory (caches, gateways) directly without complex inter-process communication (IPC). * **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. * **Simplified Deployment**: You only need to deploy a single Docker container.
## 🛠️ Tech Stack ## 🛠️ Tech Stack
* **Runtime**: [Bun](https://bun.sh/) * **Runtime**: [Bun](https://bun.sh/)
* **Bot Framework**: [Discord.js](https://discord.js.org/) * **Bot Framework**: [Discord.js](https://discord.js.org/)
* **Web Framework**: [React 19](https://react.dev/) + [Vite](https://vitejs.dev/) (served via Bun) * **API Framework**: Bun HTTP Server (REST API)
* **Styling**: [Tailwind CSS v4](https://tailwindcss.com/) + [Radix UI](https://www.radix-ui.com/) * **UI**: Discord embeds and components
* **Database**: [PostgreSQL](https://www.postgresql.org/) * **Database**: [PostgreSQL](https://www.postgresql.org/)
* **ORM**: [Drizzle ORM](https://orm.drizzle.team/) * **ORM**: [Drizzle ORM](https://orm.drizzle.team/)
* **Validation**: [Zod](https://zod.dev/) * **Validation**: [Zod](https://zod.dev/)
@@ -94,14 +92,14 @@ Aurora uses a **Single Process Monolith** architecture to maximize performance a
bun run db:push bun run db:push
``` ```
### Running the Bot & Dashboard ### Running the Bot & API
**Development Mode** (with hot reload): **Development Mode** (with hot reload):
```bash ```bash
bun run dev bun run dev
``` ```
* Bot: Online in Discord * Bot: Online in Discord
* Dashboard: http://localhost:3000 * API: http://localhost:3000
**Production Mode**: **Production Mode**:
Build and run with Docker (recommended): Build and run with Docker (recommended):
@@ -111,7 +109,7 @@ docker compose up -d app
### 🔐 Accessing Production Services (SSH Tunnel) ### 🔐 Accessing Production Services (SSH Tunnel)
For security, the Production Database and Dashboard are **not exposed** to the public internet by default. They are only accessible via localhost on the server. 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 access them from your local machine, use the included SSH tunnel script. To access them from your local machine, use the included SSH tunnel script.
@@ -127,12 +125,12 @@ To access them from your local machine, use the included SSH tunnel script.
``` ```
This will establish secure tunnels for: This will establish secure tunnels for:
* **Dashboard**: http://localhost:3000 * **API**: http://localhost:3000
* **Drizzle Studio**: http://localhost:4983 * **Drizzle Studio**: http://localhost:4983
## 📜 Scripts ## 📜 Scripts
* `bun run dev`: Start the bot and dashboard in watch mode. * `bun run dev`: Start the bot and API server in watch mode.
* `bun run remote`: Open SSH tunnel to production services. * `bun run remote`: Open SSH tunnel to production services.
* `bun run generate`: Generate Drizzle migrations. * `bun run generate`: Generate Drizzle migrations.
* `bun run migrate`: Apply migrations (via Docker). * `bun run migrate`: Apply migrations (via Docker).
@@ -143,7 +141,7 @@ This will establish secure tunnels for:
``` ```
├── bot # Discord Bot logic & entry point ├── bot # Discord Bot logic & entry point
├── web # React Web Dashboard (Frontend + Server) ├── web # REST API Server
├── shared # Shared code (Database, Config, Types) ├── shared # Shared code (Database, Config, Types)
├── drizzle # Drizzle migration files ├── drizzle # Drizzle migration files
├── scripts # Utility scripts ├── scripts # Utility scripts

52
docs/main.md
View File

@@ -4,7 +4,7 @@ A comprehensive, feature-rich Discord RPG bot built with modern technologies usi
## Architecture Overview ## Architecture Overview
Aurora uses a **Single Process Monolith** architecture that runs both the Discord bot and web dashboard in the same Bun process. This design maximizes performance by eliminating inter-process communication overhead and simplifies deployment to a single Docker container. Aurora uses a **Single Process Monolith** architecture that runs both the Discord bot and REST API in the same Bun process. This design maximizes performance by eliminating inter-process communication overhead and simplifies deployment to a single Docker container.
## Monorepo Structure ## Monorepo Structure
@@ -15,12 +15,8 @@ aurora-bot-discord/
│ ├── events/ # Discord event handlers │ ├── events/ # Discord event handlers
│ ├── lib/ # Bot core logic (BotClient, utilities) │ ├── lib/ # Bot core logic (BotClient, utilities)
│ └── index.ts # Bot entry point │ └── index.ts # Bot entry point
├── web/ # React web dashboard ├── web/ # REST API server
│ ├── src/ # React components and pages │ └── src/routes/ # API route handlers
│ │ ├── pages/ # Dashboard pages (Admin, Settings, Home)
│ │ ├── components/ # Reusable UI components
│ │ └── server.ts # Web server with API endpoints
│ └── build.ts # Vite build configuration
├── shared/ # Shared code between bot and web ├── shared/ # Shared code between bot and web
│ ├── db/ # Database schema and Drizzle ORM │ ├── db/ # Database schema and Drizzle ORM
│ ├── lib/ # Utilities, config, logger, events │ ├── lib/ # Utilities, config, logger, events
@@ -52,28 +48,26 @@ The bot is built with Discord.js v14 and handles all Discord-related functionali
- `ready.ts`: Bot ready events - `ready.ts`: Bot ready events
- `guildMemberAdd.ts`: New member handling - `guildMemberAdd.ts`: New member handling
### 2. Web Dashboard (`web/`) ### 2. REST API (`web/`)
A React 19 + Bun web application for bot administration and monitoring. A headless REST API built with Bun's native HTTP server for bot administration and data access.
**Key Pages:** **Key Endpoints:**
- **Home** (`/`): Dashboard overview with live statistics - **Stats** (`/api/stats`): Real-time bot metrics and statistics
- **Admin Overview** (`/admin/overview`): Real-time bot metrics - **Settings** (`/api/settings`): Configuration management endpoints
- **Admin Quests** (`/admin/quests`): Quest management interface - **Users** (`/api/users`): User data and profiles
- **Settings** (`/settings/*`): Configuration pages for: - **Items** (`/api/items`): Item catalog and management
- General settings - **Quests** (`/api/quests`): Quest data and progress
- Economy settings - **Economy** (`/api/transactions`): Economy and transaction data
- Systems settings
- Roles settings
**Web Server Features:** **API Features:**
- Built with Bun's native HTTP server - Built with Bun's native HTTP server
- WebSocket support for real-time updates - WebSocket support for real-time updates (`/ws`)
- REST API endpoints for dashboard data - REST API endpoints for all bot data
- SPA fallback for client-side routing - Real-time event streaming via WebSocket
- Bun dev server with hot module replacement - Zod validation for all requests
### 3. Shared Core (`shared/`) ### 3. Shared Core (`shared/`)
@@ -123,15 +117,15 @@ Shared code accessible by both bot and web applications.
### For Server Administrators ### For Server Administrators
1. **Bot Configuration**: Adjust economy rates, enable/disable features via dashboard 1. **Bot Configuration**: Adjust economy rates, enable/disable features via API
2. **Moderation Tools**: 2. **Moderation Tools**:
- Warn, note, and track moderation cases - Warn, note, and track moderation cases
- Mass prune inactive members - Mass prune inactive members
- Role management - Role management
3. **Quest Management**: Create and manage server-specific quests 3. **Quest Management**: Create and manage server-specific quests
4. **Monitoring**: 4. **Monitoring**:
- Real-time dashboard with live statistics - Real-time statistics via REST API
- Activity charts and event logs - Activity data and event logs
- Economy leaderboards - Economy leaderboards
### For Developers ### For Developers
@@ -148,10 +142,10 @@ Shared code accessible by both bot and web applications.
| ---------------- | --------------------------------- | | ---------------- | --------------------------------- |
| Runtime | Bun 1.0+ | | Runtime | Bun 1.0+ |
| Bot Framework | Discord.js 14.x | | Bot Framework | Discord.js 14.x |
| Web Framework | React 19 + Bun | | Web Framework | Bun HTTP Server (REST API) |
| Database | PostgreSQL 17 | | Database | PostgreSQL 17 |
| ORM | Drizzle ORM | | ORM | Drizzle ORM |
| Styling | Tailwind CSS v4 + ShadCN/Radix UI | | UI | Discord embeds and components |
| Validation | Zod | | Validation | Zod |
| Containerization | Docker | | Containerization | Docker |
@@ -165,4 +159,4 @@ bun run migrate
docker compose up docker compose up
``` ```
The bot and dashboard process run on port 3000 and are accessible at `http://localhost:3000`. The bot and API server run on port 3000 and are accessible at `http://localhost:3000`.

41
web/README.md
View File

@@ -1,21 +1,30 @@
# Aurora Web # Aurora Web API
To install dependencies: The web API provides a REST interface and WebSocket support for accessing Aurora bot data and configuration.
## API Endpoints
- `GET /api/stats` - Real-time bot statistics
- `GET /api/settings` - Bot configuration
- `GET /api/users` - User data
- `GET /api/items` - Item catalog
- `GET /api/quests` - Quest information
- `GET /api/transactions` - Economy data
- `GET /api/health` - Health check
## WebSocket
Connect to `/ws` for real-time updates:
- Stats broadcasts every 5 seconds
- Event notifications via system bus
- PING/PONG heartbeat support
## Development
The API runs automatically when you start the bot:
```bash ```bash
bun install bun run dev
``` ```
To start a development server: The API will be available at `http://localhost:3000`
```bash
bun dev
```
To run for production:
```bash
bun start
```
This project was created using `bun init` in bun v1.3.3. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.