Loan & Debt Tracking
Relevant source files
The following files were used as context for generating this wiki page:
- app/src/main/java/io/github/mojri/hesabyar/domain/usecase/ManageLoanUseCase.kt
- app/src/main/java/io/github/mojri/hesabyar/ui/LoanViewModel.kt
- app/src/main/java/io/github/mojri/hesabyar/ui/screens/LoanManagementScreen.kt
- rust/hesabyar-core/src/dashboard.rs
- rust/hesabyar-core/src/analytics.rs
- rust/uniffi/hesabyar_core/uniffi/hesabyar_core/hesabyar_core.kt
- app/src/main/java/io/github/mojri/hesabyar/api/BudgetAdvisor.kt
The Loan & Debt Tracking module is a core financial component of the Hesabyar application designed to manage personal liabilities and credits. It allows users to track money borrowed from or lent to individuals, manage repayment histories, and monitor the overall financial balance with different persons. This system supports two primary debt orientations: Debtors (people who owe the user money) and Creditors (people the user owes money to).
Sources: README.md, app/src/main/java/io/github/mojri/hesabyar/domain/usecase/ManageLoanUseCase.kt:7-13
Architecture and Data Flow
The module follows a clean architecture pattern where the UI interacts with a LoanViewModel, which delegates business logic to the ManageLoanUseCase. Data persistence and retrieval are handled by the HesabyarRepositoryInterface.
The data flow ensures that any changes to loans (addition, repayment, or deletion) are immediately reflected in the all-time balance and analytics.
Sources: app/src/main/java/io/github/mojri/hesabyar/ui/LoanViewModel.kt:15-22, app/src/main/java/io/github/mojri/hesabyar/domain/usecase/ManageLoanUseCase.kt:15-20
Data Models
The system defines loans and debt-related entities with specific fields to track original versus remaining amounts and settlement status.
Loan Entity
| Field | Type | Description |
|---|---|---|
id | Long | Unique identifier for the loan entry |
personName | String | Name of the person involved in the debt |
loanType | String | Orientation of the debt: DEBTOR or CREDITOR |
originalAmount | Long | The initial amount of money borrowed or lent |
remainingAmount | Long | Current balance after repayments |
isSettled | Boolean | Flag indicating if the debt has been fully paid |
date | Long | Timestamp of the loan creation |
Sources: rust/uniffi/hesabyar_core/uniffi/hesabyar_core/hesabyar_core.kt:1010-1019, rust/hesabyar-core/src/dashboard.rs:118-128
Debt Summary and Progress
The system calculates progress for each debt entry to visualize how much of the original amount has been repaid.
Core Logic and Computations
Aggregate Calculations
The Rust core calculates global debt and credit totals by filtering unsettled loans.
- Debtors Total: Sum of
remainingAmountfor all unsettled loans whereloanType == "DEBTOR". - Creditors Total: Sum of
remainingAmountfor all unsettled loans whereloanType == "CREDITOR".
Sources: rust/hesabyar-core/src/dashboard.rs:94-110, rust/hesabyar-core/src/analytics.rs:114-116
Debt-to-Income Ratio
A critical financial health metric computed by the system is the Debt-to-Income Ratio. This calculation combines loan repayments with monthly installments to assess the user's financial burden relative to their income.
Use Case Operations
The ManageLoanUseCase provides the following operations to the UI layer:
- Add Loan: Creates a new
Loanentity. TheremainingAmountis initially set equal to theoriginalAmount. - Make Repayment: Calls
repository.addPaymentToLoan, which typically creates aPaymentHistoryentry and decrements theremainingAmountof the associated loan. - Get Payment History: Provides a
FlowofPaymentHistoryfor a specificloanId. - Settle/Update/Delete: Standard CRUD operations to maintain the debt list.
Sources: app/src/main/java/io/github/mojri/hesabyar/domain/usecase/ManageLoanUseCase.kt:15-41, app/src/main/java/io/github/mojri/hesabyar/ui/LoanViewModel.kt:24-60
Integration with Analytics
The Loan module feeds into the broader Analytics system. The compute_analytics function in the Rust core generates a DebtSummary for both debtors and creditors, which includes:
personNameoriginalAmountremainingAmountprogress(Percentage)
This data is used to render charts and summaries on the dashboard and analytics screens.
Sources: rust/hesabyar-core/src/analytics.rs:85-112, rust/uniffi/hesabyar_core/uniffi/hesabyar_core/hesabyar_core.kt:917-925
The Loan & Debt Tracking module provides a robust framework for managing personal lending and borrowing within Hesabyar, leveraging a shared Rust core for performant financial calculations and ensuring data consistency across the application's analytical features.