Installment Management

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/ManageInstallmentUseCase.kt
• app/src/main/java/io/github/mojri/hesabyar/ui/InstallmentViewModel.kt
• rust/uniffi/hesabyar_core/uniffi/hesabyar_core/hesabyar_core.kt
• rust/hesabyar-core/src/analytics.rs
• rust/hesabyar-core/src/dashboard.rs
• app/src/main/java/io/github/mojri/hesabyar/domain/usecase/GetDashboardDataUseCase.kt
• app/src/main/java/io/github/mojri/hesabyar/data/ExcelExporter.kt
• app/src/main/java/io/github/mojri/hesabyar/ui/screens/SmartAssistantScreen.kt

Installment Management is a core module within the Hesabyar application designed to track, schedule, and analyze recurring financial obligations. It provides users with tools to record loan repayments or recurring payments, set reminders, and monitor payment progress through both automated analysis and manual controls. The system is architected as an offline-first solution, utilizing a shared Rust core (hesabyar-core) for heavy-duty financial calculations and analytics, while providing a modern Jetpack Compose interface for user interaction.

Sources: README.md, rust/hesabyar-core/README.md, app/src/main/java/io/github/mojri/hesabyar/ui/screens/SmartAssistantScreen.kt:479-500

Architecture and Data Flow

The installment system follows an MVVM (Model-View-ViewModel) pattern integrated with a Clean Architecture Use Case layer. Data originates from the AppDatabase (Room), flows through a Repository interface, and is exposed via Kotlin Coroutines Flow to the UI. For analytical tasks, the data is mapped to Rust-compatible structures and processed by the native core via UniFFI.

Component Interaction Flow

The following diagram illustrates how an installment is processed from the UI down to the data layer and analytical core.

This structure ensures that business logic is decoupled from the UI, and expensive calculations (like financial health scoring or debt-to-income ratios) are handled by the high-performance Rust core.

Sources: app/src/main/java/io/github/mojri/hesabyar/ui/InstallmentViewModel.kt:13-20, app/src/main/java/io/github/mojri/hesabyar/domain/usecase/ManageInstallmentUseCase.kt:9-15, rust/hesabyar-core/src/dashboard.rs:77-85

Data Models

Installments are represented by specific data structures across the Kotlin and Rust layers.

Kotlin Domain Model

Field	Type	Description
id	Long	Unique identifier for the installment.
title	String	Descriptive name (e.g., "Car Loan").
amount	Long	The monetary value in Rials.
dueDate	Long	Epoch timestamp of the payment deadline.
isPaid	Boolean	Completion status.
reminderEnabled	Boolean	Toggle for WorkManager notifications.
notes	String	Additional user-provided details.

Sources: rust/uniffi/hesabyar_core/uniffi/hesabyar_core/hesabyar_core.kt:1330-1340, app/src/main/java/io/github/mojri/hesabyar/domain/usecase/ManageInstallmentUseCase.kt:17-23

Key Logic and Features

Lifecycle Management

The system supports the full lifecycle of an installment, including creation, status toggling (Paid/Unpaid), and deletion. This is managed primarily through the ManageInstallmentUseCase.

Financial Analytics and Dashboarding

Installments are critical inputs for the application's dashboard. The GetDashboardDataUseCase utilizes both a Rust-based synchronous computation and a Kotlin fallback to determine the monthly debt obligation.

• Debt-to-Income Ratio: Calculated by summing unpaid installments due in the current cycle and prorated creditor loans, then dividing by monthly income.
• Monthly Boundaries: The system uses Jalali month boundaries (29–31 days) rather than a rolling 30-day window to ensure accuracy.

Sources: app/src/main/java/io/github/mojri/hesabyar/domain/usecase/GetDashboardDataUseCase.kt:76-103, rust/hesabyar-core/src/dashboard.rs:69-75

Smart Registration (AI Parsing)

Users can register installments using natural language in Persian. The SmartAssistantScreen provides an interface where sentences like "قسط ماشین ۳ میلیون" are parsed into ParsedResult objects containing extracted fields like title, amount, and daysFromNow.

Reporting and Exporting

Installment data is included in financial reports. The ExcelExporter builds a dedicated sheet for installments, including headers for Row Index, Title, Amount, Due Date, Status, and Notes. Amounts are formatted using CurrencyFormatter and dates are converted to the Jalali calendar via JalaliCalendarHelper.

Sources: app/src/main/java/io/github/mojri/hesabyar/data/ExcelExporter.kt:101-119

Implementation Details

Installment Management Use Case

// app/src/main/java/io/github/mojri/hesabyar/domain/usecase/ManageInstallmentUseCase.kt
class ManageInstallmentUseCase(private val repository: HesabyarRepositoryInterface) {
    val allInstallments: Flow<List<Installment>> = repository.allInstallments

    suspend fun addInstallment(title: String, amount: Long, dueDate: Long, reminderEnabled: Boolean, notes: String): Long =
        repository.insertInstallment(Installment(title = title, amount = amount, dueDate = dueDate, reminderEnabled = reminderEnabled, notes = notes))

    suspend fun toggleInstallmentPaid(installment: Installment) =
        repository.updateInstallment(installment.copy(isPaid = !installment.isPaid))
}

Sources: app/src/main/java/io/github/mojri/hesabyar/domain/usecase/ManageInstallmentUseCase.kt:8-35

Rust Core Analytics Integration

The analytics module in Rust aggregates installments to calculate progress.
Sources: rust/hesabyar-core/src/analytics.rs:109-111

Feature	Description
total_installments	Total count of installments in the system.
paid_installments	Count of installments where is_paid is true.
progress	Used in the UI to show completion percentage of debt repayment.

Sources: rust/hesabyar-core/src/analytics.rs:113-124

Summary

Installment Management in Hesabyar bridges the gap between simple transaction logging and long-term financial planning. By integrating Persian NLP for entry, Jalali-aware scheduling, and robust Rust-based analytics, the system provides a comprehensive view of a user's debt obligations and repayment health.