openai-status-bot/docs/system-architecture.md

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.