app_umbrix/MINI_APP_ARCHITECTURE.md

🚀 Umbrix Mini App - Полная Архитектура (PRO LEVEL)

Принципы (Best Practices):

1. Telegram Bot = Минимум - только /start → Open WebApp
2. Mini App = Все - вся логика, UI, воронка продаж
3. No localStorage - только API + MariaDB
4. Telegram WebApp SDK - интеграция с Telegram UI

---

📱 User Journey (Воронка Продаж)

Scenario 1: Новый пользователь БЕЗ реферала

1. User clicks: https://t.me/Dorod_vps_bot
2. Bot sends: "👋 Привет! 🚀 Открыть Umbrix" → WebApp button
3. User opens: https://app.umbrix.net
4. Mini App shows: Onboarding Flow
   ├── Welcome Screen (Telegram.WebApp.initData)
   ├── Language Selection (RU/EN/UZ)
   ├── Plan Selection (Shared/Dedicated/Premium)
   └── Create Account Button
5. Account created → Dashboard
6. Dashboard shows:
   ├── Subscription Status (Active / Expired / Trial)
   ├── QR Code + Links
   ├── Referral Button → Copy link
   ├── Help Button
   └── Settings Button

Scenario 2: Новый пользователь С рефералом

1. User clicks: https://t.me/Dorod_vps_bot?start=ref_john_doe
2. Bot extracts: referrerId = "john_doe"
3. Bot opens: https://app.umbrix.net?ref=john_doe
4. Mini App shows: "🎁 Вы перешли по ссылке от john_doe! +7 дней бесплатно"
5. Onboarding Flow (same as above)
6. On Account Create:
   ├── POST /api/create-user (with referrerId)
   ├── POST /api/referral/track (award +7 days to john_doe)
   └── Both get bonuses
7. Dashboard → показывает trial статус + bonus days

Scenario 3: Существующий пользователь (возврат)

1. User opens: https://t.me/Dorod_vps_bot → WebApp
2. Mini App detects: Telegram.WebApp.initDataUnsafe.user.id
3. API Check: GET /api/user-subscription?telegramId=12345
4. Response: { hasSubscription: true, token: "...", status: "active" }
5. Mini App redirects: /dashboard (skip onboarding)
6. Dashboard shows:
   ├── Subscription details
   ├── Days remaining: "23 дня осталось"
   ├── QR Code + Links
   └── Referral stats: "3 друга, +21 день заработано"

Scenario 4: Пользователь с истекшей подпиской

1. API Check: { hasSubscription: true, status: "expired" }
2. Dashboard shows:
   ├── ⚠️ "Подписка истекла 5 дней назад"
   ├── "Пригласите 2 друзей для продления" (gamification)
   ├── "Или оплатите" → Payment Button
   └── Referral progress bar: [■■■□□] 3/5 friends

---

🗂️ Структура файлов Mini App

/app
├── page.tsx                    # 🏠 Landing / Onboarding (если новый user)
├── dashboard/
│   └── page.tsx               # 📊 Dashboard (если есть подписка)
├── plans/
│   └── page.tsx               # 💎 Plan Selection (выбор тарифа)
├── referral/
│   └── page.tsx               # 🎁 Referral Stats (уже есть!)
├── help/
│   └── page.tsx               # ❓ Help / FAQ (уже есть!)
├── setup/
│   └── page.tsx               # 🔧 Setup Wizard (инструкции по настройке)
└── subscription/
    └── [token]/
        └── page.tsx           # 📲 Subscription Details (QR код, ссылки)

/components
├── OnboardingFlow.tsx         # 🎬 Onboarding steps (language, plan, create)
├── PlanCard.tsx               # 💳 Plan card (Shared/Dedicated/Premium)
├── SubscriptionStatus.tsx     # ✅ Status badge (Active/Expired/Trial)
├── ReferralProgress.tsx       # 📈 Progress bar (3/5 friends)
├── QRCodeModal.tsx            # ✅ Уже есть
├── ReferralModal.tsx          # ✅ Уже есть
└── SetupWizard.tsx            # ✅ Уже есть

/lib
├── telegram-webapp.ts         # 🔌 Telegram WebApp SDK wrapper
├── marzban-api.ts            # ✅ Уже есть
└── constants.ts              # ✅ Уже есть

---

🎨 UI Components (Telegram WebApp Style)

1. OnboardingFlow.tsx

// Multi-step onboarding (Welcome → Language → Plan → Create)
// Uses Telegram.WebApp.BackButton, .MainButton
// Stores state in React (NOT localStorage)

2. PlanCard.tsx

// Карточка тарифа с ценой, features, "Выбрать" кнопкой
// Props: { plan, price, features[], selected, onClick }
// Design: Telegram-style card (rounded, shadow, accent color)

3. SubscriptionStatus.tsx

// Badge: "✅ Активна до 15.03.2026" / "⚠️ Истекла" / "🎁 Trial (7 дней)"
// Color-coded: green/red/blue
// Props: { status, expiryDate, daysRemaining }

4. ReferralProgress.tsx

// Progress bar: [■■■□□] 3/5 friends → +30 days bonus!
// Shows: current referrals, next milestone, bonus amount
// Props: { referralCount, bonusDays }

---

🔄 API Endpoints (уже есть + новые)

Existing:

• ✅ POST /api/create-user
• ✅ GET /api/user-subscription
• ✅ POST /api/referral/track
• ✅ GET /api/referral/stats

New (to add):

// Check if user exists by Telegram ID
GET /api/user-check?telegramId=12345
Response: { exists: boolean, username?: string, status?: string }

// Get plan details
GET /api/plans
Response: { plans: [{ id, name, price, features[] }] }

// Create payment link
POST /api/create-payment
Body: { username, plan, amount }
Response: { paymentUrl: string, orderId: string }

---

📋 Implementation Priority

Phase 1: Core Flow (СЕЙЧАС)

1. ✅ Упростить n8n workflow (DONE)
2. Create OnboardingFlow.tsx (Welcome → Language → Plan → Create)
3. Update app/page.tsx (detect new vs existing user)
4. Create app/dashboard/page.tsx (show subscription status)
5. Create PlanCard.tsx component

Phase 2: Referral Integration

6. Update OnboardingFlow to accept ?ref=USERNAME
7. Pass referrerId to /api/create-user
8. Add ReferralProgress.tsx to dashboard
9. Test full referral flow

Phase 3: Payment

10. Add /api/plans endpoint
11. Add /api/create-payment endpoint
12. Integrate payment gateway (crypto)
13. Add webhook for payment confirmation

Phase 4: Polish

14. Telegram WebApp SDK integration (BackButton, MainButton, theme)
15. i18n (RU/EN/UZ)
16. Error handling + loading states
17. Analytics (track conversions)

---

🎯 Key Differences from Current Code

Current	New (PRO)
Bot имеет 3 команды + кнопки	Bot только /start → WebApp
Нет onboarding flow	Full onboarding в Mini App
localStorage для данных	API + MariaDB only
Нет gamification	Referral progress bar
Нет выбора плана в UI	Plan selection screen
Нет payment flow	Integrated payment
Нет Telegram theme	Uses Telegram.WebApp.themeParams

---

💡 Pro Tips

1. Telegram WebApp SDK: используй Telegram.WebApp.MainButton для кнопок действий
2. No localStorage: только API, чтобы работало на всех устройствах
3. Gamification: показывай прогресс реферальной программы (мотивация!)
4. Mobile-first: Mini App всегда открывается на мобильном
5. Fast loading: минимизируй API calls, cache в React state
6. Error handling: graceful fallback если нет Telegram.WebApp
7. i18n ready: структура для перевода на другие языки

---

🚀 Next Steps

Создам полную структуру Mini App с учетом этой архитектуры!