Module Documentation
v2.0
Lease Management Module
A comprehensive system for managing long-term lease agreements. This module handles the entire lifecycle from initial customer booking and credit verification to inventory processing, improved logistics delivery, and automated installment collection tracking.
Data Structure (ERD)
erDiagram
%% Core Lease Customer Entities
lease_customers {
bigint id PK
foreignId group_id FK
string customer_code
string customer_name
string mobile
string email
enum status
enum approval_status
foreignId created_by FK
timestamp created_at
timestamp updated_at
}
lease_customer_details {
bigint id PK
foreignId lease_customer_id FK
string caste
decimal monthly_income
string company
string department
string designation
string employee_code
string marital_status
date since_living
date since_working
string residential_phone
text residential_address
text office_address
string office_phone
text remarks
}
lease_customer_contacts {
bigint id PK
foreignId lease_customer_id FK
enum contact_type
string contact_value
enum contact_label
boolean is_primary
boolean is_active
}
lease_customer_documents {
bigint id PK
foreignId lease_customer_id FK
string doc_type
string file_path
}
lease_customer_cheques {
bigint id PK
foreignId lease_customer_id FK
bigint booking_id
string cheque_number
decimal amount
string status
}
lease_customer_openings {
bigint id PK
foreignId lease_customer_id FK
decimal opening_balance
}
lease_customer_accounts {
bigint id PK
foreignId lease_customer_id FK
string account_type
}
lease_customer_statuses {
bigint id PK
foreignId lease_customer_id FK
string type
text remarks
string approval_status
foreignId created_by FK
foreignId branch_id FK
foreignId approved_by FK
}
lease_customer_logs {
bigint id PK
foreignId lease_customer_id FK
foreignId user_id FK
foreignId branch_id FK
string action_type
string entity_type
bigint entity_id
text description
json old_values
json new_values
}
%% Guarantor Entities
lease_guarantors {
bigint id PK
string name
string father_name
string cnic
string occupation
string business_name
text residential_address
text business_address
string phone
string business_phone
string residential_phone
decimal monthly_income
string profile_image
string thumb_image
enum status
}
lease_customer_guarantors {
bigint id PK
foreignId lease_customer_id FK
foreignId guarantor_id FK
string relationship_type
text notes
}
%% Lease Procesing & Plans
item_plans {
bigint id PK
foreignId item_variant_id FK
foreignId branch_id FK
string item_plan_code
string name
text description
decimal installment_price
decimal installment_advance
integer duration_months
decimal processing_fee
decimal monthly_installment
decimal fine
date effective_date
boolean is_active
}
lease_processings {
bigint id PK
foreignId branch_id FK
foreignId lease_customer_id FK
foreignId item_plan_id FK
string processing_code
decimal processing_fee
decimal processing_advance
decimal principal_amount
decimal total_payable
date processing_date
date start_date
date end_date
enum status
enum payment_status
foreignId approved_by FK
foreignId created_by FK
text remarks
datetime cancelled_at
string cancellation_reason
}
lease_processing_items {
bigint id PK
foreignId lease_processing_id FK
foreignId item_variant_id FK
foreignId item_plan_id FK
decimal quantity
decimal unit_price
decimal discount
decimal tax_amount
decimal total_price
text remarks
}
customer_lease_processings {
bigint id PK
foreignId lease_processing_id FK
longText customer_image
longText customer_thumb_image
longText customer_signature
}
customer_guarantor_lease_processings {
bigint id PK
foreignId customer_guarantor_id FK
foreignId lease_processing_id FK
date date_added
}
%% Collections & Refunds
lease_collections {
bigint id PK
foreignId branch_id FK
foreignId lease_processing_id FK
foreignId delivery_voucher_id FK
string collection_number
integer installment_number
date due_date
decimal expected_amount
decimal paid_amount
date payment_date
enum payment_method
string reference_number
enum status
foreignId collected_by FK
foreignId created_by FK
timestamp posted_at
}
lease_refunds {
bigint id PK
foreignId branch_id FK
foreignId lease_processing_id FK
foreignId lease_customer_id FK
foreignId delivery_return_voucher_id FK
string refund_code
date refund_date
decimal processing_fee
decimal collected_payment
decimal deductions
decimal total_refund
enum refund_method
enum status
enum refund_reason
foreignId created_by FK
foreignId approved_by FK
foreignId processed_by FK
}
lease_refund_items {
bigint id PK
foreignId lease_refund_id FK
foreignId item_variant_id FK
decimal quantity
decimal unit_price
decimal line_total
enum disposition
}
%% Verification (CRC)
crc_verifications {
bigint id PK
foreignId branch_id FK
foreignId lease_processing_id FK
foreignId delivery_voucher_id FK
date verification_date
foreignId verified_by FK
enum status
enum operational_status
foreignId created_by FK
foreignId approved_by FK
}
crc_verification_remarks {
bigint id PK
foreignId crc_verification_id FK
text remarks
string attachment
foreignId created_by FK
}
%% Relationships
lease_customers ||--o{ lease_customer_details : "has"
lease_customers ||--o{ lease_customer_contacts : "has"
lease_customers ||--o{ lease_customer_documents : "has"
lease_customers ||--o{ lease_customer_cheques : "has"
lease_customers ||--o{ lease_customer_openings : "has"
lease_customers ||--o{ lease_customer_accounts : "has"
lease_customers ||--o{ lease_customer_statuses : "has updates"
lease_customers ||--o{ lease_customer_logs : "has logs"
lease_customers ||--o{ lease_customer_guarantors : "has guarantors"
lease_guarantors ||--o{ lease_customer_guarantors : "belongs to"
lease_customers ||--o{ lease_processings : "requests"
item_plans ||--o{ lease_processings : "defines terms"
lease_processings ||--o{ lease_processing_items : "contains"
lease_processings ||--o{ customer_lease_processings : "has digital details"
lease_processings ||--o{ customer_guarantor_lease_processings : "binds guarantor"
lease_customer_guarantors ||--o{ customer_guarantor_lease_processings : "signs"
lease_processings ||--o{ lease_collections : "generates"
lease_processings ||--o{ lease_refunds : "has refunds"
lease_refunds ||--o{ lease_refund_items : "contains"
lease_processings ||--o| crc_verifications : "requires"
crc_verifications ||--o{ crc_verification_remarks : "has"
High Level Workflow
flowchart LR
S1[1. Lease
Booking]:::booking --> S2[2. Item
Processing]:::processing
S2 --> S3[3. Lease
Delivery]:::delivery
S3 --> S4[4. Payment
Collection]:::collection
%% Styles
classDef booking fill:#3a244a,stroke:#7e529e,color:#fff
classDef processing fill:#1e4348,stroke:#428a94,color:#fff
classDef delivery fill:#262f4a,stroke:#58648c,color:#fff
classDef collection fill:#244a44,stroke:#529e94,color:#fff
classDef gl fill:#4a4424,stroke:#9e9452,color:#fff
classDef reporting fill:#243a4a,stroke:#527e9e,color:#fff
02 Processing Phase
flowchart LR
subgraph "Processing & Contract Stage"
B_START((From Booking Stage)) --> B1[Finalize items in the order
and select the Installment Plan]
B1 --> B2[System calculates final values:
- Principal Amount
- Total Interest
- Processing Fees
- Total Payable Amount]
B2 --> B3[System Generates Full Installment Schedule
Creates all future-dated records in INSTALLMENT_SCHEDULE table with status 'pending']
B3 --> B4[Generate formal contract document
with all terms and the full schedule]
B4 --> B5{Customer Reviews & Signs Contract?}
B5 -- Yes, Signs --> B6[Create INSTALLMENT_PROCESSINGS record
Update Status to 'Active'] --> C_START((To Delivery Stage))
B5 -- No, Rejects Contract --> R_START((Initiate Cancellation & Refund Process))
end
03 Delivery Phase
flowchart LR
subgraph "Logistics & Delivery Stage"
C_START((From Processing Stage)) --> C1[Allocate stock from inventory
for the items in the order]
C1 --> C2[Create DELIVERY record
Status: 'Scheduled']
C2 --> C3[Dispatch goods to customer
Update DELIVERY status to 'Dispatched']
C3 --> C4{Customer Acknowledges Receipt?
Proof of Delivery POD is signed}
C4 -- Yes, Full Delivery --> C5[Update DELIVERY status to 'Delivered'
This is the trigger!]
C4 -- Yes, Partial Delivery --> C6[Update DELIVERY status to 'Partially Delivered'
Log received items] --> C5
C4 -- No, Delivery Failed/Rejected --> C7[Log failure reason
eg, damaged goods, customer absent] --> C8{Retry or Cancel?}
C8 -- Retry --> C2
C8 -- Cancel --> R_START((Initiate Cancellation & Refund Process))
C5 --> C9["Activate the Installment Schedule
Set the 'start_date' for the first installment.
The financial obligation officially begins."] --> D_START((To Collection Stage))
end
04 Collection Phase
flowchart LR
subgraph "Collection Stage"
D_START((From Delivery Stage)) --> D1{Is there an upcoming installment due?}
D1 --> D3{Payment Received in Full by Due Date?}
D3 -- Yes --> D4[Update INSTALLMENT_SCHEDULE status to 'Paid'
Post GL entries: Dr. Cash, Cr. Receivable]
D3 -- Partial Payment Received --> D5[Update status to 'Partially Paid'
Log received amount] --> D_DUNNING((Initiate Dunning for Remainder))
D3 -- No Payment Received --> D6[Update status to 'Overdue'] --> D_DUNNING((Initiate Dunning Process))
D4 --> D7{Is this the final installment?}
D7 -- No --> D1
D7 -- Yes --> D8[Update main INSTALLMENT_PROCESSINGS status to 'Completed'
Send 'Paid in Full' notification to customer] --> D_END((End of Lifecycle))
end
05 Refunds (Pre-Delivery)
flowchart LR
subgraph "Cancellation & Refund Sub-Process"
R_START((Cancellation Requested)) --> R1{CRITICAL CHECK: Has Delivery Occurred?}
R1 -- Yes, Delivery is complete/partial --> R2[Refund Request REJECTED
Inform customer that post-delivery cancellations
are handled via Early Buyout or Return policies, not refunds.] --> R_END((End))
R1 -- No, Pre-Delivery --> R3[Calculate Refundable Amount
e.g., Advance Paid - Cancellation Fee]
R3 --> R4{Managerial Approval Required?}
R4 -- Yes --> R5{Manager Approves?}
R5 -- No --> R6[Inform customer of rejection reason] --> R_END
R4 -- No --> R7
R5 -- Yes --> R7
R7[Process payment to customer
Post GL entries: Dr. Advances, Cr. Cash/Bank]
R7 --> R8[Update status of BOOKING and/or
PROCESSINGS records to 'Cancelled'] --> R_END
end
Technical Architecture
System Design & Implementation
Detailed technical diagrams showing the internal architecture, service interactions, and domain models.
Lease Processing Creation Flow
Sequence diagram showing the service layer interactions
sequenceDiagram
autonumber
actor User as Staff User
participant LW as Livewire Component
(CreateProcessing)
participant Svc as LeaseProcessingService
participant Repo as LeaseProcessingRepository
participant Appr as ApprovalEngine
participant DB as Database
User->>LW: Submit Lease Application
LW->>LW: Validate Input
LW->>Svc: create(data)
activate Svc
Svc->>DB: Begin Transaction
Svc->>Repo: create(data)
activate Repo
Repo-->>Svc: returns LeaseProcessing (Draft)
deactivate Repo
Svc->>Appr: checkSetupExists('CREATE', LeaseProcessing::class)
alt Approval Setup Exists
Appr-->>Svc: Returns Setup ID
Svc->>Appr: createRequest(SetupID, RecordID)
Svc->>Repo: updateStatus(PENDING)
else No Approval Needed
Appr-->>Svc: Returns Null
Svc->>Repo: updateStatus(ACTIVE)
Svc->>Svc: fireCreateEvent()
end
Svc->>DB: Commit Transaction
Svc-->>LW: returns Result
deactivate Svc
LW-->>User: Show Success Notification
Lease Processing State Machine
All possible states and transitions throughout the lease lifecycle
stateDiagram-v2
[*] --> Draft : Staff Created
Draft --> Pending : Submitted for Approval
state Approval_Process {
Pending --> CRC_Verification : Initial Review
CRC_Verification --> CRC_Approved : Credit Check Passed
CRC_Verification --> CRC_Rejected : Credit Check Failed
}
CRC_Rejected --> Cancelled : Application Denied
CRC_Approved --> Active : Final Authorization
state Active {
[*] --> Unpaid_Advance
Unpaid_Advance --> Active_Lease : Advance Paid
Active_Lease --> Delinquent : Missed Payments
Delinquent --> Active_Lease : Arrears Cleared
}
Active --> Completed : All Installments Paid
Active --> Cancelled : Early Turnover/Default
Completed --> [*]
Cancelled --> [*]
Complete Lease Lifecycle
End-to-end process from customer onboarding to lease closure
flowchart TD
subgraph Onboarding["📋 Customer Onboarding"]
Start([Start]) --> RegCust[Register Lease Customer]
RegCust --> AddGuar[Add Guarantors]
AddGuar --> Docs[Upload Documents]
end
subgraph Verification["🔍 CRC Verification"]
Docs --> CRC{CRC Check}
CRC -- Verified --> SelectPlan[Select Item Plan]
CRC -- Failed --> Reject([Reject Customer])
end
subgraph Processing["⚙️ Lease Processing"]
SelectPlan --> AppForm[Create Lease Processing]
AppForm --> Validation{System Validation}
Validation -- Valid --> AppReq[Approval Request]
Validation -- Invalid --> AppForm
end
subgraph Execution["✅ Execution & Delivery"]
AppReq --> Manager{Manager Approval}
Manager -- Approved --> GenSched[Generate Collection Schedule]
Manager -- Rejected --> Notify[Notify Customer]
GenSched --> PayAdv[Collect Advance Payment]
PayAdv --> Deliver[Generate Delivery Voucher]
end
subgraph Collection["💰 Payment Collection"]
Deliver --> CollectLoop((Collection Loop))
CollectLoop --> PayInst[Receive Installment]
PayInst --> CheckBal{Balance 0?}
CheckBal -- No --> CollectLoop
CheckBal -- Yes --> CloseLease[Close Lease]
end
CloseLease --> End([End])
Notify --> End
Domain Model (Class Diagram)
Core entities and their relationships in the Lease domain
classDiagram
namespace LeaseDomain {
class LeaseCustomer {
+string code
+enum status
+details() HasOne
+guarantors() HasMany
}
class LeaseProcessing {
+decimal principal_amount
+decimal total_payable
+customer() BelongsTo
+items() HasMany
+collections() HasMany
}
class ItemPlan {
+decimal installment_price
+int duration_months
+decimal processing_fee
}
class LeaseCollection {
+decimal expected_amount
+date due_date
+markAsPaid()
}
class CRCVerification {
+date verification_date
+enum status
+enum operational_status
+remarks() HasMany
}
}
LeaseCustomer "1" *-- "1..*" LeaseProcessing : requests
LeaseProcessing "1" -- "1" ItemPlan : based on
LeaseProcessing "1" *-- "*" LeaseCollection : generates
LeaseProcessing "1" -- "0..1" CRCVerification : verified by
Note: LeaseProcessing serves as the central Aggregate Root for the lease module, coordinating all related entities and business rules.
CRC Verification System
Credit Risk Check verification workflow and entity details
crc_verifications
| Column | Type | Description |
|---|---|---|
| id | bigint | PK |
| lease_processing_id | foreignId | FK |
| delivery_return_voucher_id | bigint | FK (nullable) |
| verification_date | date | Date of verification |
| verified_by | foreignId | FK User |
| status | enum |
PENDING
APPROVED
AWAITING_UPDATE
REJECTED
|
| operational_status | enum |
pending
verified
unverified
|
crc_verification_remarks
| Column | Type | Description |
|---|---|---|
| id | bigint | PK |
| crc_verification_id | foreignId | FK |
| remarks | text | Verification notes |
| attachments | string | File path/URL |
| created_by | foreignId | FK User |
Key Business Rules
- CRC Verification is only visible/accessible for lease processings that have been delivered.
-
Status flow:
PENDING → APPROVED/REJECTEDwith approval workflow support. - Multiple remarks with attachments can be added to track verification history.