commit 77e43a6a38203c02f205b95cc5f1b63974221b50 Author: zwitschi Date: Sun May 17 15:50:43 2026 +0200 Add initial project structure, including README, CONTRIBUTING, and documentation files - 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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4a28f99 --- /dev/null +++ b/.gitignore @@ -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/ \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..250b1a2 --- /dev/null +++ b/CONTRIBUTING.md @@ -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` 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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..6e31352 --- /dev/null +++ b/README.md @@ -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. diff --git a/docs/01_introduction_and_goals.md b/docs/01_introduction_and_goals.md new file mode 100644 index 0000000..3639d7d --- /dev/null +++ b/docs/01_introduction_and_goals.md @@ -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 | diff --git a/docs/02_architecture_constraints.md b/docs/02_architecture_constraints.md new file mode 100644 index 0000000..b6a2be8 --- /dev/null +++ b/docs/02_architecture_constraints.md @@ -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 diff --git a/docs/03_context_and_scope.md b/docs/03_context_and_scope.md new file mode 100644 index 0000000..eb0d6cd --- /dev/null +++ b/docs/03_context_and_scope.md @@ -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. diff --git a/docs/04_solution_strategy.md b/docs/04_solution_strategy.md new file mode 100644 index 0000000..f2d1dec --- /dev/null +++ b/docs/04_solution_strategy.md @@ -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 diff --git a/docs/05_building_block_view.md b/docs/05_building_block_view.md new file mode 100644 index 0000000..b7ed962 --- /dev/null +++ b/docs/05_building_block_view.md @@ -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 | diff --git a/docs/06_runtime_view.md b/docs/06_runtime_view.md new file mode 100644 index 0000000..dde9863 --- /dev/null +++ b/docs/06_runtime_view.md @@ -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 diff --git a/docs/07_deployment_view.md b/docs/07_deployment_view.md new file mode 100644 index 0000000..f32f3bd --- /dev/null +++ b/docs/07_deployment_view.md @@ -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 | diff --git a/docs/08_concepts.md b/docs/08_concepts.md new file mode 100644 index 0000000..3938df6 --- /dev/null +++ b/docs/08_concepts.md @@ -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` pattern +- Database table names: snake_case, plural +- PRs require passing lint + tests before merge diff --git a/docs/09_architecture_decisions.md b/docs/09_architecture_decisions.md new file mode 100644 index 0000000..473adf1 --- /dev/null +++ b/docs/09_architecture_decisions.md @@ -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. diff --git a/docs/10_quality_requirements.md b/docs/10_quality_requirements.md new file mode 100644 index 0000000..5f8874d --- /dev/null +++ b/docs/10_quality_requirements.md @@ -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). + +## 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 | diff --git a/docs/11_technical_risks.md b/docs/11_technical_risks.md new file mode 100644 index 0000000..d6f67af --- /dev/null +++ b/docs/11_technical_risks.md @@ -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 | diff --git a/docs/12_glossary.md b/docs/12_glossary.md new file mode 100644 index 0000000..2fbf8bd --- /dev/null +++ b/docs/12_glossary.md @@ -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 | diff --git a/docs/templates/ADR.md b/docs/templates/ADR.md new file mode 100644 index 0000000..1ddf0cb --- /dev/null +++ b/docs/templates/ADR.md @@ -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.