omo-bot/docs/06_runtime_view.md

Runtime View

Scenario: /sign-up join to Stage Queue

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: Advance Next Performer

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: Mileage Award on Interaction

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.