From 73ad889018ba568af04dc3f0194522673e7a9644 Mon Sep 17 00:00:00 2001 From: syntaxbullet Date: Thu, 12 Feb 2026 12:30:43 +0100 Subject: [PATCH] docs: update documentation to reflect headless API-only web service - 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 --- AGENTS.md | 18 ++++++++---------- README.md | 32 +++++++++++++++---------------- docs/main.md | 52 +++++++++++++++++++++++---------------------------- web/README.md | 41 ++++++++++++++++++++++++---------------- 4 files changed, 71 insertions(+), 72 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 04a22e6..9b81057 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,13 +2,13 @@ ## 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 ```bash # 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 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 # Docker (recommended for local dev) -docker compose up # Start bot, web, and database -docker compose up app # Start just the app (bot + web) +docker compose up # Start bot, API, and database +docker compose up app # Start just the app (bot + API) docker compose up db # Start just the database ``` @@ -44,10 +44,8 @@ shared/ # Shared between bot and web ├── lib/ # Utils, config, errors, types └── modules/ # Domain services (economy, user, etc.) -web/ # React dashboard -├── src/pages/ # React pages -├── src/components/ # UI components (ShadCN/Radix) -└── src/hooks/ # React hooks +web/ # API server +└── src/routes/ # API route handlers ``` ## Import Conventions @@ -224,9 +222,9 @@ describe("serviceName", () => { - **Runtime:** Bun 1.0+ - **Bot:** Discord.js 14.x -- **Web:** React 19 + Bun HTTP Server +- **Web:** Bun HTTP Server (REST API) - **Database:** PostgreSQL 16+ with Drizzle ORM -- **UI:** Tailwind CSS v4 + ShadCN/Radix +- **UI:** Discord embeds and components - **Validation:** Zod - **Testing:** Bun Test - **Container:** Docker diff --git a/README.md b/README.md index 01671a9..99ce2bc 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,9 @@ ![Discord.js](https://img.shields.io/badge/Discord.js-14.x-5865F2) ![Drizzle ORM](https://img.shields.io/badge/Drizzle_ORM-0.30+-C5F74F) ![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. -**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 @@ -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. * **Admin Tools**: Administrative commands for server management. -### Web Dashboard -* **Live Analytics**: View real-time activity charts (commands, transactions). -* **Configuration Management**: Update bot settings without restarting. +### REST API +* **Live Analytics**: Real-time statistics endpoint (commands, transactions). +* **Configuration Management**: Update bot settings via API. * **Database Inspection**: Integrated Drizzle Studio access. -* **State Monitoring**: View internal bot state (Lootdrops, etc.). +* **WebSocket Support**: Real-time event streaming for live updates. ## 🏗️ Architecture 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. -* **Shared State**: This allows the Dashboard to access live bot memory (caches, gateways) directly without complex inter-process communication (IPC). +* **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/) -* **Web Framework**: [React 19](https://react.dev/) + [Vite](https://vitejs.dev/) (served via Bun) -* **Styling**: [Tailwind CSS v4](https://tailwindcss.com/) + [Radix UI](https://www.radix-ui.com/) +* **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/) @@ -94,14 +92,14 @@ Aurora uses a **Single Process Monolith** architecture to maximize performance a bun run db:push ``` -### Running the Bot & Dashboard +### Running the Bot & API **Development Mode** (with hot reload): ```bash bun run dev ``` * Bot: Online in Discord -* Dashboard: http://localhost:3000 +* API: http://localhost:3000 **Production Mode**: Build and run with Docker (recommended): @@ -111,7 +109,7 @@ docker compose up -d app ### 🔐 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. @@ -127,12 +125,12 @@ To access them from your local machine, use the included SSH tunnel script. ``` This will establish secure tunnels for: -* **Dashboard**: http://localhost:3000 +* **API**: http://localhost:3000 * **Drizzle Studio**: http://localhost:4983 ## 📜 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 generate`: Generate Drizzle migrations. * `bun run migrate`: Apply migrations (via Docker). @@ -143,7 +141,7 @@ This will establish secure tunnels for: ``` ├── bot # Discord Bot logic & entry point -├── web # React Web Dashboard (Frontend + Server) +├── web # REST API Server ├── shared # Shared code (Database, Config, Types) ├── drizzle # Drizzle migration files ├── scripts # Utility scripts diff --git a/docs/main.md b/docs/main.md index d702d54..6129e43 100644 --- a/docs/main.md +++ b/docs/main.md @@ -4,7 +4,7 @@ A comprehensive, feature-rich Discord RPG bot built with modern technologies usi ## 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 @@ -15,12 +15,8 @@ aurora-bot-discord/ │ ├── events/ # Discord event handlers │ ├── lib/ # Bot core logic (BotClient, utilities) │ └── index.ts # Bot entry point -├── web/ # React web dashboard -│ ├── src/ # React components and pages -│ │ ├── pages/ # Dashboard pages (Admin, Settings, Home) -│ │ ├── components/ # Reusable UI components -│ │ └── server.ts # Web server with API endpoints -│ └── build.ts # Vite build configuration +├── web/ # REST API server +│ └── src/routes/ # API route handlers ├── shared/ # Shared code between bot and web │ ├── db/ # Database schema and Drizzle ORM │ ├── 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 - `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 -- **Admin Overview** (`/admin/overview`): Real-time bot metrics -- **Admin Quests** (`/admin/quests`): Quest management interface -- **Settings** (`/settings/*`): Configuration pages for: - - General settings - - Economy settings - - Systems settings - - Roles settings +- **Stats** (`/api/stats`): Real-time bot metrics and statistics +- **Settings** (`/api/settings`): Configuration management endpoints +- **Users** (`/api/users`): User data and profiles +- **Items** (`/api/items`): Item catalog and management +- **Quests** (`/api/quests`): Quest data and progress +- **Economy** (`/api/transactions`): Economy and transaction data -**Web Server Features:** +**API Features:** - Built with Bun's native HTTP server -- WebSocket support for real-time updates -- REST API endpoints for dashboard data -- SPA fallback for client-side routing -- Bun dev server with hot module replacement +- WebSocket support for real-time updates (`/ws`) +- REST API endpoints for all bot data +- Real-time event streaming via WebSocket +- Zod validation for all requests ### 3. Shared Core (`shared/`) @@ -123,15 +117,15 @@ Shared code accessible by both bot and web applications. ### 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**: - Warn, note, and track moderation cases - Mass prune inactive members - Role management 3. **Quest Management**: Create and manage server-specific quests 4. **Monitoring**: - - Real-time dashboard with live statistics - - Activity charts and event logs + - Real-time statistics via REST API + - Activity data and event logs - Economy leaderboards ### For Developers @@ -148,10 +142,10 @@ Shared code accessible by both bot and web applications. | ---------------- | --------------------------------- | | Runtime | Bun 1.0+ | | Bot Framework | Discord.js 14.x | -| Web Framework | React 19 + Bun | +| Web Framework | Bun HTTP Server (REST API) | | Database | PostgreSQL 17 | | ORM | Drizzle ORM | -| Styling | Tailwind CSS v4 + ShadCN/Radix UI | +| UI | Discord embeds and components | | Validation | Zod | | Containerization | Docker | @@ -165,4 +159,4 @@ bun run migrate 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`. diff --git a/web/README.md b/web/README.md index fe6ce5e..5d55815 100644 --- a/web/README.md +++ b/web/README.md @@ -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 -bun install +bun run dev ``` -To start a development server: - -```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. +The API will be available at `http://localhost:3000`