mirror of
https://github.com/tiennm99/openai-status-bot.git
synced 2026-07-15 14:22:03 +00:00
57 lines
4.2 KiB
Markdown
57 lines
4.2 KiB
Markdown
# System Architecture
|
|
|
|
## Overview
|
|
|
|
`openai-status-bot` is one Go process with two runtimes:
|
|
|
|
- `go-telegram/bot` long-poll runtime for Telegram user commands.
|
|
- OpenAI status polling loop, default every minute.
|
|
|
|
MongoDB stores subscribers, subscription settings, polling checkpoints, delivery retry state, and the Telegram restart offset.
|
|
|
|
## Data Flow
|
|
|
|
1. User sends `/start` in Telegram.
|
|
2. The Telegram framework receives a message update and dispatches it to the command handler.
|
|
3. Bot stores chat ID, optional topic thread ID, and default subscription settings in MongoDB.
|
|
4. Users can adjust settings with `/subscribe` and inspect them with `/info`.
|
|
5. Poller fetches OpenAI status JSON:
|
|
- `GET https://status.openai.com/api/v2/summary.json`
|
|
- `GET https://status.openai.com/api/v2/incidents.json`
|
|
6. Poller compares fetched state with MongoDB checkpoints and builds notification events without mutating checkpoints.
|
|
7. Events are sent to eligible subscribers through the Telegram sender adapter, respecting incident/component preferences and component ID filters.
|
|
8. Component and incident checkpoints are written only after delivery succeeds or terminal subscriber failures are removed.
|
|
|
|
## MongoDB Collections
|
|
|
|
| Collection | Document ID | Fields | Purpose |
|
|
|-----------|------------|--------|---------|
|
|
| `subscribers` | `chatID` or `chatID:threadID` | chatID, threadID, types, components | Telegram chat or topic subscribers with subscription settings |
|
|
| `component_statuses` | component ID | status | Last seen component status by component ID |
|
|
| `pending_component_events` | component ID | — | Component changes saved before fan-out so retryable delivery failures can be resumed |
|
|
| `incident_update_versions` | update ID | version | Seen incident update version by update ID |
|
|
| `delivery` | `eventKey\|subscriber` | eventKey, subscriber, expiresAt (TTL 7 days) | Temporary per-event subscriber delivery state for retry isolation |
|
|
| `meta` | `initialized` or `telegramOffset` | value | Baseline seed marker and next Telegram update offset to use on restart |
|
|
|
|
Subscriber document IDs are `chatID` or `chatID:threadID`. Each subscriber document includes subscription types and component ID filters as fields within the document.
|
|
|
|
## Runtime
|
|
|
|
The service uses Telegram `getUpdates` through `github.com/go-telegram/bot`, so it does not need a public webhook URL. On startup it starts a local health endpoint at `127.0.0.1:8080/healthz`, loads the stored `telegramOffset`, calls `deleteWebhook` before long polling, registers the Telegram command menu, and then starts the framework polling runtime. The framework is configured for message updates only, one worker, a single-update channel, and synchronous handlers so command side effects remain ordered.
|
|
|
|
`telegramOffset` stores the next update ID to resume from. Because `go-telegram/bot` stores the last seen update internally and sends `lastUpdateID + 1` to Telegram, startup passes `telegramOffset - 1` as the initial framework offset when a saved offset exists. The command handler saves `update.ID + 1` after every message update, including non-command messages.
|
|
|
|
MongoDB is configured with `MONGODB_URI` and `MONGODB_DATABASE` (default `openai_status_bot`). The OpenAI status source is fixed to `https://status.openai.com`. Docker Compose starts the bot connecting to a managed MongoDB Atlas cluster; there is no bundled local MongoDB service.
|
|
|
|
## Failure Behavior
|
|
|
|
- First successful poll seeds state without notification.
|
|
- OpenAI fetch failures are logged and retried on the next interval.
|
|
- Retryable Telegram send 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.
|
|
- Pending component events are stored before delivery and removed only after successful delivery or terminal subscriber cleanup.
|
|
- Telegram 403 and selected terminal 400 send errors remove the unreachable subscriber, then delivery continues.
|
|
- Telegram runtime errors are logged with the bot token redacted.
|
|
- Malformed subscriber document IDs are removed from MongoDB and surfaced as an error for the current poll instead of being skipped silently.
|
|
- MongoDB connection failure at startup exits the process.
|