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

Telegram Mini App Dashboard Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add a Telegram Mini App mobile dashboard that reuses the existing Web Dashboard and validates Telegram WebApp initData on the server.

Architecture: Extend TelegramAuthService for WebApp init data, add a /miniapp Blazor entry page plus /auth/telegram-webapp endpoint, and add bot entry points through an inline WebApp button and optional menu button setup. Existing application/domain services remain the only write path.

Tech Stack: .NET 10, Blazor Server, Telegram.Bot, xUnit, Dapper/Npgsql-backed existing services.

---

Task 1: Telegram WebApp Authentication

Files:

• Modify: src/GmRelay.Web/Services/TelegramAuthService.cs

• Modify: src/GmRelay.Web/Program.cs

• Test: tests/GmRelay.Bot.Tests/Web/TelegramAuthServiceTests.cs

• Write failing tests for valid WebApp initData, tampered hash, and expired auth date.

• Run dotnet test tests/GmRelay.Bot.Tests/GmRelay.Bot.Tests.csproj --filter TelegramAuthServiceTests.

• Implement WebApp HMAC verification using the Telegram WebAppData secret derivation.

• Add /auth/telegram-webapp endpoint that signs in using the same claims as /auth/telegram.

• Re-run the filtered tests.

Task 2: Mini App Entry Page

Files:

• Create: src/GmRelay.Web/Components/Pages/MiniApp.razor

• Modify: src/GmRelay.Web/Components/App.razor

• Modify: src/GmRelay.Web/wwwroot/app.css

• Test: tests/GmRelay.Bot.Tests/Web/MiniAppDashboardTests.cs

• Write failing tests that assert /miniapp, telegram-web-app.js, authenticateTelegramMiniApp, and Mini App CSS hooks exist.

• Run dotnet test tests/GmRelay.Bot.Tests/GmRelay.Bot.Tests.csproj --filter MiniAppDashboardTests.

• Implement /miniapp to post Telegram.WebApp.initData to /auth/telegram-webapp, expand/ready the Mini App, and show fallback login when opened outside Telegram.

• Add CSS for a mobile-first Mini App shell and compact dashboard spacing.

• Re-run the filtered tests.

Task 3: Bot Entry Points

Files:

• Create: src/GmRelay.Bot/Infrastructure/Telegram/TelegramMiniAppMenuButtonService.cs

• Modify: src/GmRelay.Bot/Infrastructure/Telegram/UpdateRouter.cs

• Modify: src/GmRelay.Bot/Program.cs

• Test: tests/GmRelay.Bot.Tests/Infrastructure/Telegram/TelegramMiniAppEntryPointTests.cs

• Write failing tests that assert /start exposes a WebApp button and startup registers the menu button service.

• Run dotnet test tests/GmRelay.Bot.Tests/GmRelay.Bot.Tests.csproj --filter TelegramMiniAppEntryPointTests.

• Add a configurable Telegram:MiniAppUrl entry point; when missing, keep existing command behavior.

• Add hosted service that calls SetChatMenuButton with MenuButtonWebApp only when the URL is configured.

• Re-run the filtered tests.

Task 4: Docs, Versions, and Release Prep

Files:

• Modify: Directory.Build.props

• Modify: compose.yaml

• Modify: .gitea/workflows/deploy.yml

• Modify: src/GmRelay.Web/wwwroot/app.css

• Modify: src/GmRelay.Web/Components/Layout/NavMenu.razor

• Modify: README.md

• Wiki: Home, Быстрый старт, Руководство ГМа, Развёртывание, Архитектура, Разработка

• Update project/container/workflow/UI versions to 1.9.0.

• Document TELEGRAM_MINI_APP_URL, BotFather /setmenubutton, /miniapp, and WebApp auth.

• Run dotnet test tests/GmRelay.Bot.Tests/GmRelay.Bot.Tests.csproj --collect:"XPlat Code Coverage".

• Run dotnet build GM-Relay.slnx -c Release.

• Commit, push, close issue #17, update wiki, create tag/release v1.9.0.