GuildScout

Discord Guild Management Bot with Full-Featured Web Dashboard

A production-ready Discord bot that ranks users based on activity, manages guild operations, and provides a modern real-time web dashboard for raid planning, member management, and analytics — enhanced with an AI feedback agent ("Herald") for intelligent user support.

---

Screenshots

Dashboard Overview

Personalized dashboard with active raids, top rankings, quick actions, and live data updates via WebSocket.

Raid Management

Full raid planning system with category filters, role-based signups (Tank/Healer/DPS), live countdown timers, and progress tracking.

Guild Management

Complete ingame guild system with member tracking, rank hierarchy, Discord role sync, and officer tools (kick, ban, DM, notes).

Guild Dashboard

Per-guild dashboard with interactive stats, rank distribution chart, real-time activity feed, and quick action grid.

---

Tech Stack

Backend

Frontend

Bot

AI & Infra

---

Architecture

                    ┌──────────────────┐
                    │   React Dashboard │
                    │   (TypeScript)    │
                    └────────┬─────────┘
                             │ REST + WebSocket
                    ┌────────▼─────────┐
                    │     Go API       │
                    │    (Fiber)       │
                    └───┬────────┬─────┘
                        │        │
            ┌───────────▼──┐  ┌──▼───────────┐
            │  PostgreSQL  │  │    Redis      │
            │   (Data)     │  │  (Pub/Sub)    │
            └───────────▲──┘  └──▲───────────┘
                        │        │
              ┌─────────┴────────┴───────┐
              │                          │
    ┌─────────▼──────────┐   ┌───────────▼─────────┐
    │   Discord Bot      │   │   AI Agent "Herald"  │
    │    (Python)         │   │   (Codex / Claude)   │
    └────────────────────┘   └──────────────────────┘

Key architectural decisions:

• Bidirectional sync between Discord Bot and Web Dashboard via Redis Pub/Sub
• Real-time updates through WebSocket (no polling)
• PostgreSQL as single source of truth for all data
• Bot runs on host (systemd) while API runs in Docker (Traefik reverse proxy)
• AI Agent "Herald" for multi-turn feedback conversations (Codex primary, Claude fallback)

---

Features

Core

• Activity-based ranking with configurable weights (messages, voice, membership duration)
• Real-time scoring with percentile comparisons and visual rank cards
• Multi-guild support with Discord OAuth authentication
• Multi-game support with game-specific weapons, builds, and filters
• Internationalization (DE/EN) across 15 namespaces for dashboard and bot

Raid System

• Full lifecycle management: Create, edit, lock, close, cancel raids
• Template system: Reusable raid configurations with role limits
• Category & Mode system: PvE, PvP, Guild Wars with different group sizes
• Role-based signups: Tank/Healer/DPS with auto-promote from bench
• Weapon/Build system: Per-signup weapon selection with game-specific filtering, displayed in Discord embeds
• Guild War results: Win/loss/draw tracking with MVP selection and rank points
• iCal export: Add raids to personal calendars
• Push notifications: Web Push + Discord DM with user preferences

Guild Management

• Ingame guild system: Full CRUD for guilds, ranks, and members
• Game selector: Combo-dropdown from games registry or custom input per guild
• Rank hierarchy: Priority-based with Discord role auto-mapping
• Member detail: Event timeline, officer notes, Discord actions (kick/ban/DM/nickname)
• Dashboard per guild: Statistics, rank distribution, activity feed

AI Feedback System ("Herald")

• Multi-turn conversations: Up to 5-turn Discord DM dialogs for deeper understanding
• 3 conversation intents: user_error_check, need_more_info, feature_exists
• AI closure summaries: Automatic analysis summary when closing feedback
• GitHub Living Document: Issue body updated in-place with AI analysis and status badges
• Dashboard integration: Chat-bubble layout with live WebSocket updates
• UI knowledge base: Agent understands dashboard features for targeted help

Permission System

• 5-tier hierarchy: Owner > User Overrides > Discord Role Map > Legacy Roles > Member Roles
• Per-user overrides: Grant/deny individual permissions
• Discord integration: Automatic role sync on login and role changes

Analytics

• Activity charts: Daily/hourly message and voice activity
• Period filtering: 30 days, 90 days, all-time
• MVP leaderboard: Top performers across guild wars
• CSV export: Full ranking data export

---

Project Stats

Metric	Value
Total codebase	~128,000 lines
Go API	~47,700 lines (104 files)
React Dashboard	~38,800 lines (174 files)
Python Bot	~36,000 lines (90 files)
AI Agent	~3,000 lines
Database migrations	43
API endpoints	188
Dashboard pages	20
React components	79
Custom hooks	21
i18n namespaces	15 (DE + EN)
Test suites	~1,726 tests (Go + Python + React)

---

Status

This project is actively used in production on a Discord gaming community at guildscout.eu. The source code is in a private repository.

---

Built by Commandershadow9