# MLM Investment Platform – Backend Specification (v1.0)

## 1. Overview

This document defines the complete backend specification for a dynamic MLM-based investment platform. The system supports multi-channel deposits, dynamic income computation (without cron jobs), multi-leg matching logic, configurable ROI, and a modular eligibility-driven income system.

The backend will be implemented using Laravel with MySQL as the database.

---

## 2. Core Architecture Principles

### 2.1 Hybrid Financial Model

* Ledger-based storage for real money:

  * Deposits
  * Withdrawals
  * Transfers

* Dynamic computation for:

  * ROI
  * Level income
  * Rank income

* Event-based storage for:

  * Direct income
  * Reward income

### 2.2 No Cron Dependency

All computations are performed on-demand:

* Dashboard load
* Withdrawal request
* Triggered events

### 2.3 Separation of Concerns

* Financial data must not mix with virtual data
* Computed values must not be persisted unnecessarily
* Configuration must be externalized

---

## 3. User System

### 3.1 Hierarchy

* Each user has a sponsor (parent)
* Structure is unilevel (unlimited width)
* Depth is unbounded

### 3.2 User Attributes

* status: active, inactive, blocked
* roi_enabled: boolean
* is_working_id: boolean
* team_business_enabled: boolean
* team_business_levels: integer (nullable)

### 3.3 Working ID

A working ID:

* Does not generate ROI
* Can generate direct and level income
* Participates in matching
* Team business contribution is configurable

---

## 4. Wallet Model

### 4.1 Deposit Wallet

Stored via transactions:

* Sources: deposits, transfers, admin credits
* Usage: investments, transfers

### 4.2 Investment Wallet

Derived:

* Sum of active investments

### 4.3 ROI Wallet

Computed:

* Total ROI generated minus withdrawals

### 4.4 Bonus Wallet

Computed:

* Direct income
* Level income
* Rank income
* Reward income

---

## 5. Deposit System

### 5.1 Supported Channels

* Web3 (wallet-based)
* Manual crypto (transaction hash submission)
* Other manual methods (bank, UPI, etc.)
* Admin deposits

### 5.2 Flow

Deposit Request → Verification → Approval → Ledger Credit

### 5.3 States

* pending
* approved
* rejected

### 5.4 Validation

* Transaction hash must be unique
* Manual entries require proof or remarks
* Only approved deposits affect balances

---

## 6. Withdrawal System

### 6.1 Rules

* Minimum withdrawal: configurable (default 10 USD)
* Fee: configurable (default 5%)

### 6.2 Computation

withdrawable = total_income - total_withdrawn

---

## 7. Investment System

### 7.1 Rules

* Investments are funded from deposit wallet
* Each investment is associated with a package

### 7.2 Package System

Packages define:

* Minimum investment
* Maximum investment
* Identity of investment plan

---

## 8. ROI System

### 8.1 Characteristics

* Starts after initial delay (configurable)
* Non-compounding
* Maximum ROI capped at 2x investment

### 8.2 Time-Based Configuration

ROI percentage is defined by time-based configuration:

* Multiple ROI entries per package
* Each entry has effective date range

### 8.3 Computation

* Investment duration is segmented by ROI config periods
* ROI is calculated per segment and aggregated

### 8.4 Restrictions

* Disabled if roi_enabled is false
* Disabled for working IDs

---

## 9. Direct Income

### 9.1 Behavior

* One-time income per direct referral investment
* Stored in database

---

## 10. Level Income

### 10.1 Source

* Generated from downline ROI

### 10.2 Levels

* Up to configurable number of levels (default 20)

### 10.3 Computation

level_income = downline_roi × level_percentage

### 10.4 Nature

* Computed dynamically
* Not stored

---

## 11. Rank System

### 11.1 Behavior

* Rank achieved based on team business or matching
* Rank reward distributed over fixed duration (default 100 days)

### 11.2 Computation

earned = min(days_elapsed, duration) × (reward / duration)

---

## 12. Reward System

### 12.1 Behavior

* Milestone-based rewards
* Based on matching business
* Each milestone awarded once per user

### 12.2 Storage

* Stored upon achievement

---

## 13. Matching Engine

### 13.1 Leg Definition

* Each direct referral forms a real leg
* Virtual legs are created by admin

### 13.2 Leg Types

* Real leg: derived from downline investments
* Virtual leg: fixed value, system-generated

### 13.3 Computation

* Identify strongest leg (maximum value)
* Sum all other legs
* Matching value = minimum(strong_leg, other_legs)

---

## 14. Virtual Legs

### 14.1 Behavior

* Independent of real tree
* Created by admin
* May have expiry

### 14.2 Constraints

* Do not generate ROI
* Do not affect uplines
* Used only for matching and rewards

---

## 15. Team Business Rules

### 15.1 Inclusion

* Controlled by user flags
* Disabled users excluded

### 15.2 Level Restriction

* Contribution limited to specified number of levels

---

## 16. Cap System

### 16.1 ROI Cap

* ROI ≤ 2 × investment

### 16.2 Total Cap

* Total income ≤ 3 × investment

### 16.3 Scope

Includes:

* ROI
* Direct income
* Level income
* Rank income
* Reward income

---

## 17. Configuration System

All business rules must be configurable via database:

* Packages
* ROI configurations (time-based)
* Level percentages
* Reward milestones
* Rank definitions
* Eligibility conditions

---

## 18. Eligibility Engine

### 18.1 Purpose

Centralized validation for income eligibility

### 18.2 Interface

EligibilityEngine.check(user, income_type, context)

### 18.3 Examples

* ROI:

  * roi_enabled must be true
  * not a working ID

* Level income:

  * sufficient direct referrals
  * level unlocked

* Reward:

  * matching criteria met
  * not already rewarded

---

## 19. Internal Transfers

* User-to-user transfers supported
* Fee configurable (default 0%)

---

## 20. Computation Flow

Triggered during:

* Dashboard load
* Withdrawal

Sequence:

1. ROI calculation
2. Level income computation
3. Direct income retrieval
4. Rank income computation
5. Reward evaluation
6. Matching calculation
7. Cap enforcement

---

## 21. Admin Capabilities

* Approve/reject deposits
* Create admin deposits
* Manage packages and configs
* Add virtual legs
* Enable/disable ROI
* Block users
* Adjust balances through transactions
* Trigger rewards

---

## 22. User Dashboard Data

### Financial

* Deposits
* Investments
* Withdrawals

### Income

* ROI
* Direct income
* Level income
* Rank income
* Reward income

### Matching

* Strong leg
* Other legs
* Matching value

---

## 23. Testing Strategy

### 23.1 Phased Testing

1. Ledger validation
2. Investment handling
3. ROI engine
4. Tree structure
5. Team business propagation
6. Matching engine
7. Level income
8. Rewards
9. Rank distribution
10. Full integration

### 23.2 Load Testing

* Large user base (1k–10k users)
* Deep hierarchy
* Multiple concurrent operations

---

## 24. Design Constraints

* No cron-based earnings
* All financial actions must be logged
* All computations must be reproducible
* No mixing of virtual and real financial data
* Configuration must be externalized

---

## 25. Conclusion

This backend specification defines a scalable, dynamic, and configurable MLM system with strong separation of financial logic, computation layers, and administrative control. The architecture is designed for flexibility, auditability, and performance at scale.
