HydraDrop Global

A production-grade Telegram viral growth engine + airdrop system + monetization machine. Designed for 100K+ users with high retention and revenue from day 1.

🎯 Core Features

• User Engine: Auto-creation, Telegram ID tracking, unique referral links
• Referral System: Unlimited multi-level referrals with instant rewards
• Earning Engine: Daily login rewards, task-based earnings, referral bonuses
• Rank System: Bronze → Silver → Gold → Platinum → Diamond progression
• Locked Reward System: 30% rewards locked, unlock via referrals and tasks
• Bonus Engine: Daily spin wheel with mystery rewards
• Monetization: Boost packs (₹49 → 2x, ₹99 → 5x coins), VIP membership
• Leaderboard: Global rankings with top 50 users display
• Content Tasks: Users earn by posting reels, tweets, etc.
• Anti-Spam: Rate limiting and cooldown systems

🏗️ Tech Stack

• Node.js with Telegraf for Telegram bot
• Express.js for API layer
• MySQL (Supabase/TiDB) for database
• tRPC for type-safe API
• Redis for rate limiting and caching
• Razorpay for payment processing
• Railway for deployment

📋 Prerequisites

1. Telegram Bot Token: Get from @BotFather
2. Razorpay Account: Sign up at dashboard.razorpay.com
3. MySQL Database: Supabase, TiDB, or any MySQL provider
4. Node.js 18+ and pnpm
5. Railway Account (for deployment)

🚀 Quick Start

1. Clone Repository

git clone https://github.com/yourusername/hydradrop-global.git
cd hydradrop-global

2. Install Dependencies

pnpm install

3. Set Up Environment Variables

Create a .env file with the following:

# Database
DATABASE_URL=mysql://user:password@host:3306/hydradrop

# Telegram Bot
TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN_FROM_BOTFATHER

# Razorpay Payment
RAZORPAY_KEY_ID=your_razorpay_key_id
RAZORPAY_KEY_SECRET=your_razorpay_key_secret

# Manus OAuth (pre-configured)
VITE_APP_ID=your_app_id
OAUTH_SERVER_URL=https://api.manus.im
JWT_SECRET=your_jwt_secret

# Owner Info
OWNER_OPEN_ID=your_owner_id
OWNER_NAME=Your Name

# App Config
NODE_ENV=production
PORT=3000

4. Set Up Database

Run the SQL migration to create all tables:

# Copy the SQL from drizzle/0001_slow_wendell_rand.sql
# Execute it in your MySQL database
mysql -u user -p hydradrop < drizzle/0001_slow_wendell_rand.sql

Or use the web UI to execute the SQL directly.

5. Start Development Server

pnpm dev

The bot will start in polling mode and listen for Telegram updates.

6. Run Tests

pnpm test

📊 Database Schema

Core Tables

telegram_users

• Stores user data, coins, ranks, referrals
• Tracks daily rewards, spin times, streaks

referrals

• Tracks referrer → referred user relationships
• Records reward amounts given

transactions

• Audit trail for all coin movements
• Types: daily_reward, referral_bonus, task_reward, spin_reward, boost_purchase, unlock_reward

tasks

• Available tasks for users to complete
• Types: reel, tweet, share, follow

user_tasks

• Tracks user task submissions and approvals
• Statuses: pending, submitted, approved, rejected

boost_packs

• Monetization offerings with multipliers
• Example: ₹49 → 2x coins, ₹99 → 5x coins

purchases

• Payment records with Razorpay integration
• Tracks payment status and completion

🎮 Telegram Bot Commands

User Commands

• /start - Initialize bot and show welcome
• Dashboard - View coins, rank, referrals, progress
• Earn - Daily rewards, referral info, tasks
• Invite - Share referral link
• Leaderboard - View top 50 users
• Boost - Purchase coin multipliers
• Tasks - View and submit tasks
• Spin - Daily mystery reward wheel

Admin Commands

• /admin - Admin panel (owner only)
• Task management
• User adjustments
• Leaderboard monitoring

💰 Monetization Strategy

Boost Packs

Pack	Price	Multiplier	Coins
Starter	₹49	2x	+100 coins → 200
Pro	₹99	5x	+100 coins → 500
Elite	₹199	10x	+100 coins → 1000

VIP Membership

• Daily bonus coins
• Faster rank progression
• Exclusive tasks
• Ad-free experience

🔐 Security Features

