allucanget/omo-bot
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add initial project structure, including README, CONTRIBUTING, and documentation files

Browse Source 
- 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
This commit is contained in:
zwitschi
2026-05-17 15:50:43 +02:00
commit 77e43a6a38
16 changed files with 692 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+20
View File
@@ -0,0 +1,20 @@
# agents
.agents/
.clinerules/
.cursor/
.github/instructions/
.github/copilot-instructions.md
.opencode/
.windsurf/
AGENTS.md
skills-lock.json
# environment files
.env
# node modules
node_modules/
# build and test outputs
dist/
coverage/
CONTRIBUTING.md
+33
View File
@@ -0,0 +1,33 @@
# Contributing
Internal development only. PRs reviewed by @directors.
## Code Standards
- **Language:** TypeScript (Node.js) per ADR-001
- **Commands:** kebab-case (`/sign-up`, not `/signup`)
- **Events:** `on<EventName>` handler pattern
- **DB:** snake_case table names, plural
- **Commits:** [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:`, `docs:`)
- **Env vars:** Required vars documented in `.env.example`. Never commit `.env`.
## PR Process
1. Branch from `main`. Name: `feat/`, `fix/`, `chore/` prefix.
2. Lint + tests pass before push.
3. PR description links to any related issue.
4. At least 1 approval from @directors required.
5. Squash-merge to `main`.
## Reporting Issues
Open GitHub issue with:
- Steps to reproduce
- Expected vs actual behavior
- Bot logs (redact tokens)
- Discord command and response if relevant
## Architecture Reference
See [arc42 docs](/docs/01_introduction_and_goals.md) for full architecture context.
README.md
+118
View File
@@ -0,0 +1,118 @@
# 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.
docs/01_introduction_and_goals.md
+34
View File
@@ -0,0 +1,34 @@
# Introduction and Goals
## Business Goals
- **Community engagement gamification** — Drive member participation through mileage-based progression system
- **Content syndication automation** — Auto-deliver YouTube, Instagram, TikTok content to Discord channels
- **Event management simplification** — Streamline virtual "Tour Stop" screenings and open mic scheduling
- **Cross-platform bridge** — Connect Discord community with openmicodyssey.com via OAuth2
## Essential Features
- Reaction-role onboarding ("The Call Sheet")
- Event queue management with `/sign-up` command
- Automated webhook syndication ("The Dailies")
- Mileage-based progression system
- Admin web dashboard ("The Control Room")
## Quality Goals
| Priority | Goal | Scenario |
| -------- | ---------------- | ------------------------------------------------------------------------------------- |
| 1 | Availability | Bot responds within 2s during peak events (100+ concurrent users) |
| 2 | Data consistency | Mileage and role state survive bot restarts without drift |
| 3 | Extensibility | New content sources (Twitter, RSS) addable via adapter without core changes |
| 4 | Security | OAuth2 tokens never exposed; role assignments authorized via Discord permission model |
## Stakeholders
| Role | Contact | Expectation |
| ----------------- | ------------------ | ------------------------------------------------------- |
| Community Manager | @producers | Easy event scheduling, content automation |
| Developer | @directors | Clean codebase, documented APIs, testable |
| End User | @community | Fun onboarding, seamless XP tracking, reliable commands |
| Site Owner | openmicodyssey.com | Secure OAuth2 bridge, accurate mileage sync |
docs/02_architecture_constraints.md
+25
View File
@@ -0,0 +1,25 @@
# Architecture Constraints
## Technical Constraints
| Constraint | Description |
| ---------- | --------------------------------------------------------------------------------------------------- |
| Runtime | Discord Bot must run on Node.js (Discord.js) or Python (Discord.py) per existing proposal |
| Hosting | Bot process must run 24/7 — planned deployment to Coolify |
| API Limits | Discord rate limits (50 req/s per route); webhook pollers must respect YouTube/IG/TikTok quota caps |
| OAuth2 | Web app auth must use Discord OAuth2 — no custom auth service |
| Database | PostgreSQL or MongoDB required for mileage and state persistence |
## Organizational Constraints
| Constraint | Description |
| ----------- | ----------------------------------------------------------------------------------------- |
| Development | Internal team only; no open-source contributions from outside |
| Deployment | Admin dashboard hosted at `admin.openmicodyssey.com` — CORS and subdomain config required |
| Branding | All documentation, embeds, and UI must reflect "Open Mic Odyssey" road-trip theme |
## Conventions
- Git commit messages follow Conventional Commits format
- Environment variables stored in `.env`, never committed
- Slash commands registered via `deploy-commands` script, not manual guild config
docs/03_context_and_scope.md
+33
View File
@@ -0,0 +1,33 @@
# Context and Scope
## Business Context
```txt
┌─────────────────┐ Discord API ┌──────────────────┐
│ Discord Users │◄───────────────────────► │ omo-bot │
│ (Community) │ slash cmds, embeds │ (Discord Bot) │
└─────────────────┘ └────────┬─────────┘
│
OAuth2 + REST │
▼
┌────────────────┐
│ openmicodyssey │
│ .com (Web App) │
└────────────────┘
```
## Technical Context
| Partner | Protocol | Data | Description |
| ------------------ | -------------------------- | --------------------------------------- | ------------------------------------ |
| Discord API | WebSocket (Gateway) + REST | Messages, roles, events, voice states | Bot core communication |
| YouTube Data API | HTTPS (REST + polling) | Video metadata, thumbnails | Auto-post new uploads to #screenings |
| Instagram API | HTTPS (REST + polling) | Image URLs, captions | Auto-post to #polaroids-from-the-van |
| TikTok API | HTTPS (REST + polling) | Video metadata | Auto-post to #outtakes |
| openmicodyssey.com | HTTPS (OAuth2 + REST) | User profiles, mileage data, map routes | Web session sync |
## Scope
**In scope:** Discord bot commands, reaction-role management, event queue, content webhook syndication, mileage tracking, admin dashboard API.
**Out of scope:** The main `openmicodyssey.com` website frontend, native mobile apps, third-party content moderation.
docs/04_solution_strategy.md
+33
View File
@@ -0,0 +1,33 @@
# Solution Strategy
## Technology Decisions
| Decision | Choice | Rationale |
| ---------------- | -------------------- | --------------------------------------------------------------------------------------- |
| Bot framework | Discord.js (Node.js) | Mature library, strong type support, rich event model |
| Database | PostgreSQL | Reliable, supports JSONB for flexible user state, well-suited for mileage/role tracking |
| Frontend (Admin) | React | Team familiarity, rich ecosystem for dashboards |
| Hosting | Coolify | Easy deployment for Node.js with Nixpacks. |
| Auth | Discord OAuth2 | No custom auth needed, seamless web/bot integration |
## Top-Level Decomposition
The system follows a **modular monolith** pattern with clear separation:
- **Core Bot** — command handlers, event listeners, Discord Gateway logic
- **Content Syndicator** — polling adapters for YouTube/IG/TikTok, webhook dispatch
- **Event Manager** — FIFO queue for stage/speaker management
- **Mileage Engine** — scoring logic, persistence, state sync with web app
- **Admin API** — RESTful endpoints for bot config, content scheduling, analytics
## Key Quality Goals
- **Availability** — Stateless bot instances scale horizontally behind load balancer
- **Consistency** — Write-ahead logging for mileage transactions; periodic state reconciliation with web app
- **Extensibility** — Adapter pattern for content sources: implement interface, register, deploy
## Organizational Decisions
- One-person or small-team development per project scope
- CI/CD via Gitea Actions: lint → test → deploy
- Feature toggles for admin dashboard rollout
docs/05_building_block_view.md
+41
View File
@@ -0,0 +1,41 @@
# Building Block View
## Whitebox Overall System (Level 1)
```txt
┌──────────────────────────────────────────────────────┐
│ omo-bot │
├──────────────────────────────────────────────────────┤
│ ┌──────────────────┐ ┌─────────────────────────┐ │
│ │ Command Layer │ │ Event Listener Layer │ │
│ │ /sign-up, /map │ │ member_join, reaction │ │
│ └────────┬─────────┘ └───────────┬─────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Service Layer │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │
│ │ │ Event │ │ Mileage │ │ Content │ │ │
│ │ │ Manager │ │ Engine │ │ Syndicator │ │ │
│ │ └──────────┘ └──────────┘ └──────────────┘ │ │
│ └───────────────────┬──────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Data / Persistence Layer │ │
│ │ PostgreSQL DB + Discord API Wrapper │ │
│ └──────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
```
### Black Box Descriptions
| Building Block | Responsibility |
| ------------------ | ------------------------------------------------------------------------------------------ |
| Command Layer | Register and handle slash commands (`/sign-up`, `/map`, `/help`); validate permissions |
| Event Listener | Subscribe to Discord Gateway events (member join, reaction add, voice state change) |
| Event Manager | Manage FIFO queue for voice/stage speakers; schedule "Tour Stop" events via Discord API |
| Mileage Engine | Score user interactions, persist to DB, trigger role upgrades, sync with web app |
| Content Syndicator | Poll YouTube/IG/TikTok APIs; format rich embeds; dispatch to Discord channels via webhooks |
| Admin API | Expose REST endpoints for dashboard (configuration, content schedule, engagement stats) |
| DB Layer | PostgreSQL connection pool, migrations, query builders |
docs/06_runtime_view.md
+28
View File
@@ -0,0 +1,28 @@
# Runtime View
## Scenario: User Signs Up for Open Mic
1. User runs `/sign-up` in voice channel
2. Command Layer validates user has `@ComedyFan` role
3. Event Manager adds user to FIFO queue
4. When previous speaker leaves stage (voice state change), Event Manager pops queue
5. Bot grants temporary speaker permission via voice channel API
6. Announcement sent to `#stage-door` channel
7. Mileage Engine awards +50 miles for participation
## Scenario: Content Auto-Post
1. CRON job triggers Content Syndicator every 15 min
2. Syndicator polls YouTube Data API for new uploads on channel
3. New video detected → fetches metadata + thumbnail
4. Syndicator builds rich embed (title, description, thumbnail, link)
5. Embed posted to `#screenings` channel via Discord webhook
6. Mileage Engine awards +10 miles to channel subscribers
## Scenario: Admin Updates Bot Restart
1. Bot receives SIGTERM from hosting platform
2. Graceful shutdown initiated: close Gateway connection, flush pending DB writes
3. Bot process restarts
4. On startup: reconnect to Discord Gateway, rehydrate in-memory state from DB
5. Mileage state is consistent — no data loss
docs/07_deployment_view.md
+46
View File
@@ -0,0 +1,46 @@
# Deployment View
## Infrastructure Overview
```txt
┌─────────────┐ ┌──────────────────────────────────────┐
│ Discord │◄─────►│ Coolify │
│ Gateway │ WSS │ │
│ + REST API │ │ ┌──────────────────────────────┐ │
└─────────────┘ │ │ omo-bot (Node.js process) │ │
│ │ - Command handlers │ │
│ │ - Event listeners │ │
│ │ - Mileage engine │ │
│ └──────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────┐ │
│ │ PostgreSQL (local) │ │
│ │ - User profiles │ │
│ │ - Mileage scores │ │
│ │ - Event schedules │ │
│ │ - Content cache │ │
│ └──────────────────────────────┘ │
│ │
│ ┌──────────────────────────────┐ │
│ │ Admin API / Dashboard │ │
│ │ (React SPA) │ │
│ │ admin.openmicodyssey.com │ │
│ └──────────────────────────────┘ │
└──────────────────────────────────────┘
│
OAuth2 │
▼
┌─────────────────────┐
│ openmicodyssey.com │
│ (Web Application) │
└─────────────────────┘
```
## Environments
| Environment | Host | Bot Instance | DB | Purpose |
| ----------- | ---------------- | ------------ | ---------------- | ---------------------------- | ---------------------- |
| Development | Local machine | 1 process | Local Postgres | Feature development, testing |
| Staging | Coolify | 1 instance | Staging Postgres | Integration | Pre-release validation |
| Production | Coolify (scaled) | 2+ instances | Production (HA) | Live community server |
docs/08_concepts.md
+32
View File
@@ -0,0 +1,32 @@
# Cross-cutting Concepts
## Logging & Monitoring
- Structured logging (JSON) to stdout — visible in Coolify logs and via `docker logs`
- Log levels: DEBUG (dev), INFO (prod), ERROR (alert-worthy)
- Key metrics exposed via Prometheus endpoint: commands/sec, webhook latency, active users
## Error Handling
- Command handlers: try/catch → ephemeral error reply to user + logged
- Content pollers: exponential backoff on API failures, alert after 3 consecutive failures
- Mileage writes: retry (3x, 50ms backoff) before logging as failed
## Configuration
- Environment variables via `.env` file (dev) or Coolify secrets (prod), keep example in `.env.example`
- Config schema validated on startup — bot exits on missing required vars
## Security
- Bot token stored in env variable, never logged
- OAuth2 tokens short-lived; refresh flow managed by web app
- Admin dashboard routes guarded by Discord OAuth2 role check (`@Producer` or `@Director`)
- All external API calls over HTTPS
## Conventions
- Slash command names: kebab-case
- Event handler naming: `on<EventName>` pattern
- Database table names: snake_case, plural
- PRs require passing lint + tests before merge
docs/09_architecture_decisions.md
+29
View File
@@ -0,0 +1,29 @@
# Architecture Decisions
## ADR-001: Discord.js over Discord.py
**Status:** Accepted
**Context:** Node.js and Python both viable. Team has stronger Node.js experience.
**Decision:** Use Discord.js for the bot runtime.
**Consequences:** Faster development velocity; ecosystem rich with community plugins (command handling, modals, components).
## ADR-002: PostgreSQL over MongoDB
**Status:** Accepted
**Context:** Mileage data is relational (user → role → event → score). MongoDB adds flexibility but sacrifices query power.
**Decision:** Use PostgreSQL with JSONB columns for extensible user metadata.
**Consequences:** Schema migrations needed for new features; joins straightforward.
## ADR-003: Polling over Webhooks for Content Sources
**Status:** Accepted
**Context:** YouTube, Instagram, TikTok do not provide push webhooks to arbitrary third parties without approval.
**Decision:** Poll public APIs on a CRON schedule (15-min interval).
**Consequences:** ~5 min delay between publish and Discord post; API quota management required.
## ADR-004: Modular Monolith over Microservices
**Status:** Accepted
**Context:** Single-developer or small team; deployment complexity of microservices not justified.
**Decision:** Single process with internal module boundaries (commands, events, mileage, syndication).
**Consequences:** Simpler deploy, debug, and develop; can extract services later if needed.
docs/10_quality_requirements.md
+142
View File
@@ -0,0 +1,142 @@
# Quality Requirements
Content
This section contains all relevant quality requirements.
The most important of these requirements have already been described in
section 1.2. (quality goals), therefore they should only be referenced
here. In this section 10 you should also capture quality requirements
with lesser importance, which will not create high risks when they are
not fully achieved (but might be _nice-to-have_).
Motivation
Since quality requirements will have a lot of influence on architectural
decisions you should know what qualities are really important for your
stakeholders, in a specific and measurable way.
Further Information
- See [Quality Requirements](10_quality_requirements.md) in the
arc42 documentation.
- See the extensive [Q42 quality model on
<https://quality.arc42.org>](https://quality.arc42.org).
## Quality Requirements Overview
Content
An overview or summary of quality requirements.
Motivation
Often we encounter dozens (or even hundreds) of detailed quality
requirements. In this overview section you should try to summarize, e.g.
by describing categories or topics (as suggested by [ISO
25010:2023](https://www.iso.org/obp/ui/#iso:std:iso-iec:25010:ed-2:v1:en)
or [Q42](https://quality.arc42.org))
If these summary descriptions are already precise, specific enough and
measurable, you may skip section 10.2.
Form
Use a simple table in which each line contains a category or topic and a
short description of the quality requirement. Alternatively, you may use
a mindmap to structure these quality requirements. In literature, the
idea of a _quality attribute tree_ has also been described, which puts
the generic term "quality" as the root and uses a tree-like refinement
of the term "quality". \[Bass+21\] introduced the term "Quality
Attribute Utility Tree" for this purpose.
## Quality Scenarios
Content
Quality scenarios make quality requirements concrete and allow to decide
whether they are fulfilled (in the sense of acceptance criteria). Ensure
that your scenarios are specific and measurable.
Two kinds of scenarios are especially useful:
- _Usage scenarios_ (also called application scenarios or use case
scenarios) describe the system’s runtime reaction to a certain
stimulus. This also includes scenarios that describe the system’s
efficiency or performance. Example: The system reacts to a user’s
request within one second.
- _Change scenarios_ describe the desired effect of a modification or
extension of the system or of its immediate environment. Example:
Additional functionality is implemented or requirements for a quality
attribute change, and the effort or duration of the change is
measured.
Form
Typical information for detailed scenarios include the following:
In short form (favoured in the Q42 model):
- **Context/Background**: What kind of system or component, what is the
envirionment or situation?
- **Source/Stimulus**: Who or what initiates or triggers a behaviour,
reaction or action.
- **Metric/Acceptance Criteria**: A response including a _measure_ or
_metric_
The long form of scenarios (favoured by the SEI and \[Bass+21\]) is more
detailed and includes the following information:
- **Scenario ID**: A unique identifier for the scenario.
- **Scenario Name**: A short, descriptive name for the scenario.
- **Source**: The entity (user, system, or event) that initiates the
scenario.
- **Stimulus**: The triggering event or condition the system must
address.
- **Environment**: The operational context or condition under which the
system experiences the stimulus.
- **Artifact**: The building-blocks or other elements of the system
affected by the stimulus.
- **Response**: The outcome or behavior the system exhibits in reaction
to the stimulus.
- **Response Measure**: The criteria or metric by which the system’s
response is evaluated.
Examples
See [the Q42 quality model website](https://quality.arc42.org) for
detailed examples of quality requirements.
Further Information
- Len Bass, Paul Clements, Rick Kazman: "Software Architecture in
Practice", 4th Edition, Addison-Wesley, 2021.
## Project-Specific Scenarios
| Quality | Scenario | Priority | Current Gap |
| ---------------- | --------------------------------------------------- | -------- | ----------------------------------------- |
| Availability | Bot must handle 100+ concurrent users during events | High | Not yet load-tested |
| Responsiveness | Slash commands respond within 2s | High | Baseline OK; need perf testing under load |
| Data consistency | Mileage not lost on crash or restart | High | Write-ahead logging not yet implemented |
| Security | No token leakage via logs or error messages | Critical | Pass — tokens env-only |
| Extensibility | Add new content source in ≤2 days work | Medium | Adapter pattern defined, not yet coded |
## Nice-to-Have
| Quality | Scenario |
| ------------------ | -------------------------------------------- |
| Localization | Embeds and messages in multiple languages |
| Accessibility | Dashboard UI meets WCAG 2.1 AA |
| Offline resilience | Bot caches last hour of events on local disk |
docs/11_technical_risks.md
+20
View File
@@ -0,0 +1,20 @@
# Risks and Technical Debts
## Identified Risks
| Priority | Risk | Likelihood | Impact | Mitigation |
| -------- | ------------------------------------------------ | ---------- | -------- | --------------------------------------------------------------- |
| High | API quota exhaustion (YouTube/TikTok) | Medium | High | Cache aggressively; add quota alerts; stagger poll intervals |
| High | Discord rate limit bans if polling misconfigured | Low | Critical | Implement proper backoff; respect `Retry-After` headers |
| Medium | OAuth2 token expiry during web session | Medium | Medium | Implement refresh token rotation; warn user before expiry |
| Medium | Single-process bot: any crash = total downtime | Medium | High | Use process manager (PM2); deploy to platform with auto-restart |
| Low | Mileage database drift between bot and web app | Low | Medium | Periodic reconciliation job (nightly) |
## Technical Debts
| Item | Area | Description | Priority |
| ---------------- | ------ | -------------------------------------- | -------- |
| No test coverage | All | Tests not implemented for any module | High |
| No CI pipeline | DevOps | Lint + test not automated in PRs | High |
| Inline config | Bot | Some settings hardcoded instead of env | Medium |
| Manual deploy | DevOps | No deployment script / IaC yet | Medium |
docs/12_glossary.md
+14
View File
@@ -0,0 +1,14 @@
# Glossary
| Term | Definition |
| ------------------ | -------------------------------------------------------------- |
| Call Sheet | Onboarding system for role assignment via reaction roles |
| Mileage | Gamified XP earned through community interactions |
| Tour Stop | A scheduled virtual event (screening or open mic) |
| The Dailies | Auto-syndicated content feeds from YouTube/IG/TikTok |
| The Control Room | Admin web dashboard for bot management |
| VIP Backstage | Temporary role granting Q&A access during events |
| Executive Producer | Highest community rank, reached via mileage progression |
| OAuth2 | Discord-based authentication for web app session sync |
| FIFO Queue | First-In-First-Out data structure for stage speaker management |
| Adapter | Pluggable module for adding new content sources |
docs/templates/ADR.md
Vendored
+44
View File
@@ -0,0 +1,44 @@
# Architectural Decision Record (ADR)
This template document outlines the format for recording architectural decisions made during the development of the Open Mic Odyssey Bot. Each decision should be documented in a separate ADR file within the `docs/architecture_decisions` directory, following the structure below.
## ADR Template
### Title
A concise title for the architectural decision.
### Status
The current status of the decision (e.g., Proposed, Accepted, Rejected, Deprecated).
### Context
A detailed description of the context in which the decision is being made. This should include any relevant background information, constraints, and considerations that influenced the decision.
### Decision
A clear statement of the architectural decision that has been made. This should be specific and actionable.
### Consequences
An analysis of the consequences of the decision, including any trade-offs, benefits, and potential drawbacks. This section should also discuss how the decision impacts other parts of the system and any future implications.
### Example ADR
```markdown
# ADR-001: Discord.js over Discord.py
**Status:** Accepted
**Context:** Node.js and Python both viable. Team has stronger Node.js experience.
**Decision:** Use Discord.js for the bot runtime.
**Consequences:** Faster development velocity; ecosystem rich with community plugins (command handling, modals, components).
```
### Guidelines for Writing ADRs
- Be clear and concise in your writing.
- Ensure that the context and consequences are well thought out and provide enough detail for future reference.
- Use a consistent format for all ADRs to maintain readability and organization.
- Regularly review and update ADRs as the project evolves and new information becomes available.
- Encourage team members to contribute to ADRs and discuss architectural decisions openly to foster collaboration and shared understanding.