DEV Community

Cover image for Preventing Duplicate Contact Names From Silently Corrupting Your Lending Ledger
DEVANSHU PATIL
DEVANSHU PATIL

Posted on

Preventing Duplicate Contact Names From Silently Corrupting Your Lending Ledger

Preventing Duplicate Contact Names From Silently Corrupting Your Lending Ledger

When building an expense or lending tracker, contact management seems trivial at first glance:

"Just let the user type a name in a text field: 'Rahul'. Save it to SQLite. Done."

In practice, free-form text input without identity modeling quickly degenerates into chaos.

Consider what happens over a year of real-world usage:

  • You lend Rs. 500 to Rahul (your coworker).
  • Three months later, you lend Rs. 2,000 to Rahul (your cousin).
  • Next week, you record a dinner split with Rahul P (the same coworker).

If your app relies on naive string matching or creates unindexed rows for every entry, you face two destructive failure modes:

  1. The Silent Merge: The app assumes every "Rahul" is the same person. Your cousin's loan is merged into your coworker's balance sheet!
  2. The Duplicate Explosion: The app creates three separate cards for "Rahul", "rahul", and "Rahul P.", scattering loan installments across different entries and making it impossible to see total debt in one place.

Here is how FinLedger architected a contact disambiguation engine (PersonDao.kt, LendingDialogs.kt) to eliminate name collisions and duplicate entities.

The Pitfalls of Naive Contact Management

flowchart TD
    subgraph Failures["The Twin Traps of Free-Form Contact Entry"]
        UserTypes["User Enters Name: 'Rahul'"]

        UserTypes --> Trap1["Failure Mode 1: The Silent Merge
        App matches existing 'Rahul' by string equality.
        Cousin's loan merged into Coworker's record!
        Privacy breach and accounting confusion."]

        UserTypes --> Trap2["Failure Mode 2: Duplicate Explosion
        App creates new entity for every string variance:
        'Rahul', 'rahul ', 'Rahul Patil'.
        Dozens of fragmented cards clutter the UI."]
    end

To build a reliable ledger, an application must decouple identity (who the person actually is) from display labels (what their name looks like on screen).

The FinLedger Architecture: Relational Person Entities

In FinLedger, contacts are first-class domain entities managed by PersonDao.kt, decoupled from individual loan or split records:

flowchart TD
    subgraph PersonArchitecture["Centralized Person Relational Model"]
        Input["User Types Contact Name: 'Rahul'"] --> Normalizer["String Normalizer:
        Trim whitespace, lowercase comparison"]

        Normalizer --> MatchQuery{"Query PersonDao:
        Does an existing contact match
        normalized string 'rahul'?"}

        MatchQuery -->|No Match Found| CreateNew["Create New Person:
        Generate immutable UUID.
        Store name, optional phone & note."]

        MatchQuery -->|Match Found| Disambiguate["Surface Disambiguation Dialog:
        Display matching contacts with metadata:
        - Rahul Patil (Coworker, +91 98XXX)
        - Rahul Verma (Cousin)"]

        Disambiguate --> UserDecision{"User Selects Action"}

        UserDecision -->|Select Existing| BindExisting["Bind to Existing Person ID:
        Aggregates under existing debt history"]

        UserDecision -->|Create Distinct| CreateDistinct["Create New Distinct Person:
        Assign unique UUID. Prompt for nickname/note."]
    end

Let's examine how each safeguard functions in detail:

1. Case-Insensitive String Normalization

Before querying the database, candidate names pass through a strict string sanitizer:

  • Trims leading and trailing whitespace.
  • Collapses multiple internal spaces into a single space.
  • Compares using Unicode-aware case insensitivity (COLLATE NOCASE).

This ensures that typing "Rahul Patil", "rahul patil", or "Rahul Patil " immediately identifies the candidate as the same person rather than spawning three fragmented records.

2. The Interactive Disambiguation Prompt

When you create a loan or split expense and enter a name that matches one or more existing records, FinLedger refuses to make an assumption.

In LendingDialogs.kt, an interactive disambiguation sheet appears:

  • "A contact named 'Rahul' already exists. Is this the same person?"
  • The sheet surfaces the contact's contextual metadata: their phone number suffix, personal note (e.g., "Design Team"), and current outstanding balance.
  • If it is the same person, tapping their card binds the new loan to their existing personId.
  • If it is a different person, tapping "Create as New Person" prompts you to enter a distinguishing note or last name (e.g., "Rahul (Cousin)") and assigns an independent, unique UUID.

3. Immutable Relational Keys (personId)

Every debt record (LendingEntity) and repayment (LendingRepaymentEntity) references the person via an immutable foreign key: personId: String (a UUIDv4).

Because the database relations are bound to the immutable UUID rather than the human-readable string:

  • If you later edit Rahul's display name to "Rahul Patil (Tech Lead)", that edit updates a single row in the persons table.
  • All historical loans, partial repayments, and split expenses across the last three years stay perfectly connected with zero broken references.

Key Takeaway

Contact names in human language are inherently ambiguous; software identifiers must never be.

By establishing a centralized, UUID-driven Person repository with case-insensitive normalization and proactive disambiguation prompts, FinLedger guarantees that doing business with people of the same name never corrupts your financial records.


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

Top comments (0)