# AKRSera MLM - Production Execution Specification

## 1) Product Identity
- Product name: `AKRSera MLM`
- Operating company: `Lakhsman Wellness Pvt. Ltd.`
- Tech owner footer:
  - `Powered By: AKRSera Technologies Pvt. Ltd. — https://akrsera.in`
  - `Made By: AKRS WORLD — https://akrsworld.in`
- Stack:
  - Laravel `10.x`
  - PHP `8.2+`
  - MySQL/MariaDB
  - TailwindCSS + AlpineJS
- Hosting target: shared hosting (`cPanel`) with no SSH dependency after install.

## 2) Non-Negotiable Architecture Rules
- No Redis, Supervisor, Node daemon, or WebSocket server requirement in production.
- Use only:
  - scheduler via cPanel cron (`php artisan schedule:run`)
  - queue connection `database`
  - cache/session driver `file`
  - local compiled/static assets
- Financial system must be ledger-first:
  - never recalculate full tree for payouts
  - never delete income history
  - all wallet mutations must have transaction records
  - all matching operations must be idempotent and loggable

## 3) Business Model Contract

### 3.1 Hybrid Binary Plan
- Stage 1: `joining matching` (one-time)
  - signal: joined IDs count
  - basis: fixed pair value
  - no BV inclusion
  - stops after matched units
- Stage 2: `repurchase matching` (lifetime)
  - signal: product BV only
  - unlimited depth via ledger propagation
  - daily cron matching
  - carry forward BV mandatory
- Hard rule: joining and BV balances must never mix.

### 3.2 Matching Formula
- Joining:
  - `pairs = min(left_join, right_join)`
  - `income = pairs * pair_value`
- BV:
  - `match_bv = min(left_bv, right_bv)`
  - `income = match_bv * bv_rate`
- Order of operations:
  - apply capping
  - persist wallet transactions
  - persist carry forward remainder

### 3.3 Identity Limit Control
- A single mobile/email/PAN/bank can own multiple IDs.
- Config setting: `max_ids_per_identity` with values `3/5/10/50/unlimited`.
- Validation checkpoints:
  - registration
  - KYC approval
  - joining activation
- Primary data sources: `users`, `user_kyc`, bank fields.

## 4) Core Modules

### 4.1 Installer (`/install`)
Step flow:
1. requirement check
2. database credentials + env write
3. migration run
4. admin account creation
5. company bootstrap setup
6. cron setup guide
7. lock installer permanently (`installed` lock file + env marker)

Installer must:
- be inaccessible after completion
- show branding footer
- support re-entry to incomplete step only

### 4.2 Authentication and Security
- Laravel auth + role middleware (`admin`, `user`, `franchise`).
- Optional login OTP.
- Mandatory OTP for:
  - withdrawal request submit
  - bank detail change
  - password reset flow
- Required security logs:
  - IP log
  - device/session fingerprint log
  - admin activity log
  - webhook log with duplicate callback guard

### 4.3 Wallet System
- Wallet buckets:
  - `income_wallet`
  - `repurchase_wallet`
  - `withdrawable_wallet`
- No negative balances.
- All updates in DB transactions with row locking.
- Admin controls:
  - withdrawal minimum
  - TDS percent
  - charge percent
  - hold days

### 4.4 Ecommerce + BV Posting
- User flow: cart -> checkout -> payment -> admin approval -> BV credit.
- BV credit only after order approval.
- Invoice with GST fields and printable PDF.
- Optional COD + franchise pickup.

### 4.5 Payment Collection
- Gateway adapters:
  - Razorpay
  - Cashfree
  - PayU
  - Easebuzz
  - PhonePe
- Must verify webhooks with signatures.
- Never trust client redirect success as payment proof.

### 4.6 UPI System
- Modes:
  - static QR
  - dynamic QR
  - UPI intent
  - collect request
  - manual verification
- User submits UTR + bank + optional screenshot.
- Fraud controls:
  - unique UTR
  - UTR length >= 12
  - max failed attempts threshold lock
  - IP/device tracking
  - watermarking for uploaded screenshots
- Reconciliation priority:
  1) bank statement import
  2) webhook/SMS parser
  3) duplicate UTR scan
  4) amount + remark match

### 4.7 Payout Processing
- Gateway adapters:
  - RazorpayX
  - Cashfree Payout
  - PayU Payout
  - Easebuzz Payout
- Workflow:
  - request creation
  - wallet amount lock
  - transfer attempt
  - success/failure update
  - notification + retry scheduler

### 4.8 Rank Engine
- Daily cron rank computation.
- Inputs:
  - active directs
  - weak leg BV
  - team turnover
- Supports downgrade and historical rank logs.

### 4.9 Repair and Audit Tools
- Rebuild carry forward
- Recalculate wallets from wallet transaction ledger
- Repair tree references
- Retry failed payouts
- Retry failed webhooks
- Daily wallet audit report
- maintenance mode switch

