Track 4: Telegram Mini App Tasks¶
Timeline: After Track 1 MVP, ~May-July 2026 Tasks: 45 Total Hours: ~160h (20 working days) Repos: backend-api, telegram-mini-app (new), champion-stats-hub (shared components) Dependencies: Track 1 MVP for health data; Track 3 optional for NFT badges Target: 100,000 mini app users -> 2,000 main app conversions Status tracking:
[ ]To Do |[~]In Progress |[x]Done
Branch Naming Convention¶
All branches: feature/T4-XXX-short-description
Progress¶
| Phase | Tasks | Hours | Done | % |
|---|---|---|---|---|
| A: Bot & Mini App Foundation | T4-001..008 | 24h | 0 | 0% |
| B: Health Challenges | T4-009..021 | 40h | 0 | 0% |
| C: TON Blockchain | T4-022..029 | 32h | 0 | 0% |
| D: Viral Growth Mechanics | T4-030..040 | 32h | 0 | 0% |
| E: Infrastructure & Polish | T4-041..045 | 18h | 0 | 0% |
| Total | 45 | ~160h | 0 | 0% |
New Repo: telegram-mini-app¶
- Stack: React + Vite + TypeScript + Telegram Web App SDK
- Hosting: Vercel or Cloudflare Pages (free tier)
- Shares: UI components and API types with champion-stats-hub where possible
Phase A: Bot & Mini App Foundation (24h)¶
| ID | Task | Repo | Branch | Status | Est. Hours | Done When |
|---|---|---|---|---|---|---|
| T4-001 | Create Telegram bot via BotFather — set name, description, commands, menu button | — | feature/T4-001-botfather-setup |
[ ] | 1h | Bot created with name, description, /start /help /challenges commands, and menu button configured |
| T4-002 | Bot webhook server — receive and handle Telegram updates | backend-api | feature/T4-002-bot-webhook-server |
[ ] | 4h | Webhook endpoint receives messages. Bot responds to /start, /help, /challenges. Validates Telegram signature |
| T4-003 | Create Telegram Web App (TWA) project — React + Vite + Telegram Web App SDK | telegram-mini-app | feature/T4-003-twa-project-scaffold |
[ ] | 4h | Project scaffolded with @vkruglikov/react-telegram-web-app or official SDK. Builds. Opens in Telegram |
| T4-004 | TWA authentication — validate initData from Telegram | backend-api + telegram-mini-app | feature/T4-004-twa-auth-initdata |
[ ] | 4h | Backend validates Telegram initData hash. Creates/links user account. Returns JWT for API calls |
| T4-005 | User profile sync — Telegram user -> Sellwyse account | backend-api | feature/T4-005-telegram-user-sync |
[ ] | 3h | On first open, create user from Telegram data (name, photo, language). Link to existing account if email matches |
| T4-006 | TWA navigation — bottom tabs: Challenges, Leaderboard, Profile, Rewards | telegram-mini-app | feature/T4-006-twa-tab-navigation |
[ ] | 4h | Tab bar navigation works. Each tab renders placeholder. Telegram back button handled |
| T4-007 | TWA theme integration — match Telegram color scheme | telegram-mini-app | feature/T4-007-twa-theme-integration |
[ ] | 2h | App uses Telegram theme variables (bg_color, text_color, button_color). Looks native in both light/dark Telegram themes |
| T4-008 | Deploy TWA — host on Vercel/Cloudflare, configure bot menu button URL | telegram-mini-app | feature/T4-008-twa-deploy |
[ ] | 2h | Mini app accessible via bot menu button. HTTPS. Fast load (<2s) |
Phase B: Health Challenges (40h)¶
| ID | Task | Repo | Branch | Status | Est. Hours | Done When |
|---|---|---|---|---|---|---|
| T4-009 | Challenge data model — create challenges table | backend-api | feature/T4-009-challenges-table |
[ ] | 3h | Table: id, title, description, type (steps/sleep/workout/custom), target_value, start_date, end_date, created_by, max_participants, reward_pool, status. Migration runs |
| T4-010 | POST /challenges — create challenge | backend-api | feature/T4-010-create-challenge-endpoint |
[ ] | 3h | Create challenge with type, target, dates. Validate dates are future. Return challenge with join link |
| T4-011 | GET /challenges — list active challenges | backend-api | feature/T4-011-list-challenges-endpoint |
[ ] | 2h | List active/upcoming challenges. Filter by type. Sort by start date. Include participant count |
| T4-012 | POST /challenges/{id}/join — join a challenge | backend-api | feature/T4-012-join-challenge-endpoint |
[ ] | 2h | User joins challenge. Check: not already joined, not full, not ended. Create participant record |
| T4-013 | Challenge progress tracking — update daily from health data | backend-api | feature/T4-013-challenge-progress-tracking |
[ ] | 4h | Background job: for each active challenge, calculate each participant's progress from health_metrics. Steps challenge = sum steps. Sleep challenge = avg sleep score |
| T4-014 | GET /challenges/{id}/leaderboard — real-time rankings | backend-api | feature/T4-014-challenge-leaderboard |
[ ] | 3h | Return ranked participants: position, name, avatar, progress, percentage of goal. Update every hour |
| T4-015 | Challenge completion detection and rewards | backend-api | feature/T4-015-challenge-completion |
[ ] | 3h | When challenge ends, determine winners. Mark challenge completed. Award rewards to winners |
| T4-016 | TWA challenge list screen — browse and join | telegram-mini-app | feature/T4-016-twa-challenge-list |
[ ] | 4h | List of challenges: title, type icon, progress bar, days remaining, participant count. Join button. Pull to refresh |
| T4-017 | TWA challenge detail screen — progress + leaderboard | telegram-mini-app | feature/T4-017-twa-challenge-detail |
[ ] | 4h | Show: challenge info, user's progress vs goal, leaderboard of participants, share button, days countdown |
| T4-018 | TWA create challenge — "Challenge a friend" flow | telegram-mini-app | feature/T4-018-twa-create-challenge |
[ ] | 4h | Create custom challenge: pick type, set target, invite friends via Telegram share. Deep link for joining |
| T4-019 | Share challenge results — generate shareable card | telegram-mini-app | feature/T4-019-share-challenge-results |
[ ] | 3h | On challenge complete, generate result card: rank, stats, Sellwyse branding. Share to Telegram chats |
| T4-020 | Daily challenge notification via bot | backend-api | feature/T4-020-daily-challenge-notification |
[ ] | 3h | Bot sends daily progress update to challenge participants: "Day 3/7: You've done 8,234 steps (82% of goal). Keep going!" |
| T4-021 | Weekly challenge templates — auto-create recurring challenges | backend-api | feature/T4-021-weekly-challenge-templates |
[ ] | 2h | System creates weekly challenges automatically: "10K Steps Challenge", "Sleep 8h Challenge". Always something to join |
Phase C: TON Blockchain Integration (32h)¶
| ID | Task | Repo | Branch | Status | Est. Hours | Done When |
|---|---|---|---|---|---|---|
| T4-022 | Research TON Connect 2.0 integration | research | feature/T4-022-ton-connect-research |
[ ] | 4h | Understand TON Connect flow, wallet connection, transaction signing. Document integration plan |
| T4-023 | TON Connect button in TWA — connect TON wallet | telegram-mini-app | feature/T4-023-ton-connect-button |
[ ] | 6h | "Connect Wallet" button opens TON Connect modal. User approves in Tonkeeper/other wallet. Wallet address stored |
| T4-024 | Display TON balance in mini app | telegram-mini-app | feature/T4-024-ton-balance-display |
[ ] | 3h | Profile shows TON balance. Fetched from TON RPC. Refresh on pull |
| T4-025 | TON reward distribution — send TON to challenge winners | backend-api | feature/T4-025-ton-reward-distribution |
[ ] | 6h | Backend sends TON to winner wallets via TON SDK. Transaction built, signed by server keypair, broadcast. Confirmation tracked |
| T4-026 | TON transaction verification | backend-api | feature/T4-026-ton-tx-verification |
[ ] | 3h | Verify TON transfers on-chain. Check: correct amount, correct recipient, finalized. Update reward status |
| T4-027 | Reward history in mini app | telegram-mini-app | feature/T4-027-reward-history-ui |
[ ] | 3h | Rewards tab shows: earned TON, pending rewards, claimed rewards, transaction links |
| T4-028 | TON keypair management — secure server wallet | backend-api | feature/T4-028-ton-keypair-management |
[ ] | 3h | Server TON wallet keypair in AWS Secrets Manager. Fund with minimal TON for gas. Monitor balance |
| T4-029 | TON testnet testing — full reward flow | backend-api + telegram-mini-app | feature/T4-029-ton-testnet-testing |
[ ] | 4h | Test on TON testnet: create challenge -> complete -> claim reward -> verify on-chain. Test TON from faucet |
Phase D: Viral Growth Mechanics (32h)¶
| ID | Task | Repo | Branch | Status | Est. Hours | Done When |
|---|---|---|---|---|---|---|
| T4-030 | Invite system — unique referral links per user | backend-api + telegram-mini-app | feature/T4-030-invite-referral-links |
[ ] | 4h | Each user gets unique invite link. Track: who invited whom, conversion count. Display invite stats |
| T4-031 | Referral rewards — earn TON for each friend who joins | backend-api | feature/T4-031-referral-rewards |
[ ] | 3h | When referred friend joins a challenge, referrer earns bonus. Configurable: flat amount or percentage |
| T4-032 | "Challenge a Friend" Telegram share button | telegram-mini-app | feature/T4-032-challenge-friend-share |
[ ] | 3h | Share button opens Telegram share picker. Pre-filled message with challenge link. Tracked for attribution |
| T4-033 | Group challenges — create challenge in Telegram group | backend-api + telegram-mini-app | feature/T4-033-group-challenges |
[ ] | 4h | Bot can be added to groups. /challenge command creates group challenge. All group members can join |
| T4-034 | Streak system — daily login + challenge participation streaks | backend-api | feature/T4-034-streak-system |
[ ] | 3h | Track daily streaks. 7-day streak = bonus reward. 30-day streak = bigger bonus. Streak broken = start over |
| T4-035 | Streak display and notifications | telegram-mini-app + backend-api | feature/T4-035-streak-display-notify |
[ ] | 3h | Profile shows streak count + fire icon. Bot sends "Don't break your streak!" reminder at 8pm if no activity |
| T4-036 | Mini app onboarding — first-time user flow | telegram-mini-app | feature/T4-036-onboarding-flow |
[ ] | 3h | First open: welcome screen -> explain challenges -> connect health data -> join first challenge. Under 30 seconds |
| T4-037 | Deep link to main Sellwyse app | telegram-mini-app | feature/T4-037-deep-link-main-app |
[ ] | 2h | "Unlock full features" banner links to App Store / Play Store. Track conversion from mini app to full app |
| T4-038 | User segment analytics — track funnel | backend-api | feature/T4-038-user-funnel-analytics |
[ ] | 3h | Track: mini app opens, challenge joins, challenge completions, wallet connects, main app conversions. Daily metrics |
| T4-039 | Push re-engagement — bot messages for inactive users | backend-api | feature/T4-039-reengagement-messages |
[ ] | 2h | Users inactive 3+ days get bot message: "Your friends are ahead! Join today's challenge." Configurable frequency, opt-out |
| T4-040 | Achievement badges in mini app | telegram-mini-app | feature/T4-040-badges-in-mini-app |
[ ] | 2h | Show earned badges (from Track 3) in mini app profile. "Mint as NFT in main app" CTA |
Phase E: Infrastructure & Polish (18h)¶
| ID | Task | Repo | Branch | Status | Est. Hours | Done When |
|---|---|---|---|---|---|---|
| T4-041 | Rate limiting for mini app API endpoints | backend-api | feature/T4-041-miniapp-rate-limiting |
[ ] | 3h | Rate limit mini app endpoints: 60 req/min per user. Anti-abuse for challenge joins. Return 429 with retry_after |
| T4-042 | Caching layer — Redis for leaderboards and challenge data | backend-api | feature/T4-042-redis-caching-layer |
[ ] | 4h | Redis cache for: challenge leaderboards (TTL 5min), user profiles (TTL 1h), challenge list (TTL 10min). Reduces DB load |
| T4-043 | Mini app performance optimization | telegram-mini-app | feature/T4-043-miniapp-performance |
[ ] | 4h | Bundle size < 500KB. First paint < 1s. Lazy load non-critical screens. Image optimization |
| T4-044 | Error handling and offline states | telegram-mini-app | feature/T4-044-error-handling-offline |
[ ] | 3h | Network errors show retry button. Offline: show cached data with "Offline" indicator. No crashes |
| T4-045 | End-to-end testing — full user journey | all | feature/T4-045-e2e-testing |
[ ] | 4h | Test: open mini app -> join challenge -> track progress -> complete -> claim reward -> share -> invite friend. All steps work |