System Requirements Document

Coin Flip Betting App — Complete Product Roadmap

Version: 1.0
Market: India (UPI-based)
Model: Real Money + House Edge

Table of Contents

1. User Journey
2. Playing Flow
3. Cash Out Flow
4. Core Features
5. Admin Panel
6. House Edge & Commission Model
7. Tech Stack
8. Admin Controls
9. Coin Flip Logic (AI-Assisted Fair Play)
10. Build Order (MVP → Scale)
11. Legal Checklist (India)

1. User Journey

1.1 Onboarding

• Step 1: Land on app/website

  • Action: See live game activity, pot sizes, winner feed
  • Detail: Mobile number + OTP (fast) or Email + Password

• Step 2: Sign Up

• Step 3: KYC Verification

  • Detail: Aadhaar + PAN card (mandatory for real money)

• Step 4: Age Verification

  • Detail: Must confirm 18+ with DOB

• Step 5: Wallet Created

  • Detail: Auto-created with ₹0 balance + welcome bonus (optional)

• Step 6: Referral Code

  • Detail: Optional — enter a friend’s code for bonus credits

1.2 Deposit Flow

• Goal: Fast, frictionless deposit. Auto-updates wallet. No admin approval needed.

• Process:

  1. User taps "Add Money"
  2. Enters amount (e.g. ₹500)
  3. Redirected to UPI / Payment Gateway
  4. Payment processed by gateway (Razorpay / Cashfree)
  5. Gateway sends webhook to backend (payment success confirmation)
  6. Backend verifies webhook signature (security check)
  7. User wallet balance updated INSTANTLY (+₹500)
  8. User gets notification: "₹500 added to your wallet"

• Key Rules:

  • Deposit reflects immediately — no manual approval
  • Minimum deposit: ₹50
  • Maximum deposit: ₹50,000 per transaction
  • All deposits logged with: amount, time, UTR number, gateway reference
  • Failed payments auto-refund within 24 hours

1.3 Withdrawal Flow

• Goal: User can withdraw winnings, but ONLY after admin approval.

• Process:

  1. User taps "Withdraw"
  2. Enters amount + selects saved bank account / UPI ID
  3. Request created with status: PENDING
  4. Admin sees request in dashboard
  5. Admin reviews (checks for fraud flags, KYC status)
  6. Admin APPROVES → payment sent via payout API OR Admin REJECTS → amount returned to wallet + reason shown to user
  7. User notified via push notification + SMS

• Key Rules:

  • Minimum withdrawal: ₹100
  • Maximum withdrawal per day: ₹1,00,000
  • Only KYC-verified users can withdraw
  • Withdrawal from bonus credits NOT allowed (only real money winnings)
  • Admin target: process within 24 hours
  • Users can see withdrawal status: Pending → Approved → Transferred

2. Playing Flow

2.1 Finding a Game

• User enters the Lobby
  • Sees list of active game rooms:
    • Public rooms (anyone can join)
    • Private rooms (invite only, room code required)
  • Each room card shows:
    • Current pot size
    • Number of players
    • Countdown to next flip
    • Min / Max bet for that room

2.2 Joining a Round

• User picks a room → sees current round
  • Betting window OPEN (e.g. 30 seconds)
  • User selects: HEADS or TAILS
  • User enters bet amount (within room limits)
  • User taps CONFIRM BET
  • Amount deducted from wallet immediately
  • Bet locked in — shown on screen with side chosen
  • Timer hits 0 → Betting window CLOSES
  • No more bets accepted for this round

2.3 The Flip

• "Flipping..." animation begins (2-3 seconds)
• Server calculates result (see Section 9)
• Result broadcast to ALL players in room via WebSocket
• Coin lands on HEADS or TAILS (animated)
• Winners shown instantly
• Payouts credited to wallets (minus house edge)
• Next round countdown begins automatically

2.4 After the Round

• Win: wallet updated, win animation, amount shown
• Loss: loss shown, “Play Again” prompt
• Round summary: who bet what, result, your profit/loss
• Chat stays live between rounds

2.5 Leaving a Game

• User can leave anytime BETWEEN rounds
• If a user has placed a bet and the round has started → bet stands, they receive result on notification
• Wallet always stays intact — user can return anytime

3. Cash Out Flow

3.1 Wallet Overview

• Every user has a single wallet with two buckets:
  • Real Balance: Deposits + real money winnings (Withdrawable after approval)
  • Bonus Credits: Welcome bonus, referral rewards (Play-only)

3.2 Withdrawal Steps (User Side)

1. Go to Wallet → Withdraw
2. Enter amount
3. Select payout method:
   • UPI ID
   • Bank account (IFSC + Account number, saved from KYC)
4. Confirm with OTP
5. Request submitted → status shows “Under Review”
6. Once admin approves → status shows “Transferred”
7. Money arrives in bank within 1–2 business days (IMPS = instant)

3.3 Withdrawal Rules

• KYC mandatory before first withdrawal
• PAN card required for withdrawals above ₹10,000 (TDS compliance)
• TDS (30%) deducted on net winnings above ₹10,000 per year (India rule)
• User gets TDS certificate downloadable from app
• Withdrawal history always visible with timestamps

4. Core Features

4.1 User-Facing Features

• Live Lobby: See all active rooms, pot sizes, live player count
• Coin Flip Game: Real-time animated flip with WebSocket results
• Wallet: Deposit, withdraw, balance, transaction history
• My Stats: Total bets, wins, losses, win rate, total earnings
• Leaderboard: Top winners daily / weekly / all-time
• Notifications: Win/loss alerts, deposit confirmed, withdrawal status
• In-Room Chat: Chat with other players between rounds
• Private Rooms: Create a room, set bet limits, share code with friends
• Referral Program: Refer friends → earn bonus when they deposit
• Responsible Gambling: Set daily deposit limit, daily loss limit, self-exclude
• Transaction History: Full log of every bet, deposit, withdrawal
• Security: OTP login, device tracking, 2FA for withdrawals

4.2 Game Room Types

• Micro Room: ₹10 – ₹100 bets
• Standard Room: ₹100 – ₹1,000 bets
• High Stakes Room: ₹1,000 – ₹10,000 bets
• Private Room: Custom limits, invite-only

5. Admin Panel

5.1 Dashboard Overview

• Admin logs into a separate secure web portal. Sees:
  • Total active users right now
  • Total bets placed today
  • Total deposits today (₹ amount)
  • Total withdrawals pending
  • Platform revenue today (house edge collected)
  • Real-time bet activity feed

5.2 UPI ID Management (Deposit Settings)

• Admin can set and update the UPI ID that users pay to:
  • Admin Panel → Settings → Payment Configuration
  • Enter UPI ID (e.g. business@ybl)
  • Save → All new deposit QR codes generate using this UPI ID
  • Admin can update anytime (e.g. if UPI ID changes)
  • Old pending transactions complete on old ID
  • New transactions use new ID
  • Admin can add multiple UPI IDs (load balancing)
  • Admin can set payment gateway API keys (Razorpay / Cashfree)
  • Admin can set min/max deposit limits globally

5.3 User Management

• View User: Full profile, KYC docs, wallet balance, bet history
• Verify KYC: Approve or reject Aadhaar/PAN documents
• Ban User: Temporary or permanent ban
• Flag User: Mark for review (suspicious activity)
• Adjust Balance: Manual credit/debit with reason logged
• View Activity: Full login history, device info, IP addresses
• Withdrawal Approval: Approve or reject each withdrawal request

5.4 Game Management

• Pause All Games: Kill switch — stops all rooms instantly
• Pause Room: Stop a specific room only
• Cancel Round: Cancel current round + auto-refund all bets
• Create Room: Open new game rooms with custom settings
• Set Bet Limits: Change min/max bet per room
• Set House Edge: Adjust commission % (see Section 6)
• Round History: See every flip result, who bet what, payouts

5.5 Financial Management

• View all deposits (with UTR, gateway reference, amount, user)
• View all withdrawals (pending, approved, rejected, transferred)
• Approve / reject withdrawal requests
• View total house edge collected (admin commission)
• Export financial reports (CSV / PDF)
• View TDS liability report

6. House Edge & Commission Model

6.1 How It Works

• The house edge is a small percentage taken from every winning payout. The coin flip itself is completely fair (50/50). The platform earns money through volume.
• Example with 4% house edge:
  • Round: 10 players bet ₹100 each = ₹1,000 total pot
  • 5 players bet HEADS → ₹500 on heads
  • 5 players bet TAILS → ₹500 on tails
  • Result: HEADS wins
  • Gross payout to winners = ₹1,000
  • House edge (4%) = ₹40
  • Net payout to HEADS winners = ₹960
  • Each winner receives = ₹192 (profit of ₹92 on ₹100 bet)
  • Admin commission earned = ₹40

6.2 Commission Storage

• Round ends
  • Total winning payout calculated
  • House edge % deducted automatically by backend
  • Winners' wallets credited (net amount)
  • House edge amount transferred to ADMIN COMMISSION WALLET
  • Admin can withdraw from commission wallet to bank anytime
  • Full commission log maintained: per round, per day, per month

6.3 House Edge Configuration

• Room Type: Recommended House Edge
  • Micro Room: 3%
  • Standard Room: 4%
  • High Stakes: 5%
  • Private Room: 3% (to attract users)
• Admin can adjust these from the Admin Panel → Game Settings.

6.4 Why This Works Better Than Rigging

• Factor: House Edge Model vs. Rigged AI
  • Legal: Legal (with license) vs. Fraud
  • User Trust: Provably fair vs. Users detect patterns
  • Long-term Revenue: Guaranteed % on every bet vs. Users leave
  • Licensing: Obtainable vs. No license issued
  • Scalability: More bets = more revenue vs. Risk of large losses
• At 4% house edge, 1,000 rounds of ₹500 average bet = ₹20,000 guaranteed admin profit regardless of who wins.

7. Tech Stack

7.1 Frontend (User App)

• Framework: React Native (iOS + Android from one codebase)
• Web Version: React.js + Next.js (SEO, fast load)
• Styling: Tailwind CSS (Fast, clean UI)
• Animations: Framer Motion / Lottie (Smooth coin flip animation)
• Real-time: Socket.io (client) (Live game updates)
• State Management: Redux Toolkit (Wallet, game state)

7.2 Backend

• Runtime: Node.js (Fast, WebSocket-native)
• Framework: Express.js (Simple REST APIs)
• Real-time: Socket.io (server) (WebSocket game rooms)
• Authentication: Firebase Auth / JWT (OTP login, secure tokens)
• Task Queue: Bull + Redis (Process bets in order, prevent race conditions)

7.3 Database

• PostgreSQL: Users, wallets, transactions, bets (ACID-compliant — critical for money)
• Redis: Live game state, room data, bet locks, sessions
• S3 / Firebase Storage: KYC documents, profile photos

7.4 Payments

• Provider: Use
  • Razorpay: UPI deposits, bank payouts (India)
  • Cashfree: Alternative payment gateway
  • Digio / KARZA: KYC / Aadhaar verification API

7.5 Infrastructure

• Hosting: AWS (EC2 + RDS + ElastiCache)
• CDN: CloudFront
• Load Balancer: AWS ALB (for WebSocket scaling)
• Monitoring: Datadog / New Relic
• Logs: CloudWatch
• CI/CD: GitHub Actions
• SSL: Let’s Encrypt / AWS ACM

7.6 Admin Panel

• Layer: Technology
• Framework: React.js
• UI Library: Ant Design / MUI
• Charts: Recharts / ApexCharts
• Hosting: Same backend server (separate route, protected)

8. Admin Controls

8.1 Emergency Controls

• Global Kill Switch: Pauses ALL games instantly, no new bets accepted
• Pause Room: Stops one specific room only
• Cancel Round: Cancels active round, auto-refunds all bets in that round
• Lock Withdrawals: Temporarily disable all withdrawal requests (e.g. maintenance)
• Lock Deposits: Temporarily disable new deposits

8.2 Game Controls

• Set number of rounds per hour
• Set countdown timer (default: 30 seconds betting window)
• Set minimum players required to start a round
• Open / close specific room types
• Set global bet limits across all rooms

8.3 User Controls

• Ban user (temporary: 1 day / 7 days / 30 days, or permanent)
• Reset user password
• Force KYC re-verification
• Add/remove bonus credits manually
• Flag account for monitoring
• View full device + IP history

8.4 Financial Controls

• Approve / reject withdrawals (with reason)
• Set daily withdrawal limit (platform-wide)
• Set max single withdrawal amount
• Configure TDS deduction rate
• View and export audit logs (every transaction ever)
• Set UPI ID for deposits
• Configure payment gateway keys

8.5 Fraud Detection Alerts

• Admin gets automatic alerts for:
  • User betting same side in 10+ consecutive rounds
  • Multiple accounts from same device/IP
  • Unusually large bet just before withdrawal request
  • Rapid deposit → bet → withdraw pattern (money laundering flag)
  • Failed KYC attempts above threshold

9. Coin Flip Logic (AI-Assisted Fair System)

9.1 How the Result Is Generated

• The flip result is generated server-side only. Clients never influence the result. Two layers of fairness:
  • Layer 1 — Cryptographic Randomness
  • Layer 2 — Provably Fair Verification
    • Before round: app shows serverSeedHash publicly
    • After round: app reveals serverSeed
    • Users can verify: SHA256(serverSeed) === serverSeedHash
    • Users can verify the result themselves using published formula

9.2 AI Role: Smart Bet Monitoring

• The AI does NOT rig results. Instead, it:

  • AI Function: Purpose
  • Analyze bet distribution per round: Detect extremely lopsided rounds
  • Monitor player patterns: Flag suspicious consistent-winner accounts
  • Dynamic room balancing: Suggest opening new rooms when one is too crowded

• Result Calculation:

  • serverSeed = crypto.randomBytes(32) // Generated before round
  • serverSeedHash = SHA256(serverSeed) // Committed publicly at round start
  • clientSeed = hash of all player IDs + bets // Combines all players
  • roundId = unique round identifier
  • result = HMAC_SHA256(serverSeed, clientSeed + roundId)
    • convert to number → mod 2 → 0 = Heads, 1 = Tails
  • After result: serverSeed revealed → anyone can verify

9.3 Handling Lopsided Rounds

• If 90% of money is on one side:
  • Option A (Recommended): Round proceeds normally
    • House edge still collected from winners
    • Platform math still works at scale
  • Option B: Admin sets a max-bet-per-side limit per round
    • If one side fills up, that side closes for new bets
    • Balances rounds automatically without rigging

9.4 Why Users Trust This

• Every result is verifiable after the fact
• Players can export and audit their entire history
• RNG certificate from third party (required for licensing)
• No human can change a result once a round starts

10. Build Order (MVP → Scale)

Phase 1 — Foundation (Weeks 1–4)

• Goal: Working game with fake money
  • User auth (OTP login)
  • Basic wallet (fake balance)
  • Single game room (WebSocket)
  • Coin flip logic (server-side RNG)
  • Bet placement + result + wallet update
  • Simple React frontend with animation
  • Admin: view users, view bets
  • Test: 5–10 people play internally

Phase 2 — Real Money (Weeks 5–8)

• Goal: Real deposits working, admin controls in place
  • KYC integration (Digio / KARZA API)
  • Razorpay deposit integration
  • Webhook handler (auto wallet update on payment)
  • Withdrawal request system
  • Admin withdrawal approval dashboard
  • Admin UPI ID configuration
  • House edge deduction logic
  • Commission wallet for admin
  • Test: Small closed beta with real ₹ (₹10–₹100 bets)

Phase 3 — Engagement (Weeks 9–12)

• Goal: Keep users coming back
  • Leaderboard (daily/weekly/all-time)
  • Bet history + stats page
  • Notifications (push + SMS)
  • In-room chat
  • Private rooms with invite codes
  • Referral program
  • Responsible gambling limits
  • Provably fair verification page

Phase 4 — Scale & Protect (Weeks 13–16)

• Goal: Handle 1,000+ concurrent users safely
  • Load balancing for WebSockets
  • Redis for live game state
  • Fraud detection AI alerts
  • Multiple room types (Micro / Standard / High Stakes)
  • TDS calculation + certificate download
  • Full audit log export
  • Third-party RNG certification
  • Gambling license application

Phase 5 — Growth (Month 5+)

• Goal: Expand and enhance user experience
  • Mobile app (React Native)
  • Tournaments (scheduled events, big prize pools)
  • Loyalty program (VIP tiers)
  • Affiliate/influencer program
  • Analytics dashboard for admin
  • Multi-language support

11. Legal Checklist (India)

• Gambling License: Required — varies by state (Goa, Sikkim, Meghalaya have frameworks)
• KYC: Aadhaar + PAN mandatory for real money
• Age Verification: 18+ — must be enforced at signup
• TDS: 30% on net winnings above ₹10,000/year (Finance Act 2023)
• RNG Certificate: Required for licensing — get from BMM Testlabs or similar
• Privacy Policy: PDPB compliance (India data protection)
• Terms of Service: Must include responsible gambling, dispute resolution
• GST: 28% GST on deposits (as per 2023 amendment)