omo-bot/README.md

Discord Bot for Open Mic Odyssey

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

Installation

1. Clone repository:

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

2. Install root dependencies:

npm install

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

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

4. Register slash commands:

npm run register:commands

5. Run bot in development:

npm run dev

6. 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: 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:

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

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

Flow:

• bot checks: npm ci -> npm run lint -> npm run build -> npm run test
• dashboard checks: admin-dashboard/npm ci -> npm run lint -> npm run build
• deploy: on push to main, trigger Coolify deploy webhook

Required Gitea secrets:

• COOLIFY_DEPLOY_HOOK_URL (required)
• COOLIFY_DEPLOY_TOKEN (optional bearer token)

Contributing

Internal development only. See CONTRIBUTING.md.