Discord Bot for Open Mic Odyssey

A custom Discord bot and web integration layer designed to bridge the openmicodyssey.com experience with our community server. This application gamifies community engagement, automates content syndication, and provides a suite of event management tools centered around the themes of stand-up comedy, indie filmmaking, and a cross-country road trip.

Core Features

The Call Sheet (User & Role Management)

• The Experience: New members are greeted with a customized onboarding menu to declare their interests (e.g., @ComedyFan, @Filmmaker). Active users progress through community ranks, leveling up from "Extra" to "Roadie" and eventually "Executive Producer".
• Technical Implementation: Utilizes Discord's Reaction Role payloads and interaction webhooks for automated Role-Based Access Control (RBAC). Implements dynamic permission bitfield assignment and role hierarchy state management based on user activity telemetry.

The Tour Schedule (Event Management)

• The Experience: Organizes virtual "Tour Stops" (screenings) and digital open mics. Users can utilize the /sign-up command to enter the stage queue, while attendees receive temporary "VIP Backstage" passes for live Q&As.
• Technical Implementation: Wraps the Discord Scheduled Events API. Implements a FIFO (First-In-First-Out) queue data structure for managing Voice/Stage channel speaker states. Handles automated role assignment/revocation for temporary event permissions.

The Dailies (Content Webhooks & Syndication)

• The Experience: Automatically delivers fresh behind-the-scenes content directly from the crew's socials to dedicated server channels:

• #polaroids-from-the-van: Instagram drops.

• #outtakes: TikTok crowd work and detours.

• #screenings: YouTube trailers and vlogs.

• Technical Implementation: Event-driven architecture utilizing incoming Discord Webhooks. Integrates external API polling (YouTube Data API, TikTok/IG endpoints) to fetch, parse, and format multimedia payloads into rich Discord Embeds.

Mileage & The Hidden Map (Gamified Progression)

• The Experience: Every interaction earns users "Mileage". Accumulating miles unlocks secure passwords and GPS coordinates for the hidden /map route on the main website, granting access to deleted scenes and exclusive scripts.
• Technical Implementation: Requires Discord OAuth2 integration with the main web application. Message and event telemetry are captured, scored, and stored in a database (e.g., PostgreSQL/MongoDB), continuously syncing the user's Discord state with their authenticated web session.

The Control Room (Admin Web Interface)

• The Experience: A dedicated dashboard for the "Producers" and "Directors" to manage the server, schedule content drops, and view engagement without touching Discord commands.
• Technical Implementation: A standalone web portal (intended for admin.openmicodyssey.com). Exposes secure RESTful/GraphQL endpoints for bot configuration, CRON job scheduling for content drops, and data visualization for external link click-through rates.

Architecture Documentation (arc42)

This project uses the arc42 architecture documentation template.
All chapters are in docs/:

#	Chapter	File
1	Introduction & Goals	docs/01_introduction_and_goals.md
2	Architecture Constraints	docs/02_architecture_constraints.md
3	Context & Scope	docs/03_context_and_scope.md
4	Solution Strategy	docs/04_solution_strategy.md
5	Building Block View	docs/05_building_block_view.md
6	Runtime View	docs/06_runtime_view.md
7	Deployment View	docs/07_deployment_view.md
8	Cross-cutting Concepts	docs/08_concepts.md
9	Architecture Decisions	docs/09_architecture_decisions.md
10	Quality Requirements	docs/10_quality_requirements.md
11	Risks & Technical Debt	docs/11_technical_risks.md
12	Glossary	docs/12_glossary.md

Architecture & Tech Stack

Layer	Choice
Runtime	Node.js (Discord.js)
Database	PostgreSQL
Admin Dashboard	React
Auth	Discord OAuth2
Hosting	Coolify + Nixpacks

Getting Started

Prerequisites

• Node.js v16+ (or Python 3.9+)
• A Discord Developer Application with Bot Token
• Access to openmicodyssey.com backend for OAuth syncing

Installation

1. Clone the repository:

git clone https://github.com/your-org/open-mic-odyssey-bot.git
cd open-mic-odyssey-bot

2. Install dependencies:

npm install

3. Configure environment variables. Duplicate .env.example to .env and add your specific keys:

DISCORD_TOKEN=your_bot_token
CLIENT_ID=your_client_id
GUILD_ID=your_server_id
DB_CONNECTION_STRING=your_db_uri
YOUTUBE_API_KEY=your_yt_key

4. Deploy Slash Commands:

npm run deploy-commands

5. Start the bot:

npm start

Contributing

For internal development only. Please refer to CONTRIBUTING.md for styling guidelines and PR review processes for "The Control Room" dashboard updates.