GitHub - jonax1337/Synqed: Discord Bot + Web Dashboard for E-Sports team scheduling

A comprehensive Discord bot + web dashboard for E-Sports team scheduling

Quick Start • API Reference • Commands • Deployment

Tech Stack

Backend

Dashboard

About

Synqed is a full-stack scheduling solution designed for E-Sports teams. It combines Discord's familiar interface with a powerful web dashboard to manage player availability, coordinate training sessions, track scrims, and plan strategies.

Why This Bot?

Dual Interface - Discord commands for quick access + Web dashboard for detailed management
Smart Analysis - Automatically calculates overlapping time windows for all available players
Automation - Daily schedule posts, reminder notifications, and automated jobs via node-cron
Role Management - Support for main roster, substitutes, and coaches
Timezone-Aware - Per-user timezone support with automatic time conversion
VOD Review - Collaborative video analysis with timestamped comments
Stratbook - Local strategy management with TipTap rich text editor
Secure - JWT authentication, bcrypt password hashing, rate limiting, CORS protection

Features

Discord Bot

Feature	Description
Interactive Availability	Button-based UI for quick availability updates
Smart Schedule Analysis	Detects roster status (full, needs subs, can't proceed)
Time Window Calculation	Finds common available time slots
Per-User Timezone	Players set their timezone via `/set-timezone`
Recurring Availability	Set weekly default patterns that auto-apply
Quick Polls	Custom polls with countdown timer and auto-recovery
Training Polls	Vote on preferred training start times
Absence Management	Plan absences in advance with automatic marking

Web Dashboard

Feature	Description
Schedule Editor	Spreadsheet-like editor for schedule entries
Scrim Manager	Track opponents, results, VOD URLs, agent compositions
VOD Review	YouTube player with timestamped comments, filtering, mentions
Statistics	Availability charts, scrim results, win/loss streaks
Stratbook	TipTap editor with folders, map/side filtering, file uploads
User Portal	Self-service availability with live database updates
Live Logs	Stream bot activity, warnings, and errors
Dark Mode	Full dark mode with system preference detection

Automation

Daily Schedule Posts - Automatic posting at configured time
Smart Reminders - DM notifications before post time
Change Notifications - Channel alerts when roster status changes
Schedule Seeding - Maintains 14-day rolling window automatically

Quick Start

Prerequisites

Node.js v20 or higher
PostgreSQL 14+ (local or managed service)
Discord Bot application (setup guide)

Installation

# Clone the repository
git clone https://github.com/jonax1337/Synqed.git
cd Synqed

# Install backend dependencies
npm install

# Install dashboard dependencies
cd dashboard && npm install && cd ..

# Create environment file
cp .env.example .env
# Edit .env with your values (see Configuration section)

# Run database migrations
npx prisma migrate deploy

# Build and start
npm run build
npm start

# Start dashboard (separate terminal)
cd dashboard && npm run dev

Environment Variables

# Required
DISCORD_TOKEN=your_bot_token
DISCORD_GUILD_ID=your_server_id
DATABASE_URL=postgresql://user:pass@localhost:5432/schedule_bot
ADMIN_USERNAME=admin
ADMIN_PASSWORD_HASH=bcrypt_hash  # Generate: node dist/generateHash.js YOUR_PASSWORD
JWT_SECRET=random_32+_char_string

# Optional - Discord OAuth
DISCORD_CLIENT_ID=your_client_id
DISCORD_CLIENT_SECRET=your_client_secret
DISCORD_REDIRECT_URI=http://localhost:3000/auth/callback

# Optional - URLs
DASHBOARD_URL=http://localhost:3000
BOT_API_URL=http://localhost:3001
NEXT_PUBLIC_BOT_API_URL=http://localhost:3001

Architecture

┌──────────────────┐         ┌──────────────────┐
│                  │         │                  │
│  Discord Server  │◄────────┤  Discord Bot     │
│  (User Input)    │         │  (discord.js)    │
│                  │         │                  │
└──────────────────┘         └────────┬─────────┘
                                      │
                                      ▼
                      ┌───────────────────────────┐
                      │   Node.js Backend         │
                      │   ┌─────────────────┐     │
                      │   │ Bot Logic       │     │
                      │   ├─────────────────┤     │
                      │   │ Scheduler       │     │
                      │   │ (node-cron)     │     │
                      │   ├─────────────────┤     │
                      │   │ API Server      │     │
                      │   │ (Express :3001) │     │
                      │   └─────────────────┘     │
                      └───────────┬───────────────┘
                                  │
                  ┌───────────────┼───────────────┐
                  ▼               ▼               ▼
         ┌────────────┐  ┌────────────┐  ┌────────────┐
         │ PostgreSQL │  │  Vite SPA  │  │  Discord   │
         │ (Prisma 7) │  │  Dashboard │  │  OAuth     │
         │            │  │  :3000     │  │ (optional) │
         └────────────┘  └────────────┘  └────────────┘

Project Structure

synqed/
├── src/                      # Backend TypeScript
│   ├── index.ts              # Entry point
│   ├── api/                  # Express server + routes
│   ├── bot/                  # Discord bot (commands, events, interactions)
│   ├── jobs/                 # node-cron scheduler
│   ├── repositories/         # Prisma data access layer
│   └── shared/               # Config, middleware, utils
├── dashboard/                # Vite + React SPA
│   ├── index.html            # Vite entry HTML
│   ├── vite.config.ts        # Vite + Tailwind plugin + path alias
│   └── src/
│       ├── main.tsx          # App bootstrap
│       ├── App.tsx           # Providers + React Router routes
│       ├── pages/            # Route components
│       ├── components/       # admin/ · user/ · shared/ · shells/ · ui/ (shadcn)
│       ├── hooks/            # Custom React hooks
│       └── lib/              # Utilities, API client, auth
├── prisma/                   # Database schema + migrations
└── assets/                   # Logo, banner, brand assets

Discord Commands

User Commands

Command	Description
`/schedule [date]`	View team availability for a date
`/schedule-week`	Show next 7 days overview
`/my-schedule`	Your personal 14-day schedule
`/set`	Set your availability interactively
`/set-timezone`	Set your personal timezone
`/set-recurring`	Set recurring weekly availability
`/my-recurring`	View your recurring schedule
`/view-scrims`	View recent match results
`/scrim-stats`	View win/loss statistics

Admin Commands

Command	Description
`/post-schedule`	Post schedule to channel
`/register @user`	Register user in database
`/unregister @user`	Remove user mapping
`/remind`	Send reminders manually
`/notify`	Send notification to players
`/poll`	Create quick poll
`/add-scrim`	Add scrim result

Discord Bot Setup

Go to Discord Developer Portal
Click "New Application" → Enter name → "Create"
Navigate to "Bot" tab → "Add Bot"
Copy the token → Save as DISCORD_TOKEN
Enable SERVER MEMBERS INTENT under Privileged Gateway Intents
Navigate to "OAuth2" → "URL Generator"
Select scopes: bot, applications.commands
Select permissions: View Channels, Send Messages, Embed Links, Add Reactions, Use Slash Commands, Read Message History
Open the generated URL to invite the bot
Copy your server ID (Developer Mode) → Save as DISCORD_GUILD_ID

Database Setup

Local PostgreSQL

# Create database
psql -U postgres
CREATE DATABASE schedule_bot;
\q

# Configure DATABASE_URL in .env
DATABASE_URL="postgresql://postgres:password@localhost:5432/schedule_bot"

# Run migrations
npx prisma migrate deploy

# Optional: Open database GUI
npx prisma studio

Managed Services

Works with Railway, Supabase, Neon, or any PostgreSQL provider. Just set the DATABASE_URL connection string.

Deployment

One-Click Deploy (Railway)

Deploys Backend + Frontend + PostgreSQL automatically.

Docker Compose

git clone https://github.com/jonax1337/Synqed.git
cd Synqed
cp .env.example .env
# Edit .env with your values
docker compose up -d

Manual Deployment

# Backend
npm run build
npm start

# Dashboard
cd dashboard
npm run build
npm start

Development

# Terminal 1: Backend (hot reload)
npm run dev

# Terminal 2: Dashboard
cd dashboard && npm run dev

# Terminal 3: Database GUI (optional)
npx prisma studio

Key Commands

npm run build              # Build backend
npm run dev                # Dev mode (rebuild + start)
npm test                   # Run tests
npm run test:coverage      # Tests with coverage
npm run db:generate        # Regenerate Prisma client
npm run db:migrate         # Run migrations (dev)
npm run db:studio          # Open Prisma Studio

Important Notes

ES Modules - All imports need .js extension (even for .ts files)
Date Format - Always use DD.MM.YYYY (e.g., "24.01.2026")
Availability Format - Empty = no response, "x" = unavailable, "HH:MM-HH:MM" = time window

API Documentation

The bot runs an Express REST API on port 3001.

Authentication

JWT-based (24h expiry)
Header: Authorization: Bearer <token>
Admin login: /api/admin/login
User login: /api/user/login or Discord OAuth

Key Endpoints

# Schedule
GET  /api/schedule/next14
POST /api/schedule/update-availability

# User Mappings
GET  /api/user-mappings
POST /api/user-mappings

# Scrims
GET  /api/scrims
POST /api/scrims
GET  /api/scrims/stats/summary

# Strategies
GET  /api/strategies
POST /api/strategies

# Actions (Admin)
POST /api/actions/schedule
POST /api/actions/remind
POST /api/actions/poll

# Monitoring
GET  /api/health
GET  /api/bot-status

Troubleshooting

Issue	Solution
Bot doesn't respond	Check token, permissions, and intents in Developer Portal
Database connection fails	Verify `DATABASE_URL` format, test with `npx prisma db pull`
Dashboard can't connect	Check `NEXT_PUBLIC_BOT_API_URL`, verify API is running
OAuth not working	Verify redirect URI matches exactly in Developer Portal
Commands not registering	Ensure `GUILDS` and `GUILD_MEMBERS` intents are enabled

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m "Add amazing feature"
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Guidelines

TypeScript strict mode is enabled
Use async/await for all database operations
Follow existing code style and patterns
Add tests for new features

License

This project is licensed under the MIT License.

Acknowledgments

discord.js - Discord API library
Vite - Frontend build tool & dev server
React Router - SPA routing
shadcn/ui + Radix UI - UI components
Prisma - Database ORM
TailwindCSS - CSS framework

Made with ❤️ for E-Sports teams

Name		Name	Last commit message	Last commit date
Latest commit History 743 Commits
.claude		.claude
.github		.github
assets		assets
dashboard		dashboard
docs		docs
prisma		prisma
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
prisma.config.ts		prisma.config.ts
railway.toml		railway.toml
render.yaml		render.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Tech Stack

About

Why This Bot?

Features

Discord Bot

Web Dashboard

Automation

Quick Start

Prerequisites

Installation

Environment Variables

Architecture

Project Structure

Discord Commands

User Commands

Admin Commands

Discord Bot Setup

Database Setup

Local PostgreSQL

Managed Services

Deployment

One-Click Deploy (Railway)

Docker Compose

Manual Deployment

Development

Key Commands

Important Notes

API Documentation

Authentication

Key Endpoints

Troubleshooting

Contributing

Guidelines

License

Acknowledgments

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages