Active Debt vs Settled Debt: The Lifecycle State Machine Inside FinLedger's Lending Engine

2026-11-16来源 dev.to UXEnglish
Active Debt vs Settled Debt: The Lifecycle State Machine Inside FinLedger's Lending Engine

Active Debt vs Settled Debt: The Lifecycle State Machine Inside FinLedger's Lending Engine

When a friend finishes repaying a loan, what should happen to the record in your finance app?

In many expense trackers, you are presented with a frustrating dilemma:

  • Option A: Delete the record to keep your debt dashboard clean. But deleting the record destroys your historical audit trail, erases notes, and leaves orphan entries in your bank statement.
  • Option B: Keep the settled record forever in your primary view. But after two years of tracking shared expenses with roommates and colleagues, your dashboard is cluttered with dozens of people who owe you exactly zero rupees.

In financial software, historical data must never be deleted simply to achieve visual cleanliness.

When architecting FinLedger's debt tracker, I introduced a formal lifecycle separation: Active Records versus Past Records (LendingPersonLifecycleTest.kt).

Here is how FinLedger automates the borrower lifecycle to keep your daily interface minimal while preserving permanent historical truth.

The Problem with Manual Deletion

Consider this scenario:

flowchart TD subgraph DeletionRisk["The Deletion Anti-Pattern"] Loan["You lend Rahul Rs. 5,000 for concert tickets"] --> Repaid["Rahul repays Rs. 5,000 across 3 installments"] Repaid --> ManualDelete["User deletes Rahul's record to clean up UI"] ManualDelete --> Dispute["3 Months Later: Dispute arises over whether the second installment of Rs. 1,500 was paid in cash or UPI."] Dispute --> Regret["Data Permanently Lost: Zero record of payment dates, bank linkages, or timestamps!"] end

Deleting settled loans erases the answers to critical questions:

  • When did they pay me back?
  • Which bank account did the money get deposited into?
  • Did they settle in a single lump sum or partial installments?

In financial accounting, an entity transitioning to zero balance is an event to be recorded, not erased.

The Active vs Past Lifecycle Engine

FinLedger solves this by deriving borrower visibility dynamically through reactive domain models:

flowchart TD subgraph LifecycleFlow["Borrower Lifecycle State Transitions"] Open["1. Open Loan Created: Outstanding Balance > 0.00 Status: OUTSTANDING"] --> ActiveTab["Displayed in 'Active Records': Surfaces prominently with due dates and balances"] ActiveTab --> Partial["2. Partial Repayment Logged: Outstanding Balance Decreases Status: PARTIALLY_PAID"] Partial --> ActiveTab Partial --> FullRepay["3. Final Repayment Logged: totalRepaid == totalOriginal Outstanding Balance = 0.00"] FullRepay --> Settled["4. Automatic State Transition: Status: SETTLED isFullySettled = true"] Settled --> PastTab["Silently Moved to 'Past Records': Active view stays uncluttered. Full history preserved in searchable archive."] end

Deterministic State Derivation

In LendingPersonSummary.fromRecords, a contact's settlement status is never a manual toggle that a user can forget to click. It is derived mathematically:

  • If lentOutstanding > 0.00 (or borrowedOutstanding > 0.00), the person is classified as Active.
  • When repayments bring the outstanding balance to zero (lentOutstanding <= 0.001), the summary flags isFullySettled = true.

Zero Manual Intervention

The transition is immediate and automatic:

  1. The moment the user logs the final repayment of Rs. 150 that brings Rahul's balance to zero, the reactive Kotlin StateFlow emits an updated person summary.
  2. Jetpack Compose animates Rahul's card out of the Active Records list.
  3. Rahul is immediately accessible under the Past Records tab, complete with his entire multi-year transaction log.

Inspecting Past Records with Complete Context

Moving an entity to "Past Records" is not an archival black hole.

Tapping a contact in Past Records opens their complete lending dossier:

  • Every loan agreement and disbursement date.
  • Every partial repayment installment, including exact timestamps and notes.
  • Clickable links to the companion bank ledger transactions where the money was deposited.
  • Aggregate metrics: Total lifetime money lent, total lifetime repayments, and average days to full settlement.

If Rahul ever asks, "Did I finish paying you back for that trip?", you can pull up the verified ledger in five seconds.

Key Takeaway

A well-designed financial application respects both your current attention and your past history.

By treating borrower settlement as an automated lifecycle transition between Active and Past views, FinLedger keeps your daily debt dashboard clean and focused on actionable balances, without ever sacrificing the permanent audit trail of your financial relationships.

FinLedger is a privacy-first, offline-first personal finance application for Android that models bank accounts, credit cards, and cash without double-counting.

Explore FinLedger on Google Play: https://play.google.com/store/apps/details?id=com.devanshufinance.app

原文:https://www.a8q9.cn/en/article/active-debt-vs-settled-debt-the-lifecycle-state-machine-inside-finledger-s-lendi-e42ba9.html

相关文章