GmRelayBot/docs/superpowers/specs/2026-04-28-telegram-mini-app-dashboard-design.md

Telegram Mini App Dashboard Design

Goal

Issue #17 adds a Telegram Mini App dashboard as the mobile entry point for the existing Web Dashboard. Owner and co-GM users must be able to open the dashboard from Telegram, pass server-side Telegram WebApp initData validation, and manage only their own groups.

Scope

• Add Mini App authentication using Telegram WebApp initData.
• Add a /miniapp entry page that signs the user into the existing cookie auth flow, then opens the regular dashboard UI in mobile-first mode.
• Reuse AuthorizedSessionService, SessionService, and existing Blazor pages for groups, sessions, templates, waitlist promotion, edit forms, and bulk batch operations.
• Add bot entry points: a Mini App button in /start and a configurable default menu button when Telegram:MiniAppUrl is set.
• Update README, wiki, deployment config, and visible version strings to 1.9.0.

Architecture

The Mini App is not a second dashboard implementation. It is a Telegram-authenticated entrance into the existing Blazor dashboard. This keeps authorization, domain operations, Telegram message synchronization, and Web Dashboard behavior in one place.

TelegramAuthService gains a second verification method for WebApp initData. The server accepts the raw URL-encoded init payload at /auth/telegram-webapp, verifies the Telegram HMAC with the bot token, extracts the user id/name from the embedded user JSON, and issues the same auth cookie as the login widget endpoint.

/miniapp loads telegram-web-app.js, posts window.Telegram.WebApp.initData to the server endpoint, expands the WebApp viewport, and redirects to /. If a user opens /miniapp outside Telegram, the page shows the regular login fallback.

Data Flow

1. User opens the Mini App from the bot menu button or /start inline button.
2. Telegram injects initData into the WebApp JavaScript API.
3. /miniapp posts { initData } to /auth/telegram-webapp.
4. The server verifies the WebApp signature and expiry.
5. The server creates the same claims used by Telegram Login Widget.
6. Existing Blazor pages load groups through AuthorizedSessionService.
7. Any edit, waitlist, template, or batch action still goes through existing services and keeps Telegram messages synchronized.

Error Handling

• Missing or invalid init data returns 401 and leaves the user on the Mini App page.
• Expired auth data is rejected with the same 24-hour window used by the Login Widget.
• A verified Telegram user with no owner/co-GM groups sees the existing empty dashboard state.
• Direct navigation to a foreign group/session still redirects to /access-denied through existing authorization checks.

Testing

• Unit tests cover valid and invalid WebApp initData.
• File-level regression tests ensure /miniapp, /auth/telegram-webapp, Telegram WebApp script loading, bot Mini App button, menu button setup, and mobile Mini App CSS hooks remain present.
• Existing AuthorizedSessionServiceTests continue covering owner/co-GM access behavior.