354 lines
8.6 KiB
Markdown
354 lines
8.6 KiB
Markdown
# Astro Bot Web Dashboard Architecture
|
|
|
|
## Overview
|
|
A real-time web dashboard for controlling the Discord music bot from a browser. Users can manage queues, adjust settings, and control playback without Discord.
|
|
|
|
## Tech Stack
|
|
|
|
### Backend (Flask/FastAPI)
|
|
**Recommended: FastAPI** (modern, async, WebSocket support built-in)
|
|
|
|
```python
|
|
# Dependencies
|
|
fastapi==0.104.1
|
|
uvicorn[standard]==0.24.0
|
|
websockets==12.0
|
|
python-socketio==5.10.0 # For real-time updates
|
|
aioredis==2.0.1 # For session management
|
|
```
|
|
|
|
**Why FastAPI:**
|
|
- Native async support (works well with discord.py)
|
|
- Built-in WebSocket support
|
|
- Auto-generated API docs
|
|
- Fast performance
|
|
|
|
### Frontend
|
|
**Recommended: React + Tailwind CSS**
|
|
|
|
```
|
|
React 18
|
|
Tailwind CSS
|
|
Socket.IO client (for real-time)
|
|
Axios (for API calls)
|
|
```
|
|
|
|
**Alternative (simpler):** Vanilla JS + Tailwind if you want less complexity
|
|
|
|
---
|
|
|
|
## Architecture Diagram
|
|
|
|
```
|
|
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
|
|
│ Browser │◄───────►│ FastAPI │◄───────►│ Discord Bot │
|
|
│ (React UI) │ HTTP/WS │ Backend │ IPC │ (Python) │
|
|
└─────────────┘ └──────────────┘ └─────────────┘
|
|
│
|
|
▼
|
|
┌──────────────┐
|
|
│ Database │
|
|
│ (SQLite) │
|
|
└──────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Communication Flow
|
|
|
|
### 1. Bot → Web (Status Updates)
|
|
Discord bot sends real-time updates to web backend via:
|
|
- **Shared Database** (simplest) - Bot writes to DB, web reads
|
|
- **Redis Pub/Sub** (better) - Bot publishes events, web subscribes
|
|
- **WebSocket/Socket.IO** (best) - Direct real-time connection
|
|
|
|
### 2. Web → Bot (Commands)
|
|
Web backend sends commands to bot via:
|
|
- **Database flags** (simplest) - Web writes commands, bot polls
|
|
- **Redis Queue** (better) - Web publishes, bot consumes
|
|
- **Direct IPC** (best) - Web calls bot functions directly
|
|
|
|
---
|
|
|
|
## Detailed Implementation
|
|
|
|
### Phase 1: Database-Based (Easiest Start)
|
|
|
|
**How it works:**
|
|
1. Bot writes current state to database
|
|
2. Web reads database and displays
|
|
3. Web writes commands to "commands" table
|
|
4. Bot polls table every second
|
|
|
|
**Pros:**
|
|
- Simple to implement
|
|
- No new dependencies
|
|
- Works immediately
|
|
|
|
**Cons:**
|
|
- Not truly real-time (polling delay)
|
|
- Database writes on every update
|
|
|
|
### Phase 2: Redis-Based (Production Ready)
|
|
|
|
**How it works:**
|
|
1. Bot publishes events to Redis: `PUBLISH bot:status {"song": "...", "queue": [...]}`
|
|
2. Web subscribes to Redis channel
|
|
3. Web publishes commands: `PUBLISH bot:commands {"action": "skip"}`
|
|
4. Bot subscribes and executes
|
|
|
|
**Pros:**
|
|
- True real-time
|
|
- Fast and efficient
|
|
- Decoupled architecture
|
|
|
|
**Cons:**
|
|
- Requires Redis server
|
|
- More complex setup
|
|
|
|
---
|
|
|
|
## API Endpoints
|
|
|
|
### GET Endpoints (Read)
|
|
```
|
|
GET /api/servers # List all servers bot is in
|
|
GET /api/servers/{id}/queue # Get current queue
|
|
GET /api/servers/{id}/status # Get playback status
|
|
GET /api/servers/{id}/settings # Get volume/loop/effect
|
|
```
|
|
|
|
### POST Endpoints (Write)
|
|
```
|
|
POST /api/servers/{id}/play # Add song to queue
|
|
POST /api/servers/{id}/skip # Skip current song
|
|
POST /api/servers/{id}/volume # Set volume
|
|
POST /api/servers/{id}/loop # Set loop mode
|
|
POST /api/servers/{id}/effect # Set audio effect
|
|
POST /api/servers/{id}/shuffle # Shuffle queue
|
|
POST /api/servers/{id}/clear # Clear queue
|
|
```
|
|
|
|
### WebSocket Events
|
|
```
|
|
ws://localhost:8000/ws/{server_id}
|
|
|
|
# Bot → Web
|
|
{"event": "song_changed", "data": {...}}
|
|
{"event": "queue_updated", "data": [...]}
|
|
{"event": "volume_changed", "data": 150}
|
|
|
|
# Web → Bot
|
|
{"action": "skip"}
|
|
{"action": "volume", "value": 120}
|
|
```
|
|
|
|
---
|
|
|
|
## Example Code Structure
|
|
|
|
### Backend (FastAPI)
|
|
|
|
```python
|
|
# main.py
|
|
from fastapi import FastAPI, WebSocket
|
|
from fastapi.middleware.cors import CORSMiddleware
|
|
import asyncio
|
|
import sqlite3
|
|
|
|
app = FastAPI()
|
|
|
|
# Allow frontend to connect
|
|
app.add_middleware(
|
|
CORSMiddleware,
|
|
allow_origins=["*"],
|
|
allow_methods=["*"],
|
|
allow_headers=["*"],
|
|
)
|
|
|
|
# WebSocket connection for real-time updates
|
|
@app.websocket("/ws/{server_id}")
|
|
async def websocket_endpoint(websocket: WebSocket, server_id: str):
|
|
await websocket.accept()
|
|
|
|
# Send updates every second
|
|
while True:
|
|
# Read from database
|
|
queue_data = get_queue_from_db(server_id)
|
|
await websocket.send_json(queue_data)
|
|
await asyncio.sleep(1)
|
|
|
|
# API endpoint to skip song
|
|
@app.post("/api/servers/{server_id}/skip")
|
|
async def skip_song(server_id: str):
|
|
# Write command to database
|
|
conn = sqlite3.connect("./data/music.db")
|
|
cursor = conn.cursor()
|
|
cursor.execute("INSERT INTO commands (server_id, action) VALUES (?, ?)",
|
|
(server_id, "skip"))
|
|
conn.commit()
|
|
conn.close()
|
|
return {"status": "ok"}
|
|
```
|
|
|
|
### Bot Integration
|
|
|
|
```python
|
|
# In your bot code, add command polling
|
|
@tasks.loop(seconds=1)
|
|
async def process_web_commands():
|
|
"""Check for commands from web dashboard"""
|
|
conn = sqlite3.connect("./data/music.db")
|
|
cursor = conn.cursor()
|
|
|
|
cursor.execute("SELECT * FROM commands WHERE processed = 0")
|
|
commands = cursor.fetchall()
|
|
|
|
for cmd in commands:
|
|
server_id, action, data = cmd[1], cmd[2], cmd[3]
|
|
|
|
# Execute command
|
|
if action == "skip":
|
|
guild = bot.get_guild(int(server_id))
|
|
if guild and guild.voice_client:
|
|
guild.voice_client.stop()
|
|
|
|
# Mark as processed
|
|
cursor.execute("UPDATE commands SET processed = 1 WHERE id = ?", (cmd[0],))
|
|
|
|
conn.commit()
|
|
conn.close()
|
|
```
|
|
|
|
### Frontend (React)
|
|
|
|
```javascript
|
|
// Dashboard.jsx
|
|
import { useEffect, useState } from 'react';
|
|
|
|
function Dashboard({ serverId }) {
|
|
const [queue, setQueue] = useState([]);
|
|
const [ws, setWs] = useState(null);
|
|
|
|
useEffect(() => {
|
|
// Connect to WebSocket
|
|
const websocket = new WebSocket(`ws://localhost:8000/ws/${serverId}`);
|
|
|
|
websocket.onmessage = (event) => {
|
|
const data = JSON.parse(event.data);
|
|
setQueue(data.queue);
|
|
};
|
|
|
|
setWs(websocket);
|
|
|
|
return () => websocket.close();
|
|
}, [serverId]);
|
|
|
|
const skipSong = async () => {
|
|
await fetch(`http://localhost:8000/api/servers/${serverId}/skip`, {
|
|
method: 'POST',
|
|
});
|
|
};
|
|
|
|
return (
|
|
<div>
|
|
<h1>Now Playing: {queue[0]?.title}</h1>
|
|
<button onClick={skipSong}>Skip</button>
|
|
|
|
<ul>
|
|
{queue.map((song, i) => (
|
|
<li key={i}>{song.title}</li>
|
|
))}
|
|
</ul>
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Authentication (Important!)
|
|
|
|
**Problem:** Anyone with the URL can control your bot.
|
|
|
|
**Solutions:**
|
|
|
|
1. **Discord OAuth2** (Recommended)
|
|
- Users log in with Discord
|
|
- Check if user is in the server
|
|
- Only show servers they're members of
|
|
|
|
2. **API Keys**
|
|
- Generate unique key per server
|
|
- Server admins share key with trusted users
|
|
|
|
3. **IP Whitelist**
|
|
- Only allow specific IPs to access
|
|
|
|
---
|
|
|
|
## Deployment
|
|
|
|
### Development
|
|
```bash
|
|
# Backend
|
|
cd backend
|
|
uvicorn main:app --reload --port 8000
|
|
|
|
# Frontend
|
|
cd frontend
|
|
npm run dev
|
|
```
|
|
|
|
### Production
|
|
```bash
|
|
# Backend (systemd service)
|
|
uvicorn main:app --host 0.0.0.0 --port 8000
|
|
|
|
# Frontend (build static files)
|
|
npm run build
|
|
# Serve with nginx or deploy to Vercel/Netlify
|
|
```
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
```
|
|
astro-bot/
|
|
├── bot.py # Discord bot
|
|
├── cogs/
|
|
│ └── music/
|
|
│ ├── main.py
|
|
│ ├── queue.py
|
|
│ └── util.py
|
|
├── web/
|
|
│ ├── backend/
|
|
│ │ ├── main.py # FastAPI app
|
|
│ │ ├── routes/
|
|
│ │ │ ├── servers.py
|
|
│ │ │ └── playback.py
|
|
│ │ └── websockets.py
|
|
│ └── frontend/
|
|
│ ├── src/
|
|
│ │ ├── components/
|
|
│ │ │ ├── Queue.jsx
|
|
│ │ │ ├── Controls.jsx
|
|
│ │ │ └── NowPlaying.jsx
|
|
│ │ ├── App.jsx
|
|
│ │ └── main.jsx
|
|
│ └── package.json
|
|
└── data/
|
|
└── music.db
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. **Start with database-based approach** - Get it working first
|
|
2. **Add WebSocket for real-time** - Once basic functionality works
|
|
3. **Build simple UI** - Focus on core features (play, queue, skip)
|
|
4. **Add authentication** - Discord OAuth2
|
|
5. **Polish and deploy** - Make it production-ready
|