## 5) Required Data Model (Minimum)
- `users`
- `user_kyc`
- `binary_ledger`
- `user_binary_carry`
- `joining_pair_income`
- `binary_matching_income`
- `wallet_transactions`
- `wallet_balances`
- `products`
- `orders`
- `order_items`
- `withdrawals`
- `ranks`
- `payment_transactions`
- `payout_transactions`
- `upi_transactions`
- `webhook_logs`
- `notification_templates`
- `otp_verifications`
- `franchises`
- `franchise_transactions`
- plus control tables:
  - `settings`
  - `installer_states`
  - `admin_activity_logs`
  - `identity_usage_counters`

## 6) Event-Driven Financial Posting
- Joining activation:
  - propagate ledger upward `type=joining`, `amount=1`.
- Product approval:
  - propagate upward `type=repurchase`, `amount=BV`.
- Order cancel/refund:
  - reverse business ledger entries
  - reverse wallet credit entries through reversal transactions
- Never hard delete finance records.

## 7) Admin Panel Scope
- Dashboard
- Members
- Genealogy
- Wallet
- Accounting
- Ecommerce
- Franchise
- Rank plan
- Payments
- UPI verification
- KYC
- Reports
- Settings
- Repair tools
- Logs
- critical actions:
  - secret login as user
  - merge IDs
  - wallet adjust with reason + log
  - fraud alert broadcast

## 8) User Panel Scope (Mobile First)
- earnings summary
- binary tree + team view
- left/right/auto referral links
- order and invoice history
- wallet transfer
- withdrawal request
- rank tracker
- KYC upload
- downloadable reports

## 9) Franchise Panel Scope
- create IDs
- stock and product sale management
- pickup/dispatch handling
- BV transfer to users
- commission wallet and report
- role-restricted features only

## 10) Marketing Website Module
- Blade + Tailwind + Alpine
- SEO first, mobile first
- includes:
  - preloader
  - notice ticker
  - sticky header with CTA actions
  - hero + trust strip + counters
  - products + plan + calculator
  - achievers + videos + testimonials + blog
  - lead form + CRM storage
  - floating support buttons
  - push notification subscription prompt (5s delay, 7-day cool-off on deny)
- Performance targets:
  - sub-2s first render on shared hosting baseline
  - no blocking JS
  - lazy images/videos
  - service worker cache strategy

## 11) UI/UX Design System
- Visual tone: fintech trust + wellness brand.
- Palette:
  - primary `#16A34A`
  - secondary `#2563EB`
  - accent `#F59E0B`
  - danger `#EF4444`
  - bg `#F8FAFC`
- Must include:
  - responsive sidebar/topbar desktop
  - bottom nav mobile
  - readable cards/forms
  - mobile-friendly tables (collapsible rows)
  - dark mode toggle
  - micro interactions (toasts, success states, loading skeletons)

## 12) Development Phase Gates (Strict Order)
1. project init
2. installer
3. auth
4. wallet base
5. orders
6. tree
7. ledger
8. matching
9. ranks
10. withdrawals
11. gateways
12. UPI
13. notifications
14. admin panel
15. user panel
16. franchise panel
17. website
18. repair tools
19. stress + reconciliation tests

Each phase must end with:
- migrations up/down validation
- seed sanity run
- API/web route smoke test
- error-free log check

## 13) Test and Integrity Criteria
- deterministic cron runs (rerun-safe)
- no duplicate income on retry
- no wallet drift from ledger totals
- webhook duplicate callbacks ignored safely
- rank transitions logged
- financial reversal consistency validated
- stress simulation target:
  - 10,000 users
  - 50,000 orders
  - refunds + payouts included

## 14) Deployment and Ops
- cPanel-safe `.env` defaults documented.
- cron command displayed in installer and settings:
  - `php artisan schedule:run`
- no post-install SSH requirement.
- log retention and downloadable admin diagnostic bundle.

## 15) Definition of Done
- Installer completes from clean server and locks itself.
- Admin can run complete onboarding and business lifecycle.
- Distributor can register, buy, earn, withdraw, and view reports on mobile.
- Financial totals remain consistent under retries, refunds, and payout failures.
- UI appears as premium production SaaS, not a template demo.

## 16) Detailed Feature Matrix Companion
- The full detailed scope for Admin, User, and Franchise modules is maintained in:
  - `docs/COMPLETE_FEATURES_LIST_ADMIN_USER_FRANCHISE.md`
  - `docs/FEATURE_DELIVERY_TRACKER_ADMIN_USER_FRANCHISE.md`
  - `docs/FEATURE_DELIVERY_TRACKER_ADMIN_USER_FRANCHISE_ATOMIC.csv`
- This companion matrix is mandatory input for:
  - sprint planning
  - UAT test case coverage
  - go-live readiness validation
