From 29b6c7e4d8aa6cf420fc6f16e76db547559fb8d0 Mon Sep 17 00:00:00 2001 From: Ilia Denisov Date: Wed, 24 Jun 2026 12:19:50 +0200 Subject: [PATCH] docs(telegram): document the Mini App embedding enhancements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Record the current state in ARCHITECTURE and FUNCTIONAL (+ _ru mirror): inside the Mini App the client tracks Telegram's live theme switch, fits the full device safe-area, exposes a native Settings button into the in-app settings, and syncs the device-independent display prefs (theme, reduce-motion, board labels — not the interface language) across the user's Telegram devices via CloudStorage; the validator denies a bot user (is_bot) before provisioning an account. --- docs/ARCHITECTURE.md | 12 +++++++++--- docs/FUNCTIONAL.md | 8 ++++++-- docs/FUNCTIONAL_ru.md | 10 ++++++++-- 3 files changed, 23 insertions(+), 7 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0079a17..2c0a3f4 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -42,7 +42,12 @@ Three executables plus per-platform side-services: users, a weighted fair rotation — §10), and a client **board-style** setting (bonus-label mode). The visual/interaction design system is documented in - [`UI_DESIGN.md`](UI_DESIGN.md). + [`UI_DESIGN.md`](UI_DESIGN.md). Inside the Telegram Mini App the client additionally + tracks Telegram's live theme switch (`themeChanged`), fits the full device safe-area + insets (the bottom/home-indicator strip taking the bottom bar's colour), exposes + Telegram's native **Settings** button into the in-app settings, and syncs the + device-independent display preferences (theme, reduce-motion, board labels — **not** the + interface language) across the user's Telegram devices via **CloudStorage**. - **`platform/telegram`** — the Telegram side-service (module `scrabble/platform/telegram`), split into two binaries that share the bot token (**one bot**, one optional game channel, §3): @@ -152,7 +157,8 @@ arrive from a platform rather than completing a mandatory registration). - **Single bot.** The platform side-service runs **one bot** (one token + one optional game channel), split into a home **validator** and a remote **bot** that share the token. `ValidateInitData` (the validator) validates `initData` against that single - token and returns only the Telegram user identity — there is no per-bot "service + token, **rejects a bot user** (the signed `is_bot` flag), and returns only the Telegram + user identity — there is no per-bot "service language" and no supported-languages set on the wire. The bot's chat messages and out-of-app push are rendered in the recipient's **interface language** (`preferred_language`, en/ru), not in @@ -972,7 +978,7 @@ edits take effect on the next `profile.get` (open/reconnect/foreground), not mid | Concern | Enforced by | | --- | --- | | Public rate limiting / anti-abuse | gateway (per-IP public/email/admin classes, per-user authenticated class; a request body cap of `GATEWAY_MAX_BODY_BYTES`; rejections are metered, summarised to the backend and surfaced in the admin console with a conservative reversible auto-flag — §11). In prod a **temporary IP ban** (`GATEWAY_ABUSE_BAN_ENABLED`) blocks an IP that sustains rejections or trips a **honeypot** decoy path / **honeytoken**, refused with 429 before any work; operators lift bans from the console. Off in the shared-NAT test contour, where the client IP is not real (§11) | -| Telegram initData validation (bot-token HMAC) | the Telegram **validator**; the gateway delegates it over gRPC, so the bot token (the HMAC secret) lives only in the validator and the bot, never in the gateway | +| Telegram initData validation (bot-token HMAC) | the Telegram **validator**; the gateway delegates it over gRPC, so the bot token (the HMAC secret) lives only in the validator and the bot, never in the gateway. The validator also **rejects a bot principal** (the signed `is_bot` flag) before any account is provisioned | | Session minting; email-code / guest validation | gateway (with backend) | | Session → `user_id` resolution, `X-User-ID` injection | gateway | | Authorisation, ownership, state transitions | backend (`X-User-ID` is the sole identity input) | diff --git a/docs/FUNCTIONAL.md b/docs/FUNCTIONAL.md index c21c38e..4b242b0 100644 --- a/docs/FUNCTIONAL.md +++ b/docs/FUNCTIONAL.md @@ -30,7 +30,8 @@ A player arrives from a platform (Telegram first), via email login, or as an ephemeral guest. The gateway validates the credential once and mints a thin session token; the backend resolves it to an internal `user_id`. A **Telegram Mini App** launch authenticates from the platform's signed `initData`, themes the UI to -the Telegram colours, and — on first contact — seeds the new account's interface +the Telegram colours (re-theming live if you switch Telegram's light/dark mode) and fits +the device safe-area, and — on first contact — seeds the new account's interface language from the Telegram client. If a launch cannot reach the backend (for example during a deployment), the Mini App retries quietly and then shows a small "couldn't load" screen with a **Retry** button, rather than dropping to the web sign-in, which has no place inside Telegram. @@ -249,7 +250,10 @@ is first created — so robot games are timed correctly before you ever open thi daily away window (on a 10-minute grid, at most 12 hours, wrapping midnight) and the block toggles. The profile form is edited inline (no separate edit mode). Linking an email or Telegram and merging accounts are covered under "Accounts, linking & -merge". +merge". Inside the Telegram Mini App, Telegram's own ⋮ menu also offers a **Settings** +entry that opens this screen, and your display preferences (theme, board-label style and +reduce-motion — not the interface language, which follows your account) sync across your +Telegram devices. **Preferences (which variants you can be matched into).** A profile setting picks the game variants — Erudite, Russian Scrabble and English Scrabble, shown **Erudite-first** — you allow diff --git a/docs/FUNCTIONAL_ru.md b/docs/FUNCTIONAL_ru.md index c611b7a..f06af8c 100644 --- a/docs/FUNCTIONAL_ru.md +++ b/docs/FUNCTIONAL_ru.md @@ -31,7 +31,9 @@ top-1 подсказку, безлимитную проверку слова с эфемерный гость. Gateway один раз валидирует доступ и выдаёт тонкий session-токен; backend сопоставляет его с внутренним `user_id`. Запуск **Telegram Mini App** авторизует по подписанным `initData` платформы, перекрашивает интерфейс -в цвета Telegram и — при первом контакте — задаёт язык интерфейса нового аккаунта по +в цвета Telegram (перекрашиваясь вживую при смене светлой/тёмной темы Telegram) и +вписывается в безопасные зоны экрана (safe-area), а — при первом контакте — задаёт язык +интерфейса нового аккаунта по языку Telegram-клиента. Если запуск не может достучаться до бэкенда (например, во время деплоя), Mini App тихо повторяет попытки, а затем показывает небольшой экран «не удалось загрузить» с кнопкой **Повторить**, вместо того чтобы сбрасывать на веб-вход, которому внутри @@ -255,7 +257,11 @@ UTC; при создании аккаунта она подставляется игры с роботом таймились правильно ещё до открытия этой формы), суточного окна отсутствия (away; сетка по 10 минут, не более 12 часов, с переходом через полночь) и переключателей блокировок. Форма профиля редактируется сразу (без отдельного режима редактирования). Привязка email и Telegram, а также -слияние аккаунтов вынесены в раздел «Аккаунты, привязка и слияние». +слияние аккаунтов вынесены в раздел «Аккаунты, привязка и слияние». Внутри Telegram +Mini App пункт **Settings** в системном меню «⋮» Telegram также открывает этот экран, а +ваши настройки отображения (тема, стиль подписей клеток и reduce-motion — кроме языка +интерфейса, который следует за аккаунтом) синхронизируются между вашими устройствами в +Telegram. **Предпочтения (в какие варианты тебя можно подбирать).** Настройка профиля задаёт варианты игры — Эрудит, русский Scrabble и английский Scrabble, показанные **сначала Эрудит**, — в