zwitschi
77e43a6a38
- Created .gitignore to exclude unnecessary files - Added README.md with project description and core features - Introduced CONTRIBUTING.md for development guidelines - Established documentation files for architecture, quality requirements, and technical risks
119 lines
6.1 KiB
Markdown
119 lines
6.1 KiB
Markdown
# 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.
|