# Discord Bot for Open Mic Odyssey

A custom Discord bot and web integration layer designed to bridge the [openmicodyssey.com](https://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](https://arc42.org) architecture documentation template.  
All chapters are in `docs/`:

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

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

```

2. Install dependencies:

```bash
npm install

```

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

```env
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:

```bash
npm run deploy-commands

```

5. Start the bot:

```bash
npm start

```

## Contributing

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