One Bot, One Pod, One Problem at a Time

Chat platform providing distribution, auth, push, and the bot runtime.

• Telegram Bot API
  https://core.telegram.org/bots/api
  Core reference for messages, updates, webhooks, and bot configuration.

Pull-based update delivery — no inbound traffic, no TLS, single-replica only.

• getUpdates
  https://core.telegram.org/bots/api#getupdates
  Long-polling method used in the initial single-worker architecture.

Push-based update delivery that enables multiple bot worker replicas.

• setWebhook
  https://core.telegram.org/bots/api#setwebhook
  Register an HTTPS endpoint for Telegram to push updates to.
• Getting Updates
  https://core.telegram.org/bots/api#getting-updates
  Comparison of polling and webhook delivery modes.

Four-layer defense: firewall, ingress, IP check, and request signature verification.

• Webhook Secret Token
  https://core.telegram.org/bots/api#setwebhook
  Application-level signature check via the secret_token parameter.
• Telegram IP Ranges
  https://core.telegram.org/bots/webhooks
  Official IP ranges for firewall and ingress allowlisting.

Stateless worker handling Telegram updates, sessions, and outbound API calls.

• Go
  https://go.dev/doc/
  Language used for the Telegram bot worker service.

Internal PHP API for persisting users, courses, and session state.

• Symfony
  https://symfony.com/doc/current/index.html
  PHP framework backing the data storage layer.

Primary relational store and source of truth for all persistent data.

• PostgreSQL Documentation
  https://www.postgresql.org/docs/
  Database engine used by the Symfony storage API.

Container orchestration for multi-replica bot workers with autoscaling and rolling updates.

• Horizontal Pod Autoscaler
  https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/
  Per-bot replica scaling configured via Helm values.
• Pod Disruption Budgets
  https://kubernetes.io/docs/tasks/run-application/configure-pdb/
  Keep at least one replica available during node churn.
• Namespaces
  https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/
  One namespace per language bot for isolation.

Web UI embedded in Telegram for progress, flashcards, profile, and settings.

• Telegram Mini Apps
  https://core.telegram.org/bots/webapps
  Web views opened inside Telegram's in-app browser.
• Validating initData
  https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app
  Verify user identity from the URL fragment signed by the bot secret.

Public API layer between the mini-app frontend and the internal storage API.

• BFF Pattern
  https://samnewman.io/patterns/architectural/bff/
  Filters and aggregates internal data before exposing it to the frontend.

Outbound-only tunnel connecting an external BFF perimeter back to the cluster.

• Cloudflare Tunnel
  https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/
  cloudflared deployment with publication routes — no public ingress for the API.
• Cloudflare Access Service Tokens
  https://developers.cloudflare.com/cloudflare-one/identity/service-tokens/
  Machine-to-machine auth for BFF → internal API calls.

Shared session store, write buffer, and global rate-limit counters across replicas.

• Redis
  https://redis.io/docs/
  In-memory store replacing per-pod session state.
• Redis Persistence
  https://redis.io/docs/management/persistence/
  RDB snapshots as a safety net; Postgres remains authoritative.

Outbound API proxy with global counters — one ceiling across all replicas.

• API Gateway Pattern
  https://microservices.io/patterns/apigateway.html
  Proxies AI vendor requests and tracks token usage centrally.
• OpenAI Rate Limits
  https://platform.openai.com/docs/guides/rate-limits
  Primary external rate ceiling enforced by the controller.
• Google Gemini Rate Limits
  https://ai.google.dev/gemini-api/docs/rate-limits
  Second AI vendor with per-account quotas.

Multi-window burn-rate alerts on webhook ack latency and reply success rate.

• Google SRE — Alerting on SLOs
  https://sre.google/workbook/alerting-on-slos/
  Fast burn pages on-call; slow burn queues for next business day.
• Prometheus Burn Rate Alerting
  https://prometheus.io/docs/practices/alerting/#multi-window-multi-burn-rate-alerts
  Implementation reference for multi-window SLO alerts.

Multi-city, multi-ISP headless browser checks verifying full mini-app render.

• Playwright
  https://playwright.dev/
  Headless browser probes that verify every sub-request returns 2xx.

One chart, one deployment per language bot with per-bot values and secrets.

• Helm
  https://helm.sh/docs/
  Kubernetes package manager for bot deployments.
• Helm Values Files
  https://helm.sh/docs/chart_template_guide/values_files/
  Per-language config: replicas, HPA, feature flags, env vars.

Encrypted secrets committed to the helm-charts repo, decrypted at deploy time.

• Mozilla SOPS
  https://github.com/getsops/sops
  Encrypt and decrypt YAML secrets in git.
• age
  https://github.com/FiloSottile/age
  Encryption backend used by SOPS — the only secret kept outside the repo.

Scheduled notification delivery as a separate binary, outside the bot worker.

• Kubernetes CronJob
  https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/
  Replaced in-process Go tickers for push reminders.