• Rate limiting on all actions
• 24-hour cooldowns for daily/spin rewards
• Referral fraud detection
• Payment verification via Razorpay
• SQL injection prevention (Drizzle ORM)
• CORS protection
• Input validation (Zod)

📈 Scaling Considerations

Performance

• Response time target: < 3 seconds
• Async processing for heavy operations
• Database indexing on frequently queried columns
• Redis caching for leaderboard

Database Optimization

• Indexes on: telegram_id, rank, user_id, status
• Partitioning by date for transactions table (future)
• Connection pooling via Drizzle

Load Testing

# Example: Test with 1000 concurrent users
artillery quick --count 1000 --num 100 http://localhost:3000/health

🚢 Deployment

Railway Deployment

1. Connect GitHub Repository

   railway link

2. Set Environment Variables

   railway variables set TELEGRAM_BOT_TOKEN=your_token
   railway variables set DATABASE_URL=your_db_url
   railway variables set RAZORPAY_KEY_ID=your_key
   railway variables set RAZORPAY_KEY_SECRET=your_secret

3. Deploy

   railway up

4. Set Telegram Webhook (optional, for production)

   curl -X POST https://api.telegram.org/bot{TOKEN}/setWebhook \
     -d "url=https://your-railway-url.railway.app/webhook/telegram"

Docker Deployment

FROM node:18-alpine
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install
COPY . .
RUN pnpm build
EXPOSE 3000
CMD ["pnpm", "start"]

📝 Testing Instructions

Unit Tests

pnpm test

Manual Testing

1. Start Bot

   pnpm dev

2. Open Telegram and Find Your Bot

   • Search for your bot username
   • Send /start

3. Test Daily Reward

   • Click "Earn" → "Claim Daily"
   • Check coins increased by 50

4. Test Referral

   • Click "Invite" to get referral link
   • Share link with another user
   • Verify referrer gets 500 coins

5. Test Leaderboard

   • Click "Leaderboard"
   • Verify top 10 users displayed

6. Test Spin

   • Click "Spin Wheel"
   • Verify random reward (100-5000 coins)
   • Check 24h cooldown

Load Testing

# Test concurrent users
ab -n 1000 -c 100 http://localhost:3000/health

🐛 Troubleshooting

Bot Not Responding

1. Check TELEGRAM_BOT_TOKEN is valid
2. Verify bot is running: pnpm dev
3. Check logs for errors: tail -f .manus-logs/devserver.log

Database Connection Failed

1. Verify DATABASE_URL format: mysql://user:pass@host:port/db
2. Check MySQL server is running
3. Verify credentials and permissions

Payments Not Processing

1. Verify Razorpay credentials in .env
2. Check Razorpay account is in live mode
3. Test with Razorpay test keys first

High Latency

1. Check database query performance
2. Enable Redis caching
3. Scale Railway resources

📚 API Documentation

tRPC Endpoints

All endpoints are under /api/trpc/hydradrop.*

hydradrop.getUser

Get or create user by Telegram ID

input: { telegramId: number }
output: TelegramUser

hydradrop.getDashboard

Get dashboard data (coins, rank, rewards)

input: { telegramId: number }
output: { user, rank, canClaimDaily, canSpinNow }

hydradrop.claimDaily

Claim daily reward

input: { telegramId: number }
output: { success: boolean }

hydradrop.spin

Perform spin wheel

input: { telegramId: number }
output: { reward: number }

hydradrop.getLeaderboard

Get top users

input: { limit: number }
output: TelegramUser[]

hydradrop.getBoostPacks

Get available boost packs

input: {}
output: BoostPack[]

hydradrop.getTasks

Get available tasks

input: {}
output: Task[]

hydradrop.submitTask

Submit task completion

input: { telegramId, taskId, submissionUrl }
output: { success: boolean }

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Commit changes: git commit -am 'Add feature'
4. Push to branch: git push origin feature/your-feature
5. Submit pull request

📄 License

MIT License - See LICENSE file for details

🎯 Roadmap

• Admin dashboard for user management
• Advanced analytics and reporting
• Multi-language support
• Mobile app (iOS/Android)
• Web interface for users
• Advanced referral tiers
• Crypto integration
• Gamification enhancements

📞 Support

For issues and questions:

• GitHub Issues: hydradrop-global/issues
• Telegram Support: @hydradrop_support
• Email: support@hydradrop.global

---

Built with ❤️ for the Telegram community