A modular Discord bot + admin platform that syncs community engagement between Discord and openmicodyssey.com. The system includes onboarding roles, stage queue management, mileage progression, content syndication, an admin API, and a React admin dashboard.

Core Features

The Call Sheet (Onboarding + Roles)

Reaction-role onboarding message with emoji-to-role bindings
Role hierarchy safety checks before assignment/removal
Optional onboarding completion role and welcome-channel message

The Tour Schedule (Stage Queue)

/sign-up subcommands: join, leave, list, next, clear
FIFO queue per guild
Optional stage-speaker promotion and queue announcement dispatch

The Dailies (Content Syndication)

Adapter-based polling pipeline
YouTube RSS adapter implemented
Discord webhook dispatch with duplicate suppression

Mileage Engine

PostgreSQL-backed mileage event/user persistence
Configurable event scoring
Role-tier upgrades on threshold milestones
Retry behavior for transient write failures

Admin API + Dashboard

Express Admin API for config, queue, stats, OAuth bridge, configuration DB
React/Vite dashboard for OAuth login + analytics views

OAuth2 Bridge

Discord OAuth2 code exchange to user profile
Ephemeral session issuance
Optional sync callback to openmicodyssey.com backend

Configuration Database

bot_settings, content_schedules, engagement_stats tables
Admin CRUD endpoints for settings/schedules
Engagement snapshot persistence from runtime events

Implemented Modules

src/bot.ts: gateway client lifecycle, command dispatch, service wiring
src/call-sheet.ts: reaction role onboarding and role hierarchy guards
src/tour-schedule.ts: FIFO queue, stage speaker promotion, announcements
src/mileage.ts: mileage persistence, scoring, role-upgrade triggers
src/dailies/*: adapter/poller/webhook syndication pipeline
src/admin-api.ts: operational and configuration endpoints
src/oauth-bridge.ts: Discord code exchange + openmic session sync
src/configuration-database.ts: bot settings, schedules, engagement snapshots
admin-dashboard/src/*: admin SPA, OAuth callback flow, analytics views

Architecture Documentation (arc42)

This project uses the arc42 template. Chapters are in docs/.

Architecture & Tech Stack

Layer	Choice
Runtime	Node.js + TypeScript
Discord SDK	discord.js
Database	PostgreSQL
Admin API	Express
Admin Dashboard	React + Vite
Auth	Discord OAuth2
Hosting	Coolify + Nixpacks

Getting Started

Prerequisites

Node.js 22+
npm 10+
Discord Developer Application (bot token + OAuth2 app)
PostgreSQL instance
Discord server where you can install bots with role/channel permissions

Discord Bot Setup (Portal)

Open Discord Developer Portal and create a new application.
In Bot tab, click Add Bot.
Copy these values for runtime config (bot_settings):
- DISCORD_TOKEN from Bot tab (Reset Token if needed)
- DISCORD_CLIENT_ID from OAuth2 > General
In Bot > Privileged Gateway Intents, enable only:
- Server Members Intent (required by current code)
Keep these disabled unless code changes require them:
- Message Content Intent
- Presence Intent

Current gateway intents used by this project (src/bot.ts):

Guilds
GuildMembers (privileged)
GuildMessageReactions

Discord Bot Install (OAuth2 URL)

Open OAuth2 > URL Generator.
Select scopes:
- bot
- applications.commands
Select bot permissions (minimum recommended for current features):
- View Channels
- Send Messages
- Read Message History
- Add Reactions
- Manage Roles (call-sheet role assignment)
- Manage Channels (queue moderation paths)
Use generated URL to add bot to your server.

Installation

Clone repository:

git clone https://git.allucanget.biz/allucanget/omo-bot.git
cd omo-bot

Install root dependencies:

npm install

Configure bootstrap environment variables (.env from .env.example):

DATABASE_URL=postgres://...
CONFIG_DB_ENABLED=true
DISCORD_GUILD_ID=... # optional seed scope

npm run register:commands

Run bot in development:

npm run dev

Build and run production bundle:

npm run build
npm start

Admin Dashboard

cd admin-dashboard
npm install
npm run dev

Dashboard environment template: admin-dashboard/.env.example.

Validation Commands

npm run lint
npm run build
npm run test

Database Setup Commands

DATABASE_URL is required for each command.

npm run db:migrate
npm run db:seed
npm run db:setup

db:migrate: applies schema migrations tracked in schema_migrations
db:seed: ensures migrations are applied, then inserts initial config values from environment into bot_settings when missing
db:setup: runs migrate then seed

Runtime Config Source

Runtime reads configuration keys from bot_settings table first, then falls back to environment values.

Global scope: guild_id = __global__
Guild override scope: guild_id = DISCORD_GUILD_ID
Key names match previous env variable names (examples: DISCORD_TOKEN, DISCORD_CLIENT_ID, ADMIN_API_TOKEN)

Recommended flow:

Set bootstrap env (DATABASE_URL, optional DISCORD_GUILD_ID).
Run npm run db:migrate.
Run npm run db:seed once while legacy env vars are still present.
Remove legacy runtime vars from .env after confirming bot_settings contains required keys.

Deployment

Deployment setup and domain configuration moved to DEPLOYMENT.md.

Coolify project/resource setup
Real domain DNS/TLS and routing patterns
Discord OAuth production redirect alignment
Gitea Actions secret configuration for deploy hooks
Two-resource deploy flow (omo-bot-backend + omo-bot-dashboard)

Dashboard quality check:

cd admin-dashboard
npm run lint
npm run build

Admin API Endpoints

GET /health
GET /admin/config
GET /admin/stats?guildId=...
GET /admin/schedule?guildId=...
POST /admin/schedule/clear
POST /admin/oauth/discord/exchange
GET /admin/oauth/session/:sessionId
GET /admin/db/settings?guildId=...
PUT /admin/db/settings
GET /admin/db/schedules?guildId=...
PUT /admin/db/schedules
DELETE /admin/db/schedules/:guildId/:scheduleKey
GET /admin/db/engagement/latest?guildId=...

CI/CD (Gitea Actions)

Pipeline file: .gitea/workflows/ci-cd.yml

For full deployment flow, webhook secret strategy, and two-resource Coolify deployment, see DEPLOYMENT.md.

Contributing

Internal development only. See CONTRIBUTING.md.