What the client receives
The Telegram Mini App opens from a familiar bot but behaves like a dedicated application. Coaches invite clients, build programs and review activity. Clients log workouts, nutrition and progress. The backend validates Telegram signatures and authorization on every action. It is a practical format for testing a service without an App Store installation.
Telegram authentication flow
The WebApp receives signed initData and sends it to the API. The server verifies the HMAC and data age before resolving the user role. A Telegram ID supplied by the browser without a signature is not authentication.
The frontend uses the role for routing and UI, while the backend repeats ownership checks. Replacing an ID manually cannot expose another client profile.
Telegram /start
→ open WebApp
→ Authorization: tma <initData>
→ GET /api/v2/auth/me
→ coach or client workspaceWhy the project outgrew Google Sheets
The spreadsheet helped validate the first workflow. Later, one coach became related to multiple clients, a program to days and exercises, and an exercise to planned and completed sets. Concurrent writes and access rules became part of the product.
After the first workflow was validated, spreadsheet storage remained part of the early version while the working data model moved to SQLAlchemy. SQLite is enough for local development; PostgreSQL is a better fit for concurrent users.
What had to be fixed
- 01The coach overview ran several SQL queries per client. It was replaced with batch queries, while expensive metrics moved to the detail view.
- 02The temporary API address changed whenever the tunnel restarted. A stable version needs a permanent domain so the frontend does not require a rebuild after every restart.
- 03The test environment enabled simplified authentication while a manual call returned 401. We separated the modes explicitly instead of weakening signature validation.
- 04The pricing screen existed before payments were wired. A complete payment flow needs invoice creation, Telegram confirmation and protection against processing the same event twice.
What a permanent launch requires
- 01Move working data to PostgreSQL and apply schema changes through migrations.
- 02Run the API and Telegram bot as separate managed services with automatic restart.
- 03Attach a stable API domain, restrict CORS and add a service health check.
- 04Test real Telegram login and verify coach and client permissions with test accounts.
- 05Verify backup and restore before onboarding real users.