# Requirements Summary - Telegram Mini App Investment Platform

## Core System
- Telegram Mini App with auto-registration on first launch
- Multi-level marketing (MLM) referral system (3 levels)
- Gaming campaign investment with tier-based rewards
- Credit balance system with crypto deposits/withdrawals

## User Registration & Auth
- Capture all Telegram data: user_id, username, first_name, last_name, language_code, photo_url
- Support multiple devices/sessions per user
- No additional verification (email/phone)
- No action on deleted Telegram accounts
- Auto-register on referral link click or direct app access

## Referral System
- Format: `https://t.me/botname?start=REF123456`
- One unique link per user, no expiration
- Auto-register on link click
- Circular prevention: existing users detected, no new registration
- Commission structure: L1=50%, L2=30%, L3=20% of referral's daily reward (not investment)
- Commission timing: calculated immediately after daily reward, credited immediately
- Commission display: show pending + distributed during transition
- Commission stops when referral's investment contract expires (after last day reward)

## Credit Balance
- Initial: $0
- Withdrawal: via payment gateway API (provided later)
- Deposit: crypto payment gateway, unique address per request, callback on status
- Track all transactions

## Investment System
- Tiers (USD): T1≤$100(1%,120d), T2≤$500(1.5%,130d), T3≤$1k(2%,140d), T4≤$2k(2.5%,150d), T5≤$5k(3%,160d), T6>$5k(3.5%,180d)
- Min: $10, Max: none
- Multiple concurrent investments allowed
- Each investment tracked independently (tier, rate, duration)
- No withdrawal mid-cycle
- No principal return on expiration
- Last day reward issued + commission calculated on expiration

## Daily Reward Calculation
- Timezone: UTC+8
- Timing: Invest 23:59:59 Day5 → calc Day6 00:00 → distribute Day7 00:00 (calc+distribute both on Day7 00:00)
- No DST handling
- Calculate on weekends/holidays
- Don't show pending rewards
- Cronjob: runs every 5min, creates DB entry at 00:00 to prevent duplicates, handles downtime
- Each investment calculated independently

## Technical Stack
- Backend: Django (Python) recommended, Laravel (PHP) alternative, MySQL, OS cronjob, no caching, API rate limiting yes
- Telegram: python-telegram-bot/aiogram (Django) or irazasyed/telegram-bot-sdk (Laravel), webhooks yes
- Frontend: React 18+ TypeScript, Vite, Zustand+TanStack Query, React Router v6, Telegram Web App SDK yes, no PWA
- Infrastructure: Cloud server, Let's Encrypt SSL manual, manual backups/staging, scale: tens of thousands

## Logging
- Create/Update/Delete: POST data, previous/new state, request metadata (user_id, IP, timestamp, method, URL), query params, response metadata (status, time, count), filter criteria, pagination
- Retrieval: request metadata, query params, response metadata, filter criteria, pagination (queryable in admin)
- Financial transactions: all logged
- Purpose: admin panel queryability

## Security
- Telegram initData validation: REQUIRED (HMAC-SHA-256, validate hash, check auth_date, verify user_id)
- CSRF: yes
- Encryption: passwords hashed, balances/transactions not encrypted (DB ops), API keys in env vars, session tokens handled by framework, TLS/SSL in transit
- API auth: JWT tokens
- Audit logs: yes (financial transactions)

## Documents
- `/docs/requirements-and-questions.md` - full requirements
- `/docs/frontend-architecture.md` - frontend architecture details