University Telegram Scheduler (M15)

Overview

A container-level topology for a small university scheduling service (max 8 accounts) that publishes events, homework, and reminders to a Telegram supergroup with topics. All communication is synchronous HTTP — there are no queues, so Telegram delivery failures are surfaced immediately rather than retried. The stack runs under docker-compose on a single appnet network, except the bot container, which uses the host network for outbound-only Telegram access.

Components

• Actors — Guest (read-only calendar), Student (JWT, homework marks), Admin (events, Telegram, attendance), Owner (user CRUD, hard limit of 8).
• Client — Browser SPA holding the JWT in localStorage.
• Application tier — frontend (React + Vite,
  → 5173), backend (FastAPI + SQLModel
  , the sole DB writer), worker (APScheduler, metrics on
  ).
• State — postgres:15 (events, users, homework completions, attendance marks, teacher profiles), an idle redis:7 instance, and the /uploads volume served as URL paths.
• Host network — bot (FastAPI
  ) wrapping the Telegram Bot API with IPv6 → IPv4 → DNS fallback.
• External — api.telegram.org and GitHub Actions CI (SCP + docker compose up).
• Observability — Prometheus, Grafana, cAdvisor, node/postgres/redis/blackbox exporters, Fluent Bit, and Loki.

Data Flow

The SPA proxies REST/JSON calls through the frontend to the backend, which is the only writer to Postgres and /uploads. Publishing an event stores it, then POSTs /send to the bot, which reads attachment bytes from the read-only /uploads mount and calls the Bot API, returning message_id for persistence. The worker polls the backend for due reminders, birthdays, and the Friday backup job. Prometheus scrapes every service; Fluent Bit ships container logs to Loki for Grafana correlation. If the bot is down, the backend returns 502 with no retry path.