Yupland Academy: building a Telegram Mini App inside Yupland

Summary: Yupland Academy is a game-like Telegram Mini App within the Yupland world. I built it to introduce people to Yupland through learning modules and quests, with PvP modes available in the same app. This case covers the product and the engineering work that took me the longest: capturing and validating Telegram initData.

Yupland is the gaming ecosystem and world that includes Yupland Academy. I built the Academy as a Telegram Mini App where people can learn about Yupland through modules and quests; PvP modes are available in the same app. I made the TMA on my own, from the first idea to its current state.

The app pairs a learning route with quests. PvP modes sit alongside them. The home screen shows a learner's progress, XP, level, badge count, and a way to continue learning. The bottom bar links to PvP and quests, plus other app sections.

Learning progress at a glance

The supplied home-screen capture shows one profile state: 504 XP, level 6, one badge, 1 of 42 modules, and 2% total progress. These values come from the screenshot, not from all users.

The learning area is presented as a roadmap. A learner can see their progress and return to the next step from the home screen.

The home screen shows progress, XP, level, and a shortcut to continue learning. The interface text is in Russian.

Quests connect the content and the games

The quest screen points to different parts of Yupland. "Yupland News," "Game Announcements," and "Yupland Bazaar" each show a 10 XP reward. Their descriptions point learners to news and events. They also introduce game mechanics and the marketplace for trading or finding artifacts.

Other visible quests are tied to PvP: play a first duel for 15 XP, play a match with a Duplo stake for 25 XP, and win Yupland Battle for 30 XP. The quest list rewards both exploring the world and playing.

Quests that point to the news, game announcements, and bazaar sections. The interface text is in Russian.

PvP quests and their displayed XP rewards. The interface text is in Russian.

PvP is a distinct part of the academy

The PvP hub shows tournaments with a 60/30/10 prize split, Yupland Battle between six schools, invitation duels, and Quiz Battle. Its game catalogue includes chess, 8×8 Reversi, 10×10 Sea Battle, Four in a Row, and Hex. Chess is marked as available; the other cards are marked as new.

PvP appears beside the learning route and quests in the main navigation. The screens show which modes are part of Yupland Academy.

The PvP section shows tournaments and cards for game modes. The interface text is in Russian.

The catalogue marks chess as available and the other cards as new. The interface text is in Russian.

What is Yupland?

Yupland is the gaming world that contains Yupland Academy. I built the Academy as one way to get to know Yupland. People can follow modules or quests, then open the game modes available in the Mini App.

Learning, XP progression, and PvP sit side by side in the Academy. They connect the lessons and activities to the same Yupland world.

The hardest part was Telegram initData

The work that took me longest was handling the data Telegram passes to a Mini App at launch. The client has to capture it, send it to the server, and the server has to validate its signature. Telegram warns that initDataUnsafe should not be trusted; the original initData string must be validated on the server (Telegram documentation).

The initData path from capture and transfer to signature validation before parsing user data.

I had to account for several edge cases. The project history shows repeated work on initData: some clients could send a double-encoded value, the Telegram.WebApp object could appear later, the page URL could change, and after a Mini App relaunch the live object or launch URL might no longer be available.

I added several ways for the client to recover the launch data. It first saves tgWebAppData from the URL to sessionStorage, before other code can clean the address. When the app needs the value, it checks that saved copy, then Telegram.WebApp.initData, the URL parameters, and finally a durable copy in localStorage.

For TMA requests, the client sends initData in the X-Telegram-Init-Data header. The Hono server handles the double-encoding case, rebuilds the string Telegram signed, and checks its HMAC-SHA-256 signature using the bot token. This helps confirm that the launch data has not been changed. The server parses the user data only after validation succeeds.

Git history shows that I revisited this area several times between May 8 and May 30, 2026: the iterations covered data delivery, startup timing, and keeping the data across relaunches. Users rarely see this work, although it determines whether the Mini App can identify them reliably.

Project stack

The client uses React 19 and TypeScript, with Vite for builds and Zustand for client state. The server uses Hono and tRPC; data is stored in PostgreSQL through Drizzle ORM. In the TMA flow, the client captures and forwards launch data, and the server checks its signature before parsing the user data.

My technical takeaway is to test the complete initData lifecycle: the first launch, delayed Telegram bridge initialization, URL changes, app relaunches, and server-side signature validation. One successful login isn't enough.

I see Yupland Academy as a game-like entry point into the Yupland world. It ties learning about the world to progress and quests, with PvP available in the same app.

In brief

• What is Yupland? The gaming world that contains Yupland Academy and related game mechanics.
• What is Yupland Academy? A Telegram Mini App I built as an entry point into Yupland, connecting learning about its world with quests, progress, and PvP.
• What does the current interface show? A 42-module learning route, XP and levels, reward quests, and PvP modes.
• What took the most engineering time? Capturing and preserving Telegram initData, handling its encoding, and validating its signature on the server.