mirror of
https://github.com/tiennm99/openai-status-bot.git
synced 2026-10-14 20:17:37 +00:00
52 lines
2.9 KiB
Markdown
52 lines
2.9 KiB
Markdown
# System Architecture
|
|
|
|
## Overview
|
|
|
|
`openai-status-bot` is one Go process with two loops:
|
|
|
|
- Telegram long polling loop for user commands.
|
|
- OpenAI status polling loop, default every minute.
|
|
|
|
Redis stores subscribers, subscription settings, polling checkpoints, delivery retry state, and the Telegram update offset.
|
|
|
|
## Data Flow
|
|
|
|
1. User sends `/start` in Telegram.
|
|
2. Bot stores chat ID, optional topic thread ID, and default subscription settings in Redis.
|
|
3. Users can adjust settings with `/subscribe` and inspect them with `/info`.
|
|
4. Poller fetches OpenAI status JSON:
|
|
- `GET /api/v2/summary.json`
|
|
- `GET /api/v2/incidents.json`
|
|
5. Poller compares fetched state with Redis checkpoints and builds notification events without mutating checkpoints.
|
|
6. Events are sent to eligible subscribers, respecting incident/component preferences and component ID filters.
|
|
7. Component and incident checkpoints are written only after delivery succeeds or terminal subscriber failures are removed.
|
|
|
|
## Redis Keys
|
|
|
|
| Key | Type | Purpose |
|
|
|-----|------|---------|
|
|
| `openai-status:subscribers` | set | Telegram chat or topic subscribers |
|
|
| `openai-status:subscriber-settings` | hash | Subscription types and component ID filters by subscriber key |
|
|
| `openai-status:component-statuses` | hash | Last seen component status by component ID |
|
|
| `openai-status:incident-updates` | set | Legacy seen incident update IDs, retained as write-through metadata; version hash is authoritative |
|
|
| `openai-status:incident-update-versions` | hash | Seen incident update version by update ID |
|
|
| `openai-status:event-delivery:<hash>` | set | Temporary per-event subscriber delivery state for retry isolation |
|
|
| `openai-status:telegram-offset` | string | Last processed Telegram update offset |
|
|
| `openai-status:initialized` | string | Baseline seed marker |
|
|
|
|
Subscriber set members are `chatID` or `chatID:threadID`. Missing settings default to incident and component notifications for backward compatibility with older Redis state.
|
|
|
|
## Runtime
|
|
|
|
The service uses Telegram `getUpdates`, so it does not need a public webhook URL. On startup it calls `deleteWebhook` before long polling, which allows migration from a webhook-based deployment using the same bot token. Redis is configured with `REDIS_URL`. Docker Compose starts Redis and the bot.
|
|
|
|
## Failure Behavior
|
|
|
|
- First successful poll seeds state without notification.
|
|
- OpenAI fetch failures are logged and retried on the next interval.
|
|
- Retryable Telegram failures do not advance component or incident checkpoints.
|
|
- Successful per-subscriber deliveries are tracked temporarily, so retrying one failed subscriber does not resend to already-delivered subscribers.
|
|
- Telegram 403 and selected terminal 400 errors remove the unreachable subscriber, then delivery continues.
|
|
- Malformed subscriber keys are removed from Redis and surfaced as an error for the current poll instead of being skipped silently.
|
|
- Redis connection failure at startup exits the process.
|