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

feat: update documentation for architecture, runtime scenarios, and deployment strategies

Browse Source
This commit is contained in:
zwitschi
2026-05-17 16:54:00 +02:00
parent a402c7b0bb
commit 168f4ea13c
5 changed files with 176 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/06_runtime_view.md
+36 -21
View File
@@ -1,28 +1,43 @@
# Runtime View
## Scenario: User Signs Up for Open Mic
## Scenario: `/sign-up join` to Stage Queue
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
1. User invokes `/sign-up join`.
2. Command handler validates guild/context and required permissions.
3. Tour schedule engine appends user to guild queue if not already present.
4. Engine returns queue position and current queue snapshot.
5. Bot replies ephemerally with confirmation and position.
6. If configured, queue announcement message is sent to target channel.
## Scenario: Content Auto-Post
## Scenario: Advance Next Performer
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
1. Moderator invokes `/sign-up next`.
2. Tour schedule engine pops head of FIFO queue.
3. If stage channel integration is enabled, bot resolves member and promotes stage speaker.
4. Confirmation response includes promoted user and remaining queue length.
5. Optional announcement is sent to configured channel.
## Scenario: Admin Updates Bot Restart
## Scenario: Mileage Award on Interaction
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
1. Discord interaction event reaches runtime handler.
2. Bot resolves guild/member context and chooses mileage event type.
3. Mileage engine calculates points from configured event map.
4. Transaction persists event row and upserts total user mileage.
5. Role-tier thresholds are evaluated and missing roles are granted.
6. Runtime stores an engagement snapshot in configuration DB for dashboard consumption.
## Scenario: Dashboard OAuth Connect
1. Browser redirects user to Discord OAuth authorize URL.
2. Dashboard callback receives authorization code.
3. Dashboard posts code to `POST /admin/oauth/discord/exchange`.
4. OAuth bridge exchanges code for Discord token, fetches user, creates local session.
5. API returns `sessionId`; dashboard fetches session details from `/admin/oauth/session/:sessionId`.
6. Optional backend sync call propagates session to openmicodyssey.com.
## Scenario: Graceful Shutdown
1. Process receives SIGINT/SIGTERM.
2. Runtime stops HTTP server and Discord client.
3. Service tear-down closes DB pools and cancels dailies intervals.
4. Process exits with clean status after shutdown promises resolve.