Industry Context & Market Problem
The plotted real estate and land distribution sector across peri-urban and tier-2/tier-3 growth corridors relies heavily on multi-tiered agency networks, independent channel partners, and field brokers. However, typical real estate developers face catastrophic operational losses resulting from fragmented, manual record-keeping, unverified commission assertions, and chaotic paper-based EMI tracking.
The Fragmented MLM & Sales Bottleneck
Traditional developers manage booking registers in physical diaries or decentralized spreadsheets. When a plot is token-booked by an agent across town, other field brokers continue pitching the same unit. Worse, multilevel commissions (often extending 5 to 9 tiers up the sponsor hierarchy) are tabulated by manual accounting staff at the end of each month. This leads to rampant disputes over who registered a client first, unauthorized brokerage rates, and double disbursements that drain project margins.
The 60-Month Financing Void
Plotted township developers offer long-term direct financing (e.g., 60-month EMI schemes) to attract middle-income buyers. Without an automated installment engine, calculating dynamic grace periods, progressive late fines, cumulative payments, and remaining principal balances becomes unmanageable at scale.
The MLM Software Solution
MLM Software merges cadastral plot inventory management with an automated 9-level binary genealogy engine, a 60-month installment collection system, an immutable payout ledger, and an identity/KYC security vault into a single unified command platform.
Target Personas & Access Control Hierarchy
The platform enforces strict Role-Based Access Control (RBAC) via stateless JWT tokens to ensure complete data isolation.
Super Admin
Role Code: super_admin
Key Responsibilities: Overall platform governance, land inventory, commission overrides, bank approval, batch payouts.
Platform Interfaces & Capabilities: Full access to all 12 Administrative consoles, system settings, activity audit trails, and SQL ledger overrides.
Field Distributor
Role Code: distributor
Key Responsibilities: Client plot presentations, downline expansion, tracking binary tree nodes, withdrawal requests.
Platform Interfaces & Capabilities: Personal distributor portal, interactive genealogy tree (ReferralTree.jsx), wallet balance dashboard.
Land Buyer / Customer
Role Code: customer
Key Responsibilities: Purchasing residential plots, monitoring 60-month EMI balances, downloading payment receipts.
Platform Interfaces & Capabilities: Customer personal dashboard, payment history modals, EMI installment passbook, customer support ticketing.
Finance & Audit Officer
Role Code: finance_staff
Key Responsibilities: Verifying KYC documents, auditing bank details, processing bank transfer payout sheets.
Platform Interfaces & Capabilities: Restricted admin access: KYC Approvals, Bank Update Requests, Commission Reports, and Payout Export engines.
Visual Module Breakdown & Live Console Audits
This section details every administrative console screen in the live MLM Software production deployment. Each module is documented with its user interface controls, underlying calculations, and data validations.
Executive Command Center & Network Health
Executive Dashboard showing 6 KPI metric widgets, state-wise density, and dynamic genealogy visualizer.
Operational Purpose:
Acts as the central cockpit for executive leadership to assess business health, network expansion velocity, total revenue inflow, and pending settlement obligations in real time.
KPI Widget Architecture:
- Total Users (34): Cumulative registered distributor and buyer records across the database.
- Verified KYC (21): Accounts with verified PAN, National ID, and bank details authorized for payouts.
- Total Revenue (■0.00): Net cash collected from property advances, full settlements, and EMI receipts.
- Commission Paid (■0.00): Gross multi-tier referral bonuses and binary incentives disbursed to date.
- Pending KYC (0): Submissions awaiting compliance audit before account unlocking.
- Pending Payouts (■0.00): Unprocessed withdrawal requests in the ledger queue.
State Distribution & Binary Visualizer:
The right panel displays geographic distributor density (e.g., Tamil Nadu: 34 active accounts). The bottom Network Genealogy Overview tool allows administrators to enter any distributor ID (e.g., spart00004) and click Visualize to dynamically render their binary downline tree.
User Management
Figure 2: Master user registry tracking legal names, internal distributor IDs, upline sponsor references, and verification flags.
Operational Purpose:
Centralized administrative directory for monitoring, filtering, onboarding, and auditing all network distributors and retail customer accounts.
Data Column Specifications:
- USER: Full legal name, system-generated avatar, and registered contact email (e.g., nasula1999@gmail.com).
- ID: Immutable system distributor code (e.g., spart00010) used in tree traversal.
- REFERRAL: Immediate upline sponsor code (e.g., spart00005) defining lineage.
- JOIN DATE: Timestamp of profile registration (e.g., 16/07/2026).
- KYC STATUS: Real-time compliance badge (Verified vs. Not Submitted).
- STATUS: Account activation state (Active vs. Suspended).
Administrative Actions:
Administrators can filter by KYC status or account status, search across names and IDs, export the full database to CSV, or click inline actions to inspect downlines, edit credentials, or suspend fraudulent accounts.
KYC Verification & Compliance Vault
Dedicated multi-stage identity verification vault for evaluating PAN, National ID, and bank account proofs.
Operational Purpose:
Enforces fiscal and tax compliance (including TDS reporting) by verifying distributor identity before releasing commission withdrawals.
Queue Toggles & Audit Parameters:
The console organizes submissions into 4 filtered tabs: Pending (0), Approved (20), Suspended (1), and Rejected (0). Each incoming request requires administrative verification across 4 mandatory checkpoints:
- Business Details: Corporate trade name, registration certificates, and verified operational address.
- PAN Document: Permanent Account Number file upload checked against tax records for TDS compliance.
- National ID: Government identity document verified against the user's registered name.
- Bank Account Details: Account number and IFSC code verification for payout processing.
Buying Requests
Inbound plot purchase interest pipeline and booking conversion management desk.
Operational Purpose:
Manages the property sales pipeline, tracking incoming plot purchase inquiries from distributors and prospective buyers.
Pipeline Workflow:
Distributors submit purchase requests on behalf of buyers through the product catalog. These requests appear in the Pending Interest queue. Administrators can review buyer identity, verify earnest money deposits, confirm plot availability, and transition bookings into either full property settlements or active 60-month EMI payment schedules.
Comission Report
Master commission ledger tracking real estate sales transactions and multi-tier payout allocations.
Operational Purpose:
Provides transparency into multi-level commission payouts, tracking bonus allocations across up to 9 sponsorship levels.
Mathematical Distribution Logic:
When a property sale or installment payment clears, the backend traverses upward through 9 parent nodes:
Total Commission Distributed = SUM (Sale Volume × Level Tier Li%) for i=1 to 9
The Revenue & Payout Ledger records every transaction reference, buyer identity, gross property value, and exact commission credits. Administrators can refresh logs in real time or click Export Detailed CSV for monthly tax filings and external audits.
Commission Payouts & Settlement
Batch settlement desk showing pending payouts, user counts, bank export utilities, and confirmation import tools.
Operational Purpose:
Facilitates bank transfers by compiling approved distributor withdrawal requests into banking-ready batch files.
Two-Phase Settlement Workflow:
- Phase 1 (Export & Banking): The system aggregates pending requests (Total Pending: Rs. 0 across Users to Pay: 0). Administrators click Export Excel to download a batch payment file containing beneficiary account numbers, IFSC codes, and net transfer amounts for processing via corporate net banking.
- Phase 2 (Reconciliation & Import): Once the bank processes the transfers, administrators click Import Paid to upload the bank's confirmation file, automatically updating all ledger entries to 'Completed' status.
Bank Update Security Vault
Security checkpoint holding distributor bank account changes for administrative review.
Operational Purpose:
Prevents account hijacking and unauthorized payout diversion by intercepting distributor bank account modifications.
Security Protocol:
When a distributor updates their banking details, the change is intercepted and routed to the Bank Update Requests queue. The user's active payout profile remains locked to their existing verified bank details. Administrators cross-reference submitted cancel cheques or bank passbooks with the user's verified identity documents before approving the change.
60-Month EMI & Installment Management
Long-term property installment tracker displaying plan states, collection efficiency, and late penalty fines.
Operational Purpose:
Governs extended 60-month land installment financing schemes, monitoring collection rates and calculating late payment penalties.
Portfolio Metrics & Fine Engine:
- Active Plans: Number of buyers currently paying down 60-month installment contracts.
- Overdue: Accounts that have missed monthly payment deadlines.
- Completed: Fully settled contracts eligible for title deed registration.
- Collection %: Monthly collection efficiency against scheduled installment targets.
- Total Fines (■0.00): Automated late fees applied to delinquent accounts, accessible via the View Fines audit ledger.
Property Inventory & Land Catalog
Real estate catalog manager for configuring land parcels, boundaries, pricing, and MLM eligibility.
Operational Purpose:
Central inventory console for managing available land developments, plot configurations, and pricing structures.
Inventory Configuration Controls:
Administrators use the + Add New Land button to register new township phases. Parameters include Plot ID, dimensions (sq.ft.), boundary facing (North/East/West/South), base rate per sq.ft., total price, eligible MLM commission allocations, and financing terms (e.g., standard 60-month EMI schemes).
Withdrawal Processing & Cash Settlements
Payout processing console for handling distributor wallet withdrawals and manual cash disbursements.
Operational Purpose:
Manages distributor wallet balance redemptions, tracking requests from submission through settlement.
Operational Workflow:
Displays metrics for Pending Requests (0), Processed (0), and Pending Amount (■0.00). Administrators can process standard bank payouts or click $ Manual Cash Payout to record direct over-the-counter settlements into the permanent audit ledger.
Support Ticket
Analytics console featuring date-range filters, quick presets, and multi-perspective reporting.
Operational Purpose:
Generates consolidated business intelligence reports across sales, distributor productivity, and financial flows.
Filter Parameters & Perspectives:
Includes date-range selectors (From: dd-mm-yyyy To: dd-mm-yyyy) and quick presets (30 Days, 45 Days, 90 Days), with an optional Limit to Last 30 Records toggle.
- Platform Reports: High-level sales conversion rates and operational metrics.
- User Report: Downline productivity and commission earnings per distributor.
- Detailed Financials: Balance ledger covering collections, disbursements, and pending reserves.
- Custom Report: Custom parameter queries matching specific date ranges, user tiers, or property phases.
Reports & Business Analytics Suite
Figure Analytics console featuring date-range filters, quick presets, and multi-perspective reporting.
Operational Purpose:
Allows marketing administrators to create and broadcast promotional campaigns, festival discounts, and conversion incentives.
Campaign Metrics & Creation Suite:
Tracks campaign performance across 4 KPI cards: Total Offers (0), Active (0), Inactive (0), and With Discount (0). Administrators click + New Offer to configure campaign titles, promotional badges, percentage-based or flat cash discounts, validity periods, and target plots. Active promotions are broadcast directly to user dashboards.
Mathematical Pricing & 60-Month EMI Valuation Engine
Property pricing incorporates base square footage rates, Preferential Location Charges (PLC), and installment schedules across 60 monthly installments.
Gross Property Valuation Formula:
Gross Property Value = (Area in Sq.Ft. × Base Rate per Sq.Ft.) + PLC Charges
| Plot Dimension & Classification | Area (Sq.Ft.) | Base Rate | Total Value | Down Payment (20%) | 60-Month EMI |
|---|---|---|---|---|---|
| Standard Residential (30x40 ft) | 1,200 | ■2,000 | ■24,00,000 | ■4,80,000 | ■32,000 / mo |
| Medium Residential (30x50 ft) | 1,500 | ■2,500 | ■37,50,000 | ■7,50,000 | ■50,000 / mo |
| Executive Corner Plot (40x55 ft) | 2,200 | ■2,500 | ■55,00,000 | ■11,00,000 | ■73,333 / mo |
Late Penalty Fine Calculation:
Installments unpaid after the monthly due date enter delinquency status. The system applies late penalty charges calculated as:
Late Penalty Fine = Installment Amount × (Penalty Rate / 100) × (Days Overdue / 30)
Fines accumulate daily until the installment is cleared and are viewable in the Fine Summary Ledger (FineSummaryCard.jsx).
Architecture & DevOps
Relational Database Schema & System Architecture
7. Production DevOps, Container Ingress & Operational Runbook
6
Relational Database Schema
The platform uses an asynchronous SQLAlchemy engine on PostgreSQL. The schema isolates financial ledgers, genealogical downlines, and identity verification documents.
| Table Name | Primary / Foreign Keys | Key Attributes & Business Schema |
|---|---|---|
| users | id UUID PK sponsor_id UUID FK (self) |
email (UNIQUE), password_hash, first_name, distributor_id (UNIQUE), role, is_active, created_at. |
| products | id UUID PK | title, plot_number, dimensions, area_sqft, base_price, emi_eligible (Boolean), status. |
| emi_records | id UUID PK user_id FK, product_id FK |
total_tenure_months (60), monthly_due, paid_months, balance_amount, overdue_status, accumulated_fines. |
| transactions | id UUID PK user_id FK |
reference_id (UNIQUE), amount, type (COMMISSION, EMI_PAYMENT, WITHDRAWAL), status, payout_batch_id. |
| kyc_records | id UUID PK user_id FK |
pan_number, id_document_url, bank_name, account_number, ifsc_code, status (PENDING/APPROVED). |
| bank_updates | id UUID PK user_id FK |
requested_account_number, requested_ifsc, passbook_url, approval_status, admin_reviewer_id FK. |
| offers | id UUID PK | title, badge_text, discount_percentage, is_active, expires_at, target_plot_ids. |
| activity_logs | id UUID PK actor_user_id FK |
action_type, entity_affected, old_state_json, new_state_json, ip_address, timestamp. |
7
Production DevOps & Container Ingress
The application deploys in isolated Docker containers managed via Docker Compose and an Nginx reverse proxy.
Container Ingress Architecture:
• Port 80/443 (Nginx Web Proxy): Terminates SSL, serves static React 19 production chunks, and routes /api/* traffic.
• Port 8000 (FastAPI Backend Service): Handles REST API requests, executes business logic, and manages authentication via Uvicorn.
• Port 5432 (PostgreSQL 16 Database): Stores application data with schema migrations managed by Alembic.
• Port 80/443 (Nginx Web Proxy): Terminates SSL, serves static React 19 production chunks, and routes /api/* traffic.
• Port 8000 (FastAPI Backend Service): Handles REST API requests, executes business logic, and manages authentication via Uvicorn.
• Port 5432 (PostgreSQL 16 Database): Stores application data with schema migrations managed by Alembic.
Standard Production Commands
| Command Syntax | Operational Function |
|---|---|
| docker-compose up --build -d | Builds and launches all application containers in detached background mode. |
| docker-compose ps | Verifies the operational health and uptime status of all running containers. |
| docker-compose logs -f backend | Streams real-time FastAPI backend logs for monitoring and debugging. |
| docker-compose exec backend alembic upgrade head | Applies all pending database migrations to the PostgreSQL database. |
| bash backup.sh | Executes an automated database dump and saves a compressed backup file. |
Operational Glossary & Terminology
| Term | Definition in MLM Software Context |
|---|---|
| Binary Tree Lineage | A hierarchical distributor structure where every node sponsors left and right downlines, used to calculate multi-tier bonuses. |
| 9-Level Commission | A multi-tier compensation model distributing sales bonuses across up to 9 upline sponsorship levels. |
| 60-Month EMI Plan | A structured financing option that divides property purchases into 60 monthly installments. |
| Late Penalty Fine | Automated penalty charges applied to delinquent installment accounts based on days overdue. |
| KYC Approvals Vault | A compliance document repository storing identity and tax records (PAN, National ID) required before processing payouts. |
| Bank Update Queue | A security checkpoint holding bank detail changes for administrative review before updating disbursement accounts. |
| Offers Engine | The administrative module for scheduling promotional discounts, festival schemes, and conversion badges across catalog properties. |
| Platform Reports | Aggregated analytical summaries evaluating network health, collections, and commission liabilities across configurable timeframes. |
MLM Software Developers & Network Systems
Enterprise Real Estate MLM & Cadastral Operations ERP · Operational System Manual v1.0.0 · Proprietary & Confidential