# Real Estate ERP

Help Center v1.0

## 1. Introduction & Getting Started

### Purpose of this ERP

The Real Estate ERP is a comprehensive, enterprise-grade application designed to completely automate and manage a real estate development or property management business. It acts as the central source of truth for everything from Lead Generation and Customer Registration, to Plot Bookings, Installment Tracking, Financial Ledgers, and Agent Commissions.

It solves the business problems of duplicate record-keeping, manual balance miscalculations, lost leads, delayed recoveries, and double-bookings by tightly coupling the Sales workflow with the Financial workflow.

### Who Should Use It?

This system is built for a multi-role organization. Management uses the system for high-level oversight via Dashboards and AI Reports. Sales Agents use it for lead tracking. Accounts departments use it for ledger maintenance and receipt generation. Recovery officers use it to track defaulters.

## 2. User Roles & Permissions

The system enforces strict access control through a robust Role-Based Access Control (RBAC) architecture. There are 11 core roles defined in the system.

Role Name | Purpose & Responsibilities | Key Permissions | Restrictions
--- | --- | --- | ---
Super Admin | System Owner. Full oversight of all configurations, settings, master data, users, and financials. | Manage settings, roles, users, AI reports, full edit capabilities. | None. (Use with extreme caution).
Sales Manager | Oversees the sales team, pipeline, and booking approvals. | Assign leads, view team sales dashboards, approve initial bookings. | Cannot edit financial settings or approve payments.
Sales Agent | Frontline sales staff handling leads and creating bookings. | Manage own leads, create bookings, upload customer documents. | Cannot approve bookings, edit properties, or see other agents' leads.
Accountant | Manages the ledger, receipts, installments, and recovery. | Approve transactions, generate receipts, view financial dashboards, log expenses. | Cannot delete approved transactions or modify property master data.
Data Entry | Digitizes historical data or paper forms. | Add customers, leads, upload documents. | Cannot approve or delete anything.
Customer (Portal Access) | End-user / Property Buyer. | Access Customer Portal, view their booked properties, check installment plans, upload payment proofs, download receipts, and view AI-driven property recommendations. | Read-only access to their own data, plus ability to upload payment proofs.

## 3. Dashboard

The main dashboard serves as the central intelligence hub, aggregating data across the ERP in real-time.

### Key Metrics (Widgets)

- Total Sales: The lifetime value (Total Price) of all active and approved bookings.
- Actual Collections: The sum of all approved payments/transactions (cash or bank) logged in the system.
- Defaulters: Count of customers flagged by the system whose installments are severely overdue.
- Gross Profit: Calculated as Actual Collections minus Total Paid Agent Commissions.

Note: The Financial Dashboards are only visible to Super Admin and Accountant roles.

## 4. Lead Management

The Lead Management module is where the sales journey begins. A Lead is a prospective buyer.

### Lead Workflow

Workflow: Lead Created → Assigned to Agent → Follow-ups Logged → Qualified → Converted (Becomes a Customer) OR Lost

### Create Lead Form Fields

Field | Required? | Type | Purpose & Business Logic
--- | --- | --- | ---
Full Name | Yes | Text | Legal name of prospect.
Phone | Yes | Text | Used for WhatsApp alerts and contact. Must be unique to prevent duplicate leads.
Lead Source | Yes | Dropdown | Configurable in Master Data (e.g. Facebook, Walk-in).
Status | Yes | Dropdown | New, Contacted, Qualified, Lost. Determines pipeline stage.
Assigned Agent | No | Dropdown | Links lead to a specific salesperson. That agent will see it on their dashboard.

### Actions

- Convert to Customer: If a lead is ready to buy, clicking this button automatically ports their data into the Customer table, generates a portal login password, and marks the lead as 'Converted'. It prevents duplicate data entry.

## 5. Customer Management

Customers are verified individuals who have purchased or are in the process of purchasing a property.

### Customer Profile & Fields

Field | Required? | Type | Purpose & Business Logic
--- | --- | --- | ---
CNIC / Passport Number | Yes | Text | Primary unique identifier for a customer. Used heavily in the printing of booking forms and ledgers.
Membership Number | No | Text | Optional internal ID.
Is Defaulter | System | Boolean | Read-only. Automatically set to True by the system if installments are > 30 days overdue. Displays a red alert on their profile.
User Account | System | Relation | The system automatically provisions a user account linked to the customer for Portal login.

### Document Verification (Rule 11)

Customers are required to upload mandatory KYC documents (CNIC copy, photos). Management must Verify or Reject these documents. An AI check runs in the background to flag bookings lacking verified documents.

## 6. Property Inventory (Projects & Blocks)

This module manages the core product of the ERP: the real estate inventory hierarchy.

### Hierarchy

Project (e.g. Blue World) → Block (e.g. Overseas Block) → Property/Plot (e.g. Plot # 45)

### Property Status & Duplicate Sale Prevention

Duplicate Sale Prevention: A property has a strict Status field (Available, Reserved, Booked, Sold, Transferred). The system hard blocks the creation of a booking if a property is NOT 'Available'.

### Property Fields

Field | Required? | Type | Purpose & Business Logic
--- | --- | --- | ---
Plot Number | Yes | Text | Unique identifier within a block.
Property Type | Yes | Dropdown | Commercial, Residential, Villa, etc.
Size | Yes | Dropdown | e.g. 5 Marla, 10 Marla.
Base Price | Yes | Currency | The original price of the plot.

### Dynamic Pricing (Rule 12)

Admins can revise the `Base Price` of a property at any time. When this happens, a record is written to the Property Price History table. Old sales and active bookings are completely unaffected because the booking table locks in the agreed price at the time of sale.

## 7. Bookings & Sales Workflow

This module connects a Customer to a Property, creating a financial contract.

### Sales Workflow

Customer Selects Available Property → Sales Agent Creates Booking → Down Payment is Logged as 'Pending' Transaction → Booking Status = 'Active' (Property Status = 'Booked') → Accountant Approves Transaction → Ledger Updated → WhatsApp Alert Sent

### Booking Fields

Field | Type | Purpose & Business Logic
--- | --- | ---
Customer | Relation | The buyer.
Property | Relation | The unit being sold. Must be Available.
Agent | Relation | Who made the sale (for commissions).
Total Price | Currency | Locked in at time of sale.
Discount | Currency | Subtracts from Total Price. AI will flag if discount > 15%.
Net Price | System Calc | Total Price - Discount. The actual amount the customer owes.

## 8. Payments, Receipts & Ledger Logic

The financial core of the ERP. All money movement is tracked here.

### Smart Balance Engine (Rule 2)

The system calculates outstanding balances dynamically based on the formula:

Outstanding Balance = (Net Price) - (Sum of all APPROVED Transactions)

Manual entry of remaining balance is strictly disabled to prevent fraud or human error.

### Payment Intelligence (Rule 6)

Payment Validation: When a user tries to log a payment, the system verifies if the payment amount exceeds the Outstanding Balance. If it does, the payment is blocked unless explicitly marked as an "Advance Payment".

### Ledger Automation (Rule 14)

The moment an Accountant clicks Approve on a Transaction:

1. A double-entry record is created in the Ledger (Debit Cash/Bank, Credit Customer Account).
2. The related Invoice is marked as 'Paid'.
3. A PDF Receipt is generated with a unique sequential Receipt Number.
4. A WhatsApp "Payment Received" notification is dispatched to the customer.
5. Agent Commission is automatically calculated.

## 9. Installment Plans

Manages scheduled future payments (receivables) for a booking.

### Creating a Plan

When a booking is made, an installment plan can be generated. You can select standard frequencies (Monthly, Quarterly, Bi-Annually) and the system will automatically divide the Outstanding Balance across the requested duration.

### Installment Tracking (Rule 3)

Installments have dynamic statuses: Pending, Partial Paid, Paid, Overdue.

A background cron job runs daily to check due dates. If an installment is past due, its status flips to 'Overdue' and a Late Surcharge is calculated (configurable % per day late). Management has the option to 'Waive' this surcharge during payment collection.

## 10. Recovery & Outstanding Management

Ensuring timely payments is critical. This module handles overdue accounts.

### Defaulter Detection (Rule 4)

A daily automated background job (`CheckDefaulters`) scans all installments. If a customer has an installment that is overdue by X days (configurable in Settings, default 30), the system:

- Flags the Customer Profile as Defaulter (shows a red badge across the ERP).
- Sends an automated WhatsApp alert to the customer regarding their severe overdue status.
- Surfaces the customer in the AI Recommendations dashboard under "High-Risk".

## 11. Commission Management

Manages payouts to internal Agents and external Dealers.

### Smart Commission Logic (Rule 10)

Commissions are calculated based on Actual Payments Received, not just on the total booking value. This protects the company from paying out full commissions on cancelled or unpaid bookings.

When an Accountant approves a payment transaction, the system checks the Agent linked to the booking, reads their Commission Percentage from their Profile (or Settings), and calculates their cut of that specific payment. It is logged in the Commission table as 'Unpaid'. The finance team can later mark it as 'Paid' when funds are disbursed.

## 12. Agents, HR & Follow-ups

### Agent Profiles

Stores employee details, contact info, and their assigned Commission rate. Agents can log in to view their personal dashboards containing their leads, sales, and earned commissions.

### Follow-ups & Tasks

Agents log their interactions (Calls, Meetings, WhatsApp) with Leads in the Follow-ups module. Management can view the Follow-up history to gauge agent performance and lead engagement.

### Attendance

A simple check-in/check-out system for HR to track daily agent presence.

## 13. Reports & AI Builder

### Dynamic Drag & Drop Report Builder (Rule 19)

Instead of relying entirely on fixed reports, the ERP features a powerful custom report generator.

1. Navigate to Reports → Create Custom Report.
2. Select a Module (e.g. Customers, Bookings, Leads).
3. Use the Drag and Drop interface to select exactly which columns to include and in what order.
4. Apply quick filters (e.g. Status = Overdue).
5. Save and Export to CSV.

### AI Recommendations Dashboard (Rule 20)

Located at `/ai-recommendations`, this dashboard proactively surfaces risks and anomalies. It currently detects:

- High Risk Defaulters: Customers overdue by > 60 days.
- Missing Documents: Active bookings that lack mandatory uploaded documents.
- Unusual Discounts: Bookings where the applied discount exceeds 15% of the total property price.

## 14. Audit Trail & Security (Rule 15)

### Activity Logs

The system utilizes `Spatie\Activitylog` to track every change made to core modules (Leads, Customers, Properties, Bookings, Transactions, etc.).

Navigate to Activity Logs (Super Admin only) to view a complete historical record of Who changed What and When. The interface highlights the exact fields that were modified, showing the Old Value vs. the New Value.

### Security Restrictions

- Manual ledger balance updates are strictly disabled at the code level.
- Property Status transitions are strictly gated to prevent double-booking.
- Agents cannot view other agents' leads.

## 15. Settings & Master Data

### Settings Module

Used to configure global system parameters. It manages key-value pairs stored in the database.

Setting Key | Purpose
--- | ---
Company Name/Logo | Appears on PDF Receipts and Dashboard.
Defaulter Days | Number of days overdue before a customer is flagged (default 30).
WhatsApp API Credentials | Client ID and Client Secret for wasender.online.
WhatsApp Template IDs | The specific template IDs used for Booking Approvals, Payment Receipts, and Defaulter Alerts.

### Master Data

Used to populate dropdowns across the ERP (e.g. Lead Sources, Property Types). Adding a new Lead Source here will immediately make it available in the Lead Creation form.

## 16. Automations & WhatsApp (Rule 18)

### WhatsApp Integration

The ERP is integrated with the `wasender.online` API. It automatically dispatches messages without human intervention.

Triggers:

- Booking Approved: Fired in `BookingController@store`.
- Payment Received: Fired in `TransactionController@approve`. Contains Customer Name and Amount Paid.
- Defaulter Alert: Fired by the nightly `CheckDefaulters` command. Contains Customer Name, Days Overdue, and Amount Due.

## 17. Complete Business Workflows

### Lead to Sale Workflow

Lead Created → Assigned to Agent → Converted to Customer → Property Selected → Booking Form Submitted

### Payment to Ledger Workflow

Customer Pays → Agent Logs Pending Transaction → Accountant Approves → Double Entry Ledger Logged → PDF Receipt Sent

## 22. AI & Smart Rules

### Customer AI Recommendations

The system uses basic intelligence to suggest properties to customers inside the Customer Portal based on their profile and available inventory, improving upselling.

### High-Risk Defaulter Detection

Rule: Automatically flags customers who have an installment overdue by more than 60 days. This allows the collection team to prioritize calls and surfaces them on the admin AI Dashboard.

### Missing Documents & Anomalies

The system also continuously scans for active bookings that have no uploaded KYC documents or bookings that have unusually high discounts (>15%). These are highlighted for admin review.

## Troubleshooting & FAQ

#### Q: Why can't I create a booking for a specific plot?

A: The property status must be exactly `Available`. If it is `Booked` or `Sold`, the system blocks the creation to prevent duplicate sales.

#### Q: The payment amount is being rejected, why?

A: The Payment Validation rule checks the outstanding balance. You cannot log a payment that exceeds what the customer owes, unless you specifically check the "Is Advance" checkbox.

#### Q: How do I change an Approved transaction?

A: You cannot modify an approved transaction. It is permanently written to the immutable ledger. If an error occurred, a Super Admin must delete it or a reversing journal entry must be posted.