DEV Community: DEVANSHU PATIL

How to Actually Audit Your Spending Without Spiraling Into Anxiety

DEVANSHU PATIL — Sat, 07 Nov 2026 13:00:00 +0000

Most people dread personal financial audits.

The traditional advice sounds exhausting: download three months of PDF bank statements, open a spreadsheet, manually copy every single line item into Excel, create pivot tables, and spend six hours on a Sunday afternoon squinting at numbers.

After doing that once, 95% of people never do it again. It feels like doing homework for your own life.

The problem is not that financial audits are unnecessary; the problem is that traditional auditing methods focus on the wrong details.

You do not need to analyze every 50-rupee chai or individual taxi ride to take control of your financial health. You need a structured, low-friction framework that answers three high-impact questions in less than twenty minutes.

Here is the three-tier financial audit framework, and how modern offline tools make it painless.

The Three-Tier Audit Framework

A productive personal financial review does not examine all transactions equally. It operates through three progressive filters:

flowchart TD
    subgraph AuditFramework["The 3-Tier Financial Audit Framework"]
        direction TB
        Tier1["Tier 1: Balance Reconciliation (5 Minutes)
Compare bank statement ending balances against ledger balances. Fix discrepancies."]
        Tier2["Tier 2: Subscription & Recurring Pruning (5 Minutes)
Audit automated monthly recurring charges. Cancel zombie services."]
        Tier3["Tier 3: Category Burn Rate Review (10 Minutes)
Review top 3 spending categories. Check if reality matched your intentions."]
    end
    Tier1 --> Tier2 --> Tier3

Tier 1: Balance Reconciliation (5 Minutes)

Before looking at where your money went, you must confirm that you know where your money is:

Open your primary banking app and check your current balance.
Open your personal finance app and compare the numbers.
If they match down to the paisa, you have total confidence in your data.
If there is a small discrepancy, use FinLedger's Bank Statement Reconciliation tool to record an adjustment (such as a bank service fee or interest credit) rather than trying to hunt down missing receipts from six weeks ago.

Tier 2: Subscription & Recurring Pruning (5 Minutes)

Recurring charges are the silent killers of personal wealth. A 400-rupee streaming service, a 999-rupee software subscription, or a 1,500-rupee forgotten gym membership quietly siphon thousands of rupees every year because they require zero active approval.

In FinLedger, the Subscriptions Hub uses an automated on-device pattern detector (SubscriptionDetectorEngine.kt):

It scans historical transactions for recurring patterns ($\ge 2$ occurrences with consistent intervals and amounts).
It highlights active subscriptions with their annual cost projections.
In five minutes, ask yourself: "Did I use this service in the last 30 days?" If not, cancel the subscription immediately.

Tier 3: Category Burn Rate Review (10 Minutes)

Instead of agonizing over 50 tiny expenses, focus exclusively on your top 3 spending categories.

For most people, 80% of discretionary spending concentrates in three areas:

Dining out and food delivery
Shopping and impulse online purchases
Travel and weekend entertainment

flowchart LR
    subgraph CategoryInsights["Category Donut Breakdown"]
        direction LR
        Spend["Total Monthly Outflow: 45,000"]
        Top1["1. Food & Dining: 18,000 (40%)"]
        Top2["2. Online Shopping: 12,000 (26.6%)"]
        Top3["3. Fuel & Commute: 6,000 (13.3%)"]
        Other["All Other Categories: 9,000 (20%)"]

        Spend --> Top1 & Top2 & Top3 & Other
    end

Open your monthly summary and look at the Category Donut Breakdown:

Look at the actual rupee total spent in your top category.
Compare it against your monthly budget.
Ask a single question: "Did this spending align with my real values and priorities this month?"

If the answer is yes, celebrate the fact that your money served your life. If the answer is no, you have identified the exact single behavioral change to make next month.

Why Date-Grouped Ledgers Beat Raw Spreadsheets

Spreadsheets are passive grids of data. A date-grouped mobile ledger is an interactive narrative.

In FinLedger:

The Monthly Summary groups transactions by day, showing net daily cash flow. You can instantly spot "expensive days" (like an expensive Saturday night out) and understand what drove the spike.
The Available Spendable Money hero card reminds you how much liquid cash you have left today after cordoning off money for upcoming credit card bills.

Making the Audit a Habit

A financial audit should not feel like punishment. It is a moment of self-awareness.

Set a recurring calendar reminder on the first Sunday of every month:

Reconcile balances (5 mins).
Review recurring subscriptions (5 mins).
Inspect top category burn rates (10 mins).

Twenty minutes once a month is all it takes to gain permanent control over your financial trajectory.

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

Biometrics + PIN Fallback: How FinLedger Secures Keys Without a Backend Server

DEVANSHU PATIL — Sat, 07 Nov 2026 04:30:00 +0000

When someone hands their phone to a friend to show a photo, the last thing they want is that friend casually opening their personal finance app and browsing their account balances or net worth.

Mobile authentication is the front door of personal privacy.

Yet many Android apps implement authentication with alarming vulnerabilities:

Storing a plaintext 4-digit PIN in unencrypted SharedPreferences.
Using weak, unsalted MD5 or SHA-256 hashes vulnerable to instant precomputed rainbow table attacks (a 4-digit numeric PIN has only 10,000 possible combinations, which a modern smartphone CPU can crack in less than 2 milliseconds).
Using vulnerable string comparison methods (pin == inputPin) susceptible to CPU execution side-channel timing attacks.

Here is how FinLedger architected its authentication subsystem during Hardening Sprint H8, combining hardware-backed Android BiometricPrompt with 50,000-iteration salted PBKDF2 PIN hashing and constant-time verification.

The Problem With 4-Digit PINs

A 4-digit numeric PIN has a fundamental mathematical limitation: the keyspace is tiny.

From 0000 to 9999, there are exactly 10,000 possible passwords. If an attacker extracts a standard SHA-256 hash of a 4-digit PIN:
$$\text{SHA-256}("1234") = \text{03ac674216f3e15c761ee1a5e255f067953623c8b388b4459e13f978d7c846f4}$$

A single CPU core can compute all 10,000 SHA-256 hashes in approximately 1.8 milliseconds. Without proper cryptographic key stretching and salting, a 4-digit hash provides virtually zero protection against an extracted database.

flowchart TD
    subgraph WeakHashing["The Fast Hash Vulnerability"]
        direction TB
        WeakPIN["4-Digit PIN (Only 10,000 Possible Combinations)"] --> FastAlgo["Standard SHA-256 / MD5 Hash"]
        FastAlgo --> FastCrack["Cracked in under 2 milliseconds via Brute-Force!"]
    end
    subgraph HardenedPBKDF2["FinLedger PBKDF2 Key Stretching"]
        direction TB
        PINInput["User 4-Digit PIN"] --> Salt["16-Byte Cryptographically Secure Salt (SecureRandom)"]
        Salt --> PBKDF2["PBKDF2 with HMAC-SHA256:
50,000 Sequential Iterations"]
        PBKDF2 --> HardenedHash["Computationally Expensive Derived Hash:
Defeats GPU / ASIC Brute-Force Exhaustion"]
    end

The Solution: Salted PBKDF2 with 50,000 Iterations

To secure numeric PINs, FinLedger implements Password-Based Key Derivation Function 2 (PBKDF2) combined with HMAC-SHA256:

Unique 16-Byte Random Salt: When the user configures their PIN, the SecurityManager generates a cryptographically random 16-byte salt using java.security.SecureRandom. This ensures that even if two users choose the identical PIN (1234), their stored hashes are completely different, defeating precomputed rainbow tables.
50,000 Iteration Stretching: PBKDF2 applies a pseudo-random function sequentially 50,000 times. This intentionally introduces a 30-millisecond computational delay for a single verification. For a legitimate user entering their PIN once, 30ms is completely imperceptible. But for an attacker attempting to brute-force all 10,000 combinations, the total attack time increases from 1.8 milliseconds to over 5 minutes of intensive computation.

Eliminating Timing Attacks with Constant-Time Comparison

In standard Java/Kotlin, comparing two strings using stringA == stringB or stringA.equals(stringB) uses an early-exit comparison: it checks characters one by one and returns false the microsecond it finds a mismatch.

In high-security environments, an attacker measuring CPU instruction cycles can deduce which character was incorrect based on how many nanoseconds the comparison took (a timing side-channel attack).

FinLedger verifies PIN hashes using constant-time verification:

MessageDigest.isEqual(storedHashBytes, computedHashBytes)

MessageDigest.isEqual always compares every single byte in the array regardless of where a mismatch occurs, ensuring that the execution time is strictly identical whether the first byte or the last byte differed.

Progressive Rate Limiting and Lockouts

To stop automated brute-force attacks on the physical device itself, FinLedger enforces a progressive lockout state machine:

stateDiagram-v2
    [*] --> Unlocked
    Unlocked --> Locked : App Backgrounded / Timeout
    Locked --> Unlocked : Valid Biometric or PIN
    Locked --> AttemptFailed : Incorrect PIN
    AttemptFailed --> Locked : Failed Attempts < 5
    AttemptFailed --> SoftLockout : 5 Failed Attempts (30s Lockout)
    SoftLockout --> HardLockout : 10 Failed Attempts (60s Lockout)
    HardLockout --> MaximumLockout : 15 Failed Attempts (300s Lockout)

5 Failed Attempts: Temporary 30-second lockout.
10 Failed Attempts: Temporary 60-second lockout.
15 Failed Attempts: Full 5-minute (300-second) lockout.
Lockout counters and expiration timestamps are stored inside Android Keystore-backed EncryptedSharedPreferences, ensuring that restarting the application cannot bypass active lockout countdowns.

The Zero-Lockout Migration Strategy

In early development builds, FinLedger utilized a simpler single-round SHA-256 hash. When we upgraded to 50,000-iteration PBKDF2 in Sprint H8, we faced a critical deployment challenge: how do you upgrade existing user PINs without forcing everyone to reset their accounts?

We engineered a Zero-Lockout Auto-Upgrade Migration:

When a user with an older hash logs in, the SecurityManager verifies the entered PIN against the legacy SHA-256 algorithm.
The instant authentication succeeds, the engine takes the verified plaintext PIN in memory, generates a fresh 16-byte random salt, stretches it through 50,000 iterations of PBKDF2, saves the new hardened hash, and permanently purges the legacy hash.
The user experiences zero friction, and their security is transparently upgraded to modern standards on their very next login.

Android BiometricPrompt Integration

Alongside the hardened PIN, FinLedger integrates directly with the AndroidX BiometricPrompt API:

Allows instant authentication using fingerprint sensors or secure 3D face recognition.
Uses BIOMETRIC_STRONG crypto-based authentication backed by the hardware TEE (Trusted Execution Environment).
If biometric authentication fails or the sensor is dirty, the user seamlessly falls back to the PBKDF2 PIN keypad.

Key Takeaway

A 4-digit PIN can be simple for the user without being easy for an attacker.

By combining hardware-backed biometrics with 50,000 iterations of salted PBKDF2, constant-time verification, and progressive lockout state machines, FinLedger delivers consumer convenience backed by defense-grade security.

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

What Happens When You Delete a Bank Account With 500 Transactions Behind It?

DEVANSHU PATIL — Fri, 06 Nov 2026 13:00:00 +0000

In a personal finance app, deleting an individual transaction is a minor recalculation.

Deleting an entire account, however, is the financial equivalent of detonating a structural support beam inside a building.

Consider what an account actually represents:

It holds an opening balance and a running balance.
It is referenced by hundreds or thousands of historical transactions spanning multiple years.
It may have acted as the source or destination for dozens of inter-account transfers to other bank accounts.
It may have linked active investment holdings, recurring bill schedules, or credit card billing statements.

If your application allows a user to delete an account with a single unverified DELETE FROM accounts WHERE id = ?, your database will either crash due to SQLite foreign key constraint failures or leave behind severed counter-party balances.

Here is how FinLedger designs account deletion safety through a multi-step defense-in-depth pipeline.

The Archival Alternative: Why You Rarely Want to Delete

Before discussing deletion, the most important product decision is offering Account Archival.

In 90% of real-world scenarios, a user does not want to destroy an account's history; they simply closed a bank account or canceled a credit card:

They switched from Bank A to Bank B.
They closed an old credit card to avoid an annual fee.

flowchart TD
    subgraph ArchivalVsDeletion["Archival vs Deletion"]
        direction TB
        UserAction["User Closed a Bank Account"]

        subgraph SafeArchival["Option A: Archive Account (Recommended)"]
            A1["Set isArchived = true"]
            A2["Hide from Daily Account Pickers & Transfer Dropdowns"]
            A3["Preserve 100% Historical Statements & Past Tax Reports"]
            A4["Retain Relational Foreign Key Integrity Forever"]
        end

        subgraph PermanentDeletion["Option B: Permanent Deletion (Danger Zone)"]
            D1["Double Confirmation Dialog"]
            D2["Verify No Active Dependencies (Loans, Portfolios)"]
            D3["Recalculate All Counter-Party Accounts from Past Transfers"]
            D4["Cascade Delete Transactions, Attachments, and Statements"]
        end

        UserAction --> SafeArchival
        UserAction --> PermanentDeletion
    end

When an account is archived:

The isArchived flag is set to true.
The account is immediately hidden from active transaction entry pickers, transfer dropdowns, and daily dashboard cards.
Crucially, all historical transactions, past annual tax statements, and carried-forward ledger mathematics remain 100% intact.

Permanent Account Deletion: The Safety Pipeline

When a user insists on permanent deletion (located inside the Settings "Danger Zone"), FinLedger executes a strict four-stage safety sequence:

flowchart LR
    subgraph DeletionStages["Account Deletion Safety Pipeline"]
        direction TB
        Stage1["1. Dependency Inspection:
Check for Active Portfolio Holdings or Linked Loans"] --> Stage2["2. Double-Confirmation Guard:
Explicit Warning Dialog Requiring Confirmation"]
        Stage2 --> Stage3["3. Counter-Party Recalculation:
Refund all external accounts involved in past transfers"]
        Stage3 --> Stage4["4. Atomic Cascade Cleanup:
Purge transactions, disk attachments, and statements"]
    end

Stage 1: Dependency Check (`BlockedByDependencies`)

Before allowing deletion, AccountRepository.deleteAccount() inspects relational dependencies:

Does this account have active portfolio investment holdings?
Is this account linked to outstanding loan repayments? If active dependent records exist, the operation is blocked: AccountDeletionResult.BlockedByDependencies. The user is instructed to close or transfer their active holdings first.

Stage 2: The Double-Confirmation Guard

Account deletion is quarantined behind a multi-step confirmation dialog:

The dialog explicitly lists the consequences: the exact number of transactions that will be purged and the total balance that will be eliminated.
The user must explicitly confirm the action.

Stage 3: Counter-Party Recalculation

What happens to past transfers?
Suppose Account A transferred 10,000 rupees to Account B four months ago. If Account A is deleted, what happens to Account B?

If you simply delete the transfer record, Account B's balance will become invalid upon the next historical ledger recalculation.
FinLedger's deletion engine iterates through all past transfer records involving the deleted account, recalculates the running balances of all counter-party accounts atomically, and posts compensating ledger adjustments where required.

Stage 4: Resolving SQLite Foreign Key Constraints (Commit `fd19ad0`)

In early versions, deleting an account that had linked credit card statements or vault records could trigger an immediate SQLite FOREIGN KEY constraint failed exception.

In commit fd19ad0, we audited the exact cascade deletion order inside AppDatabase.withTransaction:
1. Unlink and delete child statement records.
2. Prune linked receipt photo attachments from device disk.
3. Delete child transaction entities.
4. Finally, remove the parent account entity.

Preserving the Single Primary Account Invariant

FinLedger enforces a strict invariant: there must always be exactly one primary account.

When a user deletes an account that was currently marked as the primary account (isPrimary = true):

The repository's atomic transaction automatically selects the next available liquid account (such as the default Cash Wallet) and elevates it to primary (clearPrimaryAccounts() followed by setPrimaryAccount()).
The application is never left in an invalid state where zero primary accounts exist.

Key Takeaway

Deleting financial accounts requires comprehensive architectural defensive programming.

By prioritizing non-destructive archival, inspecting dependencies before execution, recomputing counter-party transfer balances, and respecting SQLite foreign key cascade order, FinLedger guarantees that even destructive actions never corrupt your ledger.

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

How I Store Merchant Suggestions Without Polluting Relational Database Keys

DEVANSHU PATIL — Fri, 06 Nov 2026 04:30:00 +0000

When designing a database for an expense tracker, normalization is usually the first instinct of any software engineer.

You create a transactions table. A transaction has a merchant. So you immediately create a normalized merchants table with an auto-incrementing primary key (id, name, category_id), and add a foreign key column to your transaction table: merchant_id REFERENCES merchants(id).

It feels like textbook database design.

Then real users start typing real-world merchant names into your application, and that relational foreign key constraint quickly turns into an engineering nightmare.

Here is why FinLedger deliberately decoupled merchant auto-suggestions from relational foreign keys, and how we built an on-device merchant intelligence engine without database pollution.

The Normalization Trap: Why Foreign Keys Fail for Merchants

In the real world, merchant names are noisy, erratic, and constantly shifting:

A user buys coffee at "Blue Tokai Coffee Roasters".
Next week, their credit card SMS alerts them about a transaction at "BLUE TOKAI COFFEE".
Two weeks later, they manually enter an expense as "Blue Tokai".
Three weeks later, they visit a branch at the airport and type "Blue Tokai - Terminal 2".

flowchart TD
    subgraph StrictRelational["The Strict Relational Anti-Pattern"]
        direction TB
        M1["merchants Table:
id=1: 'Blue Tokai'
id=2: 'Blue Tokai Coffee'
id=3: 'BLUE TOKAI COFFEE ROASTERS'"]
        Tx["transactions Table:
Foreign Key: merchant_id -> Rigid Dependency!"]
        M1 --- Tx
        Problem["What happens when the user cleans up duplicate merchants?
Deleting or merging merchant rows requires cascading updates across 
thousands of historical transaction records!"]
    end

If your transaction table enforces a strict foreign key constraint (merchant_id):

The Proliferation of Duplicates: Every minor spelling variation, capitalization difference, or branch suffix forces the creation of a brand new row in the merchants table.
Cascading Migration Nightmares: If a user wants to merge or rename a merchant, SQLite must rewrite foreign key pointers across hundreds of historical transactions. If an account is deleted or transactions are purged, foreign key constraints risk breaking.
SMS Ingestion Friction: Automated SMS parsers often extract truncated merchant strings (e.g. "VSI*UBER INDIA"). Forcing an automated parser to match or create a permanent relational merchant entity before saving a transaction creates unnecessary pipeline complexity.

The FinLedger Architecture: Flexible Text + Independent Learning

To solve this, FinLedger enforces a clean separation of concerns:

Transactions store merchants as pure, decoupled text attributes (purposeMerchant: String).

Meanwhile, merchant auto-suggestions, category predictions, and usage frequency are managed by an entirely independent subsystem: the Merchant Rule & Intelligence Engine (MerchantRuleEntity, MerchantRuleDao, and LocalCategoryIntelligenceEngine).

flowchart LR
    subgraph DecoupledArchitecture["FinLedger Decoupled Merchant Architecture"]
        direction TB
        TxEntity["Transaction Entity:
amount: 450.00
purposeMerchant: 'Blue Tokai' (Plain String)
categoryId: 3 (Food & Dining)"]

        RuleEntity["MerchantRule Entity (Independent):
normalizedPattern: 'blue tokai'
preferredCategoryId: 3
usageCount: 14
lastUsedTimestamp: 1729864200000"]

        TxEntity -.->|"Learns From (Asynchronous)"| RuleEntity
        RuleEntity -.->|"Provides Auto-Suggestions To"| UI["Add Transaction UI Screen"]
    end

1. The Transaction Entity Remains Resilient

Because purposeMerchant is a standard string column, transactions have zero foreign key dependencies on merchant entities:

A transaction can be edited, copied, imported from a bank statement, or deleted without worrying about orphan relational keys.
Truncated SMS names or detailed manual notes exist safely side-by-side.

2. The Auto-Learning Rule Engine

Whenever a transaction is confirmed in TransactionRepository:

The engine extracts the merchant string and normalizes it (lowercase, trimmed whitespace, special characters removed).
It queries the merchant_rules table. If the normalized pattern exists, it increments usageCount, updates lastUsedTimestamp, and refines the associated preferredCategoryId.
If the pattern is new, it inserts a new rule learning that this merchant belongs to this category.

Intelligent Auto-Suggestions with Blank Query Support

When a user taps into the merchant field in ModernAddTransactionScreen:

As they type "bl", the repository queries MerchantRuleDao.searchMerchantRules("bl%").
Results are ranked dynamically by recency and frequency (frequently visited merchants appear at the top of the dropdown).
Tapping a suggestion auto-fills the merchant name and automatically selects the associated spending category with a single tap.

Fixing the Blank Query Edge Case (Commit `8922c14`)

A subtle UX defect in early versions occurred when a user opened the merchant field without typing:

If the search query was blank, the dropdown showed nothing.
In commit 8922c14, we updated the query pipeline: when the search query is blank, the engine automatically surfaces the user's top 5 most frequently used recent merchants. If a user clears their search query, the suggestion sheet gracefully re-opens rather than closing.

Key Takeaway

Database normalization is a tool, not a religious dogma.

Keeping merchant names as decoupled text attributes in your transaction tables while managing auto-complete intelligence in an independent learning engine gives you the best of both worlds: frictionless data entry for users and zero relational fragility in your database.

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

Layers, Boundaries, and Leaks: Clean Android Architecture for Financial Apps

DEVANSHU PATIL — Thu, 05 Nov 2026 13:00:00 +0000

Architecture diagrams always look beautiful in blog posts.

You draw clean concentric circles: the UI layer points to the Presentation layer, which points to Domain UseCases, which points to Repositories, which points to the Database. Everything looks orderly, modular, and decoupled.

Then you write 100,000 lines of production code over several months.

Features are added rapidly; release deadlines loom; edge cases arise. Slowly, boundaries begin to erode:

A ViewModel starts executing raw SQL queries to save five minutes.
A Repository starts formatting user-facing date strings.
A composable screen calls three different repositories directly because creating an aggregator feels like boilerplate.

Recently, we completed an exhaustive, 360-file architectural audit of FinLedger (documented in FINLEDGER_FULL_APPLICATION_AUDIT.md).

Here is a transparent look at the anatomy of FinLedger's architecture: what worked brilliantly, where architectural erosion crept in, and how we are refactoring our largest classes.

The Architectural Blueprint

FinLedger is organized according to Clean Architecture and MVI/MVVM presentation patterns:

flowchart TD
    subgraph UI_Layer["1. Presentation Layer (Jetpack Compose)"]
        direction TB
        Screens["Screens & Composables:
LedgerScreen, DashboardScreen, CreditCardDetailScreen"]
        Tokens["Design System Tokens (Colors, Shapes, Elevation)"]
    end
    subgraph VM_Layer["2. ViewModel Layer (StateFlow & Coroutines)"]
        VMs["ViewModels:
LedgerViewModel, BudgetViewModel, VaultViewModel"]
        Pipelines["Reactive Pipelines & UDF State Bundles"]
    end
    subgraph Domain_Layer["3. Pure Domain Layer (Zero Android Dependencies)"]
        Engines["Domain Engines:
LedgerEngine, Posting.kt, CreditCardBillingEngine"]
        Models["Immutable Domain Models & Validation Rules"]
    end
    subgraph Data_Layer["4. Data Layer (Persistence & Security)"]
        Repos["Specialized Repositories:
TransactionRepo, AccountRepo, LendingRepo, VaultRepo"]
        DB[("Room + SQLCipher Encrypted SQLite
(33 Entities, 24 DAOs, Migrations 1 -> 24)")]
        Security["KeyStore & SecurityManager (PBKDF2)"]
    end

    UI_Layer -->|"User Intents"| VM_Layer
    VM_Layer -->|"Immutable StateFlow"| UI_Layer
    VM_Layer -->|"Domain Commands"| Repos
    Repos -->|"Delegates Calculations"| Domain_Layer
    Repos <-->|"withTransaction ACID"| DB

The Triumphs of This Design

Isolated Accounting Math: Consolidating all posting rules into Posting.kt and LedgerEngine.kt completely eliminated balance calculation drift between UI screens and background workers.
Lightning-Fast JVM Testing: Because the domain engine contains zero android.* imports, all 1,570 automated unit tests execute directly on the JVM in under 12 seconds.
Database Security Isolation: SQLCipher page-level encryption and KeyStore master key management remain completely encapsulated in the data layer; UI screens have zero awareness of cryptographic ciphers.

Where Architecture Eroded: The "God Object" Problem

When an application grows to 100,324 lines of Kotlin code across 360 source files, file concentration is the most insidious form of architectural erosion.

Our October audit uncovered a stark reality: the top 10 largest files accounted for over 17,900 lines of code—nearly 18% of the entire codebase!

Monolithic File	Line Count	Primary Responsibility	Architectural Flaw
`BackupRestoreManager.kt`	3,043 LOC	Encrypted backup/restore	Acts as codec, disk unpacker, and cloud sync coordinator simultaneously.
`VaultDialogs.kt`	2,813 LOC	Secret Fund UI modals	Houses 14 distinct setup dialogs and location sliders in a single file.
`ModernAddTransactionScreen.kt`	1,985 LOC	Transaction entry UI	Mixes layout composables with complex input validation and category auto-selection.
`DatabaseReconciliationEngine.kt`	1,502 LOC	Whole-app ledger recalculation	Contains both audit algorithms and direct database update routines.
`SplitGroupDetailScreen.kt`	1,497 LOC	Group expenses UI	Combines 3 distinct tab layouts (Bills, Balances, History) in one file.

Why does this happen?
It happens because convenience compounds. When adding a new backup feature, it is always faster to add a private function to an existing BackupRestoreManager.kt than to design a new modular driver interface. Over months, a 400-line class quietly becomes a 3,000-line monolith.

The Storage vs. Database ACID Boundary Window

The audit also exposed a subtle boundary leak between SQLite and the Android filesystem.

When a user deletes a transaction with receipt photos:

The database rows in the transactions and transaction_attachments tables delete within an atomic Room transaction (withTransaction).
But deleting the physical JPEG files from disk (File.delete()) must happen outside SQLite, because the local filesystem is not managed by SQLite's transaction journal.

If an unexpected process termination or power loss occurs in the millisecond window between the database commit and the disk file deletion, an orphaned image file remains in private app storage.

Identifying this leak allowed us to implement an automated startup hygiene sweep in AttachmentRepository to quietly prune orphaned disk files.

The Modular Refactoring Roadmap for v2.1.2

A real engineering architecture is not a static monument; it is a living system that requires continuous maintenance.

flowchart LR
    subgraph Monolith["BackupRestoreManager (3,043 LOC)"]
        direction TB
        CodeAll["Everything in one file"]
    end
    subgraph Modular["v2.1.2 Modular Decomposition"]
        direction TB
        Codec["BackupPayloadCodec:
Pure JSON Serialization & SHA-256 Envelope"]
        Cipher["BackupVaultCipher:
AES-256-GCM Cryptographic Engine"]
        Runner["LocalRestoreRunner:
Atomic Filesystem Unpacking & Rollback"]
        Driver["CloudSyncDriver:
Google Drive REST v3 Transport"]
    end
    Monolith ==>|"Refactored Into"| Modular

Based on our architectural audit, our refactoring plan decomposes our largest classes into single-responsibility drivers:

Splitting BackupRestoreManager.kt into BackupPayloadCodec (pure serialization), BackupVaultCipher (cryptography), LocalRestoreRunner (filesystem rollback), and GoogleDriveSyncDriver (network transport).
Decomposing VaultDialogs.kt into 6 modular dialog composables.
Decoupling ModernAddTransactionScreen.kt into presentation-only widgets and a standalone TransactionInputValidator.

Key Takeaway

Clean Architecture is not about achieving ideological purity; it is about managing cognitive complexity and change resistance.

When your codebase grows, audit your boundaries regularly. Acknowledge your monoliths honestly, and refactor before file concentration turns your architecture into legacy code.

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

Building a Finance Filter Sheet That Doesn't Require a PhD to Use

DEVANSHU PATIL — Thu, 05 Nov 2026 04:30:00 +0000

As a personal finance ledger grows from fifty transactions to five thousand, finding specific financial events becomes a needle-in-a-haystack problem.

A simple search bar can match a merchant name like "Amazon", but text search alone cannot answer multidimensional financial questions:

"Show me all credit card purchases between 1,000 and 5,000 rupees during our trip to Goa last August."
"Show me all cash expenses categorized under Dining across the last three months."
"Show me all transactions that have receipt photo attachments uploaded."

Answering these questions requires multi-dimensional filtering.

Here is how FinLedger designed and built its multi-dimensional filter bottom sheet (LedgerFilterSheet.kt) in Jetpack Compose, supporting real-time multi-variable constraints without lag.

The Five Dimensions of a Financial Filter

In Sprint 8 (commit 43d9bfb), we formalized the multidimensional filter model into five orthogonal filter axes:

classDiagram
    class LedgerFilterState {
        +DateRangeFilter dateRange
        +Set~Long~ selectedAccountIds
        +Set~TransactionType~ selectedTypes
        +Set~Long~ selectedCategoryIds
        +ClosedFloatingPointRange amountRange
        +Boolean hasAttachmentsOnly
        +Boolean isDefault()
        +Int activeFilterCount()
    }
    class DateRangeFilter {
        ALL_TIME
        THIS_MONTH
        LAST_MONTH
        CUSTOM_RANGE(start, end)
    }
    LedgerFilterState *-- DateRangeFilter

Temporal Dimension (Date Range): All Time, This Month, Last Month, or a custom date range picker (startDate to endDate).
Account Dimension: Filter to any combination of specific accounts (e.g. HDFC Checking + Cash Wallet, excluding Credit Cards).
Transaction Type Dimension: Income, Expense, Transfer, Credit Card Purchase, or Card Repayment.
Categorical Dimension: Filter across multiple spending categories (e.g. Groceries + Dining Out + Fuel).
Magnitude Dimension (Amount Slider): A dual-thumb range slider filtering transactions between a minimum and maximum monetary amount (e.g. 500 to 10,000 rupees).
Attachment Presence: A quick toggle filtering transactions that have attached receipt photos.

The Jetpack Compose Architecture: Bottom Sheet State Hoisting

To provide a smooth user experience, the filter sheet is rendered as a modal bottom sheet using Material 3 ModalBottomSheet.

A critical architectural consideration in Jetpack Compose is state hoisting:

flowchart LR
    subgraph StateHoistingFlow["Filter State Hoisting Flow"]
        direction LR
        VM["LedgerViewModel:
Holds Authoritative _filterState"] --> Sheet["LedgerFilterSheet (Composable):
Maintains Local Draft State"]
        Sheet -->|"User Toggles Chips / Adjusts Sliders"| Draft["Local Draft Updates Fluidly"]
        Draft -->|"User Taps 'Apply Filters'"| Apply["Emit New State to ViewModel"]
        Draft -->|"User Taps 'Reset All'"| Reset["Revert Local Draft to Default"]
    end

1. Isolated Draft State

If the bottom sheet modifies the ViewModel's active filter state on every single chip tap or slider drag, the underlying transaction list will continuously re-filter and recompose in the background while the user is still making decisions.

Instead, LedgerFilterSheet creates a local copy (rememberSaveable) of the filter state upon opening. Users can toggle multiple categories, adjust price sliders, and change date ranges with instant local UI responsiveness.

2. Explicit Commit and Reset

Apply Filters Button: Commits the local draft state back to LedgerViewModel._filterState. The bottom sheet dismisses, and the ledger updates in a single unified emission.
Reset All Button: Resets all five dimensions back to default in one tap.
Active Filter Badge: The filter icon on the ledger top bar displays a numbered badge indicating exactly how many filter dimensions are currently active (e.g. "3" if filtering by Category, Account, and Date Range).

Real-Time Slider Performance with Paisa Snapping

One of the most complex UI components in the sheet is the dual-thumb amount range slider:

It must handle ranges from 0 rupees to 500,000+ rupees.
If the slider steps are linear, adjusting small amounts (like 250 rupees) on a 500,000-rupee scale is nearly impossible because 1 millimeter of finger movement jumps by 10,000 rupees.
FinLedger solves this using a logarithmic scale curve for the slider values: fine-grained 50-rupee steps at lower amounts (under 5,000), expanding to 500-rupee steps at medium amounts, and 5,000-rupee steps at high amounts.

Zero Distortions in Filtered Exports

A major advantage of formalizing LedgerFilterState is seamless export integration:

When a user applies a filter (e.g. "All Medical expenses in 2026"), and then taps Export CSV or Generate PDF Statement, the export engines read the exact same filtered transaction set.
The exported vector PDF statement displays the active filter criteria directly in its header, providing an authoritative, filtered financial document ready for tax filing or expense reimbursement.

Key Takeaway

A financial ledger is only as powerful as its query capabilities.

By organizing filters into orthogonal dimensions, isolating local draft state inside a modal bottom sheet, and integrating filtered sets directly into PDF and CSV export pipelines, FinLedger turns years of complex transaction history into an instantly searchable, audit-ready database.

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

The Search Bug That Silently Corrupted My Running Balance Display

DEVANSHU PATIL — Wed, 04 Nov 2026 13:00:00 +0000

Search is one of the most frequently used features in any financial application.

A user opens their transaction ledger, taps the search bar, and types "Starbucks" or "Electric Utility". They want to know two things:

When did these transactions take place?
Exactly how much money did I spend on this specific merchant or utility?

If the user interface is poorly architected, however, searching a ledger creates bizarre, misleading financial summaries.

Here is why FinLedger's search pipeline dynamically decouples Carried-Forward opening balances from search results, ensuring that search headers provide immediate, actionable answers without financial distortion.

The Cognitive Trap of Static Ledger Headers

Consider a user who has an active checking account with an ending balance of 125,000 rupees.

They open their ledger feed and type "Gym" into the search box. The list immediately filters down to show two matching transactions:

October 1: Annual Gym Membership — 12,000 rupees
June 15: Protein Shake at Gym Cafe — 350 rupees

flowchart TD
    subgraph ConfusingUI["The Confusing Static Header Anti-Pattern"]
        direction TB
        Search["Search Active: 'Gym' (2 matches)"]
        Header["Header Summary Card:
Account Balance: 125,000
Carried-Forward (C/F): 137,350
Total Spend: 12,350"]
        UserConfusion["User Confusion:
'Why does the header say 125,000 when I searched Gym?
What does the 137,350 Carried-Forward number mean here?'"]
        Search --> Header --> UserConfusion
    end

If the summary top card continues displaying the total account balance (125,000) and the full Carried-Forward opening equity (137,350), what does that header communicate?

The user is looking at a filtered view of two gym transactions, but the top card is blaring a 125,000-rupee balance.
If the header shows "Net Flow = -12,350", but adds that to the total account opening balance, the numbers on screen completely contradict the filtered rows below them.

The user's brain has to mentally filter out the header because it represents the whole account, while the list represents the search query.

The Solution: Dynamic Search Mode Transitions

In FinLedger, entering a search query triggers a formal contextual transition in the LedgerViewModel data pipeline:

flowchart LR
    subgraph SearchStateSwitch["Ledger Header Contextual Switch"]
        direction LR
        Normal["Normal Feed Mode:
1. Display Carried-Forward Starting Balance
2. Display Period Income & Expense
3. Display Authoritative Ending Balance"]

        SearchActive["Search Mode Active:
1. Zero Out Carried-Forward Balance (C/F = 0.00)
2. Display Filtered Search Total Sum
3. Display Count of Matched Records"]

        Normal <-->|"User Types in Search Box (Debounced 200ms)"| SearchActive
    end

1. Zeroing Out the Carried-Forward Balance

When a search query is active (e.g. query.isNotBlank()), the concept of a historical opening balance is irrelevant. The user is not auditing their bank statement; they are aggregating a subset of historical expenses.

The engine explicitly sets:
$$\text{Carried-Forward (C/F)} = 0.00$$

2. Displaying the Matched Search Total

The top summary card dynamically transforms into a Search Result Breakdown:

Matched Total: Displays the exact sum of all matching expenses ($\sum \text{matched amounts}$). In the gym example, it clearly reads: "2 transactions found: -12,350.00".
If the search returns both income and expenses (such as searching a contact's name who both borrowed and repaid money), the header shows: $$\text{Net Flow} = \sum \text{Matched Income} - \sum \text{Matched Expenses}$$

3. Instant Restoral on Dismissal

The moment the user taps the clear icon or backtracks out of the search bar, the pipeline smoothly transitions back to the authoritative ledger mode:

The true Carried-Forward starting balance is restored.
The complete date-grouped transaction feed recomposes in milliseconds.

Performance: Debounced Asynchronous Filtering

In large personal ledgers spanning years of records, searching through thousands of merchant strings, notes, and tags can strain the CPU if executed naively on every keystroke.

FinLedger optimizes this using Kotlin Coroutine operators:

Debounce (200ms): The search input stream is throttled using _searchQuery.debounce(200). Rapid typing does not trigger repetitive filtering until the user's fingers pause.
Background Execution (Dispatchers.Default): String matching, case-insensitive normalization, and amount aggregation execute entirely on background worker threads.
Date Preservation: Matched search results retain their sticky date headers so the user can see exactly when each transaction occurred across past years.

Key Takeaway

Good software adapts its presentation to match user intent.

When a user searches their ledger, they want to aggregate a specific category of spending, not inspect their total bank balance. Decoupling carried-forward totals during search provides instant clarity while protecting the mathematical integrity of the feed.

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

Why `withTransaction` Is the Only Safe Way to Post Financial Entries in SQLite

DEVANSHU PATIL — Wed, 04 Nov 2026 04:30:00 +0000

Mobile applications execute in a chaotic, hostile runtime environment.

Unlike backend servers running on uninterrupted data center power, a mobile app can be terminated by the Android operating system at virtually any microsecond:

The user can swipe the app away in the Android task switcher.
The device battery can run completely out of charge.
The Android low-memory killer (LMK) can terminate background processes to prioritize an incoming phone call.

If your financial application updates multiple database tables without strict transactional atomicity, a poorly timed process death will split your database in half: some rows will be written, others will be lost, and your accounts will be permanently out of balance.

Here is how FinLedger guarantees database resilience using Room's withTransaction blocks across all multi-account balance mutations.

The Horror of Partial Batch Writes

To understand what a partial write looks like, examine what happens during a standard inter-account transfer of 20,000 rupees from a checking account to a savings account.

Under the hood, this transfer requires three separate database operations:

UPDATE accounts SET currentBalance = currentBalance - 20000 WHERE id = 1 (Checking)
UPDATE accounts SET currentBalance = currentBalance + 20000 WHERE id = 2 (Savings)
INSERT INTO transactions (...) VALUES (...) (The Transfer Audit Log)

flowchart TD
    subgraph FailureScenario["The Partial Write Catastrophe"]
        direction TB
        Op1["1. Debit Checking: 20,000 (SUCCESS)"] --> Op2["2. Android Process Killed / Device Dies (HALT!)"]
        Op2 -.-> Op3["3. Credit Savings: 20,000 (NEVER EXECUTED)"]
        Op2 -.-> Op4["4. Write Transfer Record (NEVER EXECUTED)"]
        Op1 --> Result["Result: 20,000 rupees vanished into thin air!
Checking is debited, Savings never credited, zero transaction record!"]
    end

If these three queries execute as independent SQLite statements without an enclosing transaction boundary:

Step 1 completes: 20,000 rupees leaves checking.
The phone's battery dies or the OS kills the process before Step 2 executes.
When the user restarts their phone, the 20,000 rupees is missing from checking, was never credited to savings, and no transaction record exists to explain what happened.

The user has suffered digital data loss.

The Solution: ACID Atomicity with `withTransaction`

In computer science, ACID guarantees that database transactions are Atomic, Consistent, Isolated, and Durable.

In Android Room, transactional atomicity across asynchronous Kotlin Coroutines is achieved using the withTransaction extension function on RoomDatabase:

flowchart LR
    subgraph TransactionBoundary["Room withTransaction { ... } Boundary"]
        direction TB
        Begin["BEGIN EXCLUSIVE TRANSACTION"] --> Step1["1. Debit Checking (-20,000)"]
        Step1 --> Step2["2. Credit Savings (+20,000)"]
        Step2 --> Step3["3. Insert Transfer Entity"]
        Step3 --> Step4["4. Update Learned Merchant / Category Rules"]
        Step4 --> Commit["COMMIT TRANSACTION"]
    end
    Commit -->|"Success"| LiveState["All Rows Committed Together"]
    Step2 -.->|"Process Killed / Error"| Rollback["SQLite Automatic Rollback:
Database Reverts to Exact Pre-Transfer State"]

When you wrap operations inside appDatabase.withTransaction { ... }:

Room acquires an exclusive transaction lock on the underlying SQLite connection.
All SQL insert, update, and delete queries executed inside the lambda participate in that single atomic transaction.
If any step throws an exception, or if the process dies midway, SQLite's write-ahead log (WAL) rolls back every single modification upon recovery.
Either all four steps succeed together, or none of them do. It is mathematically impossible for an account to be debited without the companion account being credited.

Sprint H2 Audit: Eliminating the Gaps

During FinLedger's Hardening Sprint H2 (commit b0ac8e2), we conducted an exhaustive audit of all database writes across the entire codebase.

We identified and resolved three areas where partial writes could previously occur:

1. CSV Data Import

Previously, importing a large CSV spreadsheet containing 500 transactions processed and inserted rows in small incremental chunks. If the user cancelled midway or a single malformed row caused a parser error, the database was left half-imported.

Resolution: The entire CSV parse-and-persist phase was wrapped in a single withTransaction block paired with a pre-import safety snapshot. If row 499 fails validation, all previous 498 rows are instantly rolled back, leaving the database completely pristine.

2. Multi-Account Loan Settlements

When a friend repays multiple loans simultaneously, the repayment must credit the user's bank account, reduce multiple loan receivables, and update the person's directory status.

Resolution: The entire repayment cascade was unified under LendingRepository inside withTransaction.

3. Credit Card Waterfall Payment Allocations

Allocating a card payment across multiple historical statements requires updating the bank balance, card liability balance, and multiple statement payment tracking entities.

Resolution: All statement status transitions (UNPAID $\to$ PARTIALLY_PAID $\to$ FULLY_PAID) execute within the same atomic boundary as the bank payment transfer.

Concurrency and SQLite Lock Contention

While withTransaction guarantees safety, holding a database transaction lock for too long can block other threads and cause UI stutter.

To ensure high performance:

We keep long-running non-database work (such as JSON parsing, cryptographic key derivation, and image compression) strictly outside the transaction block.
We prepare all entity data in memory first, enter withTransaction, execute rapid batched SQL queries, and exit the transaction in less than 5 milliseconds.

Key Takeaway

In mobile engineering, you must design for failure. Your app will be interrupted, backgrounded, and killed.

Wrapping all multi-row and multi-account balance mutations inside atomic withTransaction blocks is the non-negotiable prerequisite for building a personal finance ledger that never loses a user's money.

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

Your Finance App Needs a Reconciliation Engine — Mine Nearly Didn't Have One

DEVANSHU PATIL — Tue, 03 Nov 2026 13:00:00 +0000

No matter how disciplined you are with your personal finance tracker, physical reality will eventually collide with your digital ledger.

You open your mobile banking app on the first of the month and see an ending balance of 43,210 rupees.

You open your expense tracking app and look at that same bank account, only to find that your app displays 44,150 rupees.

There is a discrepancy—a delta ($\Delta$) of 940 rupees.

Where did it come from?

Did the bank quietly deduct an annual debit card fee or an SMS alert charge?
Did you receive a small quarterly interest credit that you forgot to record?
Did you buy fresh fruit at a roadside stall with cash that you forgot to log?
Did an automated bank notification fail to deliver due to poor mobile network coverage?

If an application provides no way to reconcile this drift, users are forced into terrible workarounds: they either manually alter opening balances, invent fake transactions, or give up on tracking altogether.

Here is how FinLedger solves balance drift by introducing a formal, double-entry Bank Statement Reconciliation Engine.

The Problem With Naive "Balance Overwrite"

When commercial finance apps let users fix a mismatched balance, their default solution is a crude text field: "Enter new balance."

flowchart TD
    subgraph NaiveOverwrite["The Naive Overwrite Problem"]
        direction TB
        AppBal["App Balance: 44,150"] --> UserTypes["User Types: 43,210"]
        UserTypes --> BlindUpdate["Blind SQL Mutation:
UPDATE accounts SET balance = 43210"]
        BlindUpdate --> Consequences["Consequences:
1. 940 rupees vanished without explanation
2. Historical audit trail broken
3. Monthly expense charts distorted
4. Future reconciliation impossible"]
    end

Blindly overwriting the database balance breaks the foundation of double-entry accounting:

Vanished Money: 940 rupees has disappeared without a paper trail. You cannot audit where your wealth went.
Broken Historical Parity: If the app ever performs a full historical recalculation (such as replaying transactions during a backup restore), the 940-rupee gap will reappear because there is no transaction explaining the delta.
Analytics Blind Spot: If the drift was caused by recurring bank service fees, your monthly expense charts will never reflect that cost, blinding you to unnecessary bank expenses.

The FinLedger Reconciliation Engine

In FinLedger, reconciliation is treated as an audited financial event, modeled in DatabaseReconciliationEngine.kt and surfaced through the dedicated ReconciliationScreen.kt.

flowchart LR
    subgraph ReconEngine["Reconciliation Workflow"]
        direction TB
        BankState["1. Real Bank Statement Balance:
User enters physical statement total (43,210)"] --> Diff["2. Engine Calculates Delta:
Delta = Actual (43,210) - Ledger (44,150) = -940"]
        Diff --> Category["3. Structured Adjustment Classification:
Bank Fee / Interest / Cash / Missing Tx"]
        Category --> Post["4. Generate Companion Adjustment Transaction:
Atomically posted via Posting.kt"]
    end

1. Delta Calculation

When the user opens the Reconciliation hub for an account:

The screen displays the current authoritative ledger balance (e.g. 44,150 rupees).
The user inputs their actual bank statement balance (43,210 rupees).
The engine calculates the exact discrepancy: $$\Delta = \text{Actual Statement Balance} - \text{Current Ledger Balance}$$
If $\Delta = 0.00$, the screen confirms that the account is in 100% mathematical harmony.
If $\Delta \neq 0.00$, the engine initiates structured adjustment workflows.

2. Structured Adjustment Transactions

Rather than blindly overwriting the account row, FinLedger generates a formal Adjustment Transaction categorized by the real-world cause:

Discrepancy Direction	Structured Adjustment Type	Accounting Behavior
Negative ($\Delta < 0$)	Bank Service Charge	Recorded as an operational expense categorized under "Banking & Fees".
Negative ($\Delta < 0$)	Unrecorded Cash / Expense	Recorded as an operational expense categorized under the user's chosen budget category.
Positive ($\Delta > 0$)	Interest Credited	Recorded as operational income categorized under "Interest & Dividends".
Positive ($\Delta > 0$)	Unrecorded Deposit	Recorded as operational income with clear reconciliation audit notes.

3. Atomic Ledger Alignment

The generated adjustment transaction flows through the authoritative domain engine (Posting.kt):

It updates the account balance to match the physical statement balance down to the exact paisa.
It records an immutable transaction row timestamped with the reconciliation date.
It attaches an explicit note: "Reconciliation adjustment for statement balance 43,210 (Delta: -940.00)".

The Whole-App Database Reconciliation Sweep

Beyond individual bank accounts, FinLedger v2.0.2 introduced a whole-app recalculation and reconciliation engine (commit 271b10c):

Users can trigger an on-demand integrity audit across all accounts simultaneously.
The engine sweeps every active and archived account, recalculates total postings from day zero, checks for foreign key integrity, and verifies that Available Spendable Money and Total Net Worth align with absolute precision.

Key Takeaway

A personal finance ledger must be reconcilable against the real banking system.

By turning balance discrepancies into structured, categorized adjustment transactions rather than silent database overwrites, FinLedger preserves a complete historical audit trail and ensures that your numbers always reflect physical truth.

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

Daily Feed, Monthly Rollup, Yearly Grid: Building All Three From One Query

DEVANSHU PATIL — Tue, 03 Nov 2026 04:30:00 +0000

When people look at their personal finances, their perspective changes depending on the question they are asking:

At 2:00 PM on a Tuesday, they ask: "Did my salary arrive today, and what did I spend on lunch?" (A Daily perspective).
On the last day of the month, they ask: "Did I save money this month, and why was my restaurant bill so high?" (A Monthly perspective).
At tax season or on New Year's Eve, they ask: "How did my overall wealth and annual spending trend across the last 12 months?" (A Yearly perspective).

Most finance applications force you into a single fixed view—usually an infinite scrolling list or a rigid monthly calendar.

In FinLedger, we engineered a unified, multi-period ledger architecture that allows users to glide seamlessly between Daily feeds, Monthly summaries, and a comprehensive 12-Month Yearly matrix with zero swipe lag.

Here is how that reactive multi-period data pipeline is built in Jetpack Compose and Kotlin Coroutines.

The Three Temporal Horizons

flowchart TD
    subgraph MultiPeriodArchitecture["The Multi-Period Perspective Hierarchy"]
        direction TB
        Daily["1. Daily View:
Granular audit feed, date headers, daily net burn, sticky C/F balances"]
        Monthly["2. Monthly View:
Calendar grouping, category spending breakdown, cash flow comparison"]
        Yearly["3. Yearly Matrix:
12-Month tabular grid (Jan - Dec), monthly income vs expense, running balance"]
    end

1. The Daily Feed: Micro-Auditability

The Daily view is designed for operational precision.

Transactions are grouped chronologically with high-contrast sticky day headers.
Each date header displays the daily net cash flow (e.g., "+45,000" or "-1,850").
The summary top card displays the exact Carried-Forward (C/F) balance from all prior days, grounding today's spend in real liquidity.

2. The Monthly View: Habit & Budget Analysis

The Monthly view shifts focus from individual transactions to spending habits.

Groups transactions across the entire calendar month.
Integrates with category budgets to show real-time burn rates and pacing alerts.
Displays the monthly cash flow comparison: total operational income vs total operational expenditure.

3. The 12-Month Yearly Matrix: High-Level Solvency

The Yearly view solves the "long-term visibility" problem using a custom 12-month financial matrix table (YearlyMatrixTable.kt).

Renders a clean 12-row tabular grid from January to December.
Each row displays three authoritative columns: Income, Expense, and Ending Running Balance.
Clicking any row in the annual matrix instantly navigates the user directly to that month's detailed transaction feed.

The Unified Data Pipeline: One Flow to Rule Them All

A common architectural mistake is creating separate, independent database queries and ViewModels for each time period: a DailyViewModel, a MonthlyViewModel, and a YearlyViewModel.

That approach leads to duplicate code, divergent calculation logic, and jarring screen transitions.

In FinLedger, all three perspectives are powered by a single reactive coroutine pipeline in LedgerViewModel:

flowchart LR
    subgraph Pipeline["Unified Reactive Pipeline"]
        direction TB
        Inputs["User Inputs:
_selectedPeriod (Daily/Monthly/Yearly)
_currentDate (Epoch Timestamp)
_filterState (Accounts, Categories)
_searchQuery (Debounced)"] --> Combine["Kotlin Flow combine()"]
        RoomDB[("Room Database
(All Accounts & Transactions)")] --> Combine
        Combine --> Worker["Dispatchers.Default:
Compute C/F Balance, Partition Date Groups, Build 12-Month Matrix"]
        Worker --> State["Immutable LedgerUiState"]
        State --> UI["Jetpack Compose Screen
(Instant Recomposition)"]
    end

The ViewModel maintains lightweight reactive state holders for _selectedPeriod (Daily, Monthly, Yearly), _currentDate, and _filterState.
A single combine operator merges these parameters with raw database streams from Room.
The transformation pipeline evaluates the active period and offloads all mathematical aggregation to Dispatchers.Default:
- If Daily: It slices transactions for that specific day and computes prior C/F balance.
- If Monthly: It filters transactions between day 1 and the last day of that month (LocalDate.lengthOfMonth()).
- If Yearly: It evaluates the entire calendar year and constructs the 12-month YearlyMatrixRow objects in a single pass.
The pipeline emits an immutable LedgerUiState consumed directly by the Jetpack Compose user interface via collectAsStateWithLifecycle.

Smooth Gestures: The Pager Navigation Shell

To switch between time periods and months, the user interface uses a horizontal swipe gesture.

When a user swipes left or right:

Changing the date simply updates _currentDate in the ViewModel.
The reactive pipeline recomputes state in under 4 milliseconds on a background thread.
Jetpack Compose uses structural keys on list items (items(transactions, key = { it.id })) to animate changes fluidly without re-measuring the entire layout.

Preserving Invariants Across Time Horizons

Regardless of which period the user is viewing, the underlying financial math never drifts:

Internal transfers contribute exactly 0.00 to monthly and yearly income/expense totals.
Credit card debt is subtracted from liquid cash across all views to preserve the Available Spendable Money invariant.
Opening balances remain balance sheet equity snapshots, never leaking into annual revenue summaries.

Key Takeaway

Financial clarity requires adjusting the zoom level without losing mathematical truth.

By powering Daily feeds, Monthly summaries, and 12-Month Yearly matrices through a single, background-computed reactive pipeline, FinLedger delivers seamless, instant transitions across all time horizons without dropped frames or accounting discrepancies.

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

Deleting a Transaction Should Be Surgical — Here's How to Do It Right

DEVANSHU PATIL — Mon, 02 Nov 2026 13:00:00 +0000

In software development, "delete" sounds simple: remove the row from the database and move on.

In a relational personal finance application, however, deleting a transaction is a major architectural operation. A single transaction record often has tentacles reaching into multiple subsystems:

It altered account balances that must now be refunded.
It may have been an inter-account transfer connecting two completely separate bank entities.
It may have had a receipt photo stored in private app storage.
It may have been a companion record generated by a loan repayment or a split expense.

If you simply execute DELETE FROM transactions WHERE id = ?, you leave behind accounting scars: orphaned files consuming device storage, desynchronized loan balances, and corrupted account totals.

Here is how FinLedger designs safe, zero-leak transaction deletion across all connected subsystems.

The Web of Dependencies

Consider what happens when a user deletes a single transfer transaction of 15,000 rupees sent from checking to a savings account six months ago.

flowchart TD
    subgraph Dependencies["The Dependency Web of a Single Transaction"]
        direction TB
        Tx["Transaction Record (ID: 502)"]
        Source["Source Account (Checking: Deducted 15,000)"]
        Dest["Destination Account (Savings: Credited 15,000)"]
        Receipt["Receipt Attachment (File: receipt_502.jpg on Disk)"]
        Lending["Companion Lending Record (Debt Repayment Sync)"]

        Tx --- Source
        Tx --- Dest
        Tx --- Receipt
        Tx --- Lending
    end

If the deletion logic only removes the row from the transactions table:

The checking account balance remains permanently under-reported by 15,000 rupees.
The savings account balance remains permanently over-reported by 15,000 rupees.
The receipt photo image file receipt_502.jpg remains abandoned in /data/user/0/com.finance.app/files/receipts/, silently consuming device disk space forever.
If this transaction was linked to a loan repayment, the friend's outstanding debt is now permanently desynchronized from the actual ledger.

The Atomic Deletion Sequence

To eliminate orphaned data and balance drift, FinLedger executes transaction deletion through a unified multi-step workflow in TransactionRepository:

flowchart LR
    subgraph DeletePipeline["Unified Deletion Pipeline"]
        direction TB
        Fetch["1. Fetch Entity & Linked Attachments"] --> Postings["2. Calculate Inverted Postings"]
        Postings --> Recalc["3. Atomic SQLite Balance Reversal"]
        Recalc --> Sync["4. Sync Companion Subsystems (Lending/Split)"]
        Sync --> Disk["5. Clean Up Physical Files on Disk"]
    end

Step 1: Pre-Deletion Inspection

Before touching the database, the repository queries the target transaction entity along with its associated records:

Identifies the source account and destination account (if a transfer).
Retrieves all linked TransactionAttachmentEntity rows containing local file URIs and remote Google Drive file IDs.

Step 2: Inverting Postings and Recalculating Balances

The engine passes the transaction to Posting.kt to determine its exact historical balance impact, negating all deltas:

If deleting an Expense: the source account is credited back the transaction amount.
If deleting an Income: the destination account is debited the transaction amount.
If deleting a Transfer: the source account is credited, and the destination account is debited.
If deleting a Credit Card Purchase: the card's liability balance is reduced.

Both accounts are updated inside an atomic SQLite transaction block (AppDatabase.withTransaction).

Step 3: Two-Way Subsystem Synchronization

If the deleted transaction was connected to a specialized feature, companion entities must be updated to preserve relational truth:

Lending & Debt Tracker: If deleting a repayment transaction (repay_tx_<id>), syncLendingStateOnTransactionDelete immediately re-opens the loan receivable, increments the borrower's outstanding debt, and moves the person back from "Past Records" to "Active Records".
Split & Group Expenses: If deleting an expense split across a group, the group's net settlement balances are dynamically recalculated to reflect that the shared bill no longer exists.

Step 4: Physical Attachment Cleanup

Once the database transaction commits successfully, the repository initiates filesystem cleanup:

The local JPEG or PNG image files stored in the private app sandbox are deleted via standard filesystem APIs (File.delete()).
If Google Drive sync is enabled, the remote file deletion queue notes the deleted ID so the cloud snapshot removes the receipt on the next sync cycle.

Handling the Storage vs. Database ACID Window

During FinLedger's formal architectural audits (documented in FINLEDGER_FULL_APPLICATION_AUDIT.md), our review identified a subtle edge case common to all mobile apps:

SQLite operations are ACID-compliant, but local filesystem operations are not part of the database transaction. If the app process dies precisely between the SQLite commit and the physical disk file deletion, an orphaned image file could theoretically remain on disk.

To harden this boundary:

Attachment entities track their local file status explicitly.
The AttachmentRepository includes a background startup hygiene sweep that compares physical files in the receipts directory against active database attachment records, quietly pruning any orphan files whose companion database rows no longer exist.

Key Takeaway

Deleting a financial transaction is a reconciliation event, not a simple database row drop.

By reversing postings across all counter-party accounts, synchronizing companion debt models, and cleaning up filesystem attachments within disciplined architectural boundaries, FinLedger guarantees that deleting a mistake leaves zero accounting scars.

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

Why Editing a Transaction In-Place Is the Fastest Way to Corrupt Your Ledger

DEVANSHU PATIL — Mon, 02 Nov 2026 04:30:00 +0000

In a standard CRUD (Create, Read, Update, Delete) application, editing a record is usually the simplest feature to implement.

If a user edits a blog post title, you execute UPDATE posts SET title = ? WHERE id = ?. If they update their username, you overwrite the database column. The change is isolated, self-contained, and has zero side effects on other rows.

In a personal finance ledger, however, there is no such thing as an isolated edit.

A transaction is not just a row of text; it is an economic event that previously altered account balances, shifted carried-forward equity, updated budget burn rates, and possibly affected credit card billing statements.

If your application naively performs an in-place SQL update on a transaction record, your ledger balances will immediately corrupt.

Here is how FinLedger architected safe transaction editing using an atomic two-phase posting reconciliation engine.

The In-Place Update Trap

To understand why in-place updates fail, consider what happens when a user modifies a simple expense.

Suppose on October 5th, a user enters a 2,000-rupee grocery expense paid from their HDFC Bank checking account. At that moment:

HDFC checking balance is debited by 2,000 rupees.
Monthly grocery spending increases by 2,000 rupees.

Three days later, the user realizes they made a mistake: the bill was actually 2,500 rupees, and they paid with cash from their physical wallet, not their HDFC debit card.

flowchart TD
    subgraph NaiveUpdate["The Naive In-Place SQL Update"]
        direction TB
        E1["User Changes: Amount (2,000 -> 2,500) & Account (HDFC -> Cash)"] --> E2["Run In-Place SQL:
UPDATE transactions SET amount = 2500, account_id = 'cash' WHERE id = 101"]
        E2 --> E3["Result:
HDFC Account STILL MISSING 2,000!
Cash Account NEVER DEBITED!
Ledger Corrupted Forever!"]
    end

If the developer simply runs UPDATE transactions SET amount = 2500, account = 'cash', what happens to the account balances?

The HDFC checking account is still missing the original 2,000 rupees that was deducted on October 5th.
The Cash wallet was never debited by the new 2,500-rupee amount.
The database is now out of sync with physical reality.

Even if the developer writes a custom helper to calculate the difference between the old amount and the new amount ($2,500 - 2,000 = +500$), that delta arithmetic breaks down the moment the user edits the account, changes the transaction type (e.g. from an Expense to a Transfer), or changes the date across a monthly statement boundary.

The Two-Phase Reconciliation Solution

To ensure absolute mathematical consistency, FinLedger treats every transaction edit as a formal two-phase financial reconciliation.

Rather than attempting to calculate complex multi-variable deltas between the old and new states, the repository executes a clean inverse-then-post sequence:

flowchart LR
    subgraph EditCycle["Two-Phase Invariant Pipeline"]
        direction TB
        OldTx["1. Fetch Stored Original Transaction"] --> Inverse["Phase 1: Invert Original Postings
(Refund original accounts)"]
        NewTx["2. Validate New Transaction Inputs"] --> Forward["Phase 2: Apply New Postings
(Debit/Credit updated accounts)"]
        Inverse & Forward --> Atomic["Execute Atomically in SQLite:
AppDatabase.withTransaction { ... }"]
    end

Phase 1: Inverse Unwinding

The engine retrieves the existing, unedited transaction entity from the database.
It feeds the original transaction through Posting.kt to determine its exact original impact on account balances.
It inverts those postings: if the original transaction deducted 2,000 rupees from HDFC checking, the engine adds 2,000 rupees back to HDFC checking.
At this millisecond, the ledger state is restored to exactly what it would have been if the original transaction had never occurred.

Phase 2: Forward Application

The engine validates the newly edited transaction data (ensuring positive non-zero amounts, distinct transfer accounts, and valid categories).
It feeds the new transaction through Posting.kt to compute the new balance deltas (e.g., deducting 2,500 rupees from the Cash wallet).
It updates the transaction row in the SQLite database.
It recalculates the final balances for all touched accounts (both the old accounts that were refunded and the new accounts that were debited).

Guaranteeing ACID Atomicity via `withTransaction`

The critical requirement of this two-phase sequence is atomicity.

If the application unwinds Phase 1 (restoring 2,000 rupees to HDFC), and the Android operating system terminates the app process or the device battery dies before Phase 2 completes, the user will be left with phantom money.

In FinLedger, the entire lifecycle is encapsulated inside Room's transactional block:

flowchart TD
    subgraph RoomTransaction["SQLite Transaction Boundary (withTransaction)"]
        direction TB
        Step1["1. Begin SQLite Transaction (BEGIN EXCLUSIVE)"] --> Step2["2. Revert Old Postings on Touched Accounts"]
        Step2 --> Step3["3. Update Transaction Table Row"]
        Step3 --> Step4["4. Apply New Postings on Touched Accounts"]
        Step4 --> Step5["5. Synchronize Companion Records (Lending / Receipts)"]
        Step5 --> Step6["6. Commit Transaction (COMMIT)"]
    end
    Step6 -->|"On Any Error / Exception"| Rollback["Automatic SQLite ROLLBACK (Zero Data Loss)"]

If an exception occurs at any point—whether due to a database constraint violation, invalid input, or unexpected process interruption—SQLite automatically executes a full rollback. Either both phases succeed completely, or the database reverts to its exact pre-edit state.

Date Boundary Edits and Statement Snapshots

A further complication arises when the transaction's date is edited across billing boundaries:

If a credit card transaction dated October 10th (billed in the October statement) is edited to October 18th (belonging to the November statement), the credit card billing engine must recalculate statement balances for both cycles.
FinLedger's credit card statement engine re-evaluates closing timestamp boundaries dynamically, reallocating waterfall payments so that past closed bills remain immutable snapshots while current statements reflect the edited date.

Key Takeaway

Editing financial records requires respecting historical cause and effect.

Never rely on in-place field updates for financial data. By cleanly unwinding the original transaction's postings and applying the updated transaction's postings inside an atomic SQLite transaction, your ledger preserves 100% balance integrity across every edit.

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

DEV Community: DEVANSHU PATIL

How to Actually Audit Your Spending Without Spiraling Into Anxiety

The Three-Tier Audit Framework

Tier 1: Balance Reconciliation (5 Minutes)

Tier 2: Subscription & Recurring Pruning (5 Minutes)

Tier 3: Category Burn Rate Review (10 Minutes)

Why Date-Grouped Ledgers Beat Raw Spreadsheets

Making the Audit a Habit

Biometrics + PIN Fallback: How FinLedger Secures Keys Without a Backend Server

The Problem With 4-Digit PINs

The Solution: Salted PBKDF2 with 50,000 Iterations

Eliminating Timing Attacks with Constant-Time Comparison

Progressive Rate Limiting and Lockouts

The Zero-Lockout Migration Strategy

Android BiometricPrompt Integration

Key Takeaway

What Happens When You Delete a Bank Account With 500 Transactions Behind It?

The Archival Alternative: Why You Rarely Want to Delete

Permanent Account Deletion: The Safety Pipeline

Stage 1: Dependency Check (BlockedByDependencies)

Stage 2: The Double-Confirmation Guard

Stage 3: Counter-Party Recalculation

Stage 4: Resolving SQLite Foreign Key Constraints (Commit fd19ad0)

Preserving the Single Primary Account Invariant

Key Takeaway

How I Store Merchant Suggestions Without Polluting Relational Database Keys

The Normalization Trap: Why Foreign Keys Fail for Merchants

The FinLedger Architecture: Flexible Text + Independent Learning

1. The Transaction Entity Remains Resilient

2. The Auto-Learning Rule Engine

Intelligent Auto-Suggestions with Blank Query Support

Fixing the Blank Query Edge Case (Commit 8922c14)

Key Takeaway

Layers, Boundaries, and Leaks: Clean Android Architecture for Financial Apps

The Architectural Blueprint

The Triumphs of This Design

Where Architecture Eroded: The "God Object" Problem

The Storage vs. Database ACID Boundary Window

The Modular Refactoring Roadmap for v2.1.2

Key Takeaway

Building a Finance Filter Sheet That Doesn't Require a PhD to Use

The Five Dimensions of a Financial Filter

The Jetpack Compose Architecture: Bottom Sheet State Hoisting

1. Isolated Draft State

2. Explicit Commit and Reset

Real-Time Slider Performance with Paisa Snapping

Zero Distortions in Filtered Exports

Key Takeaway

The Search Bug That Silently Corrupted My Running Balance Display

The Cognitive Trap of Static Ledger Headers

The Solution: Dynamic Search Mode Transitions

1. Zeroing Out the Carried-Forward Balance

2. Displaying the Matched Search Total

3. Instant Restoral on Dismissal

Performance: Debounced Asynchronous Filtering

Key Takeaway

Why `withTransaction` Is the Only Safe Way to Post Financial Entries in SQLite

The Horror of Partial Batch Writes

The Solution: ACID Atomicity with withTransaction

Sprint H2 Audit: Eliminating the Gaps

1. CSV Data Import

2. Multi-Account Loan Settlements

3. Credit Card Waterfall Payment Allocations

Concurrency and SQLite Lock Contention

Key Takeaway

Your Finance App Needs a Reconciliation Engine — Mine Nearly Didn't Have One

The Problem With Naive "Balance Overwrite"

The FinLedger Reconciliation Engine

1. Delta Calculation

2. Structured Adjustment Transactions

3. Atomic Ledger Alignment

The Whole-App Database Reconciliation Sweep

Key Takeaway

Daily Feed, Monthly Rollup, Yearly Grid: Building All Three From One Query

The Three Temporal Horizons

1. The Daily Feed: Micro-Auditability

2. The Monthly View: Habit & Budget Analysis

3. The 12-Month Yearly Matrix: High-Level Solvency

The Unified Data Pipeline: One Flow to Rule Them All

Smooth Gestures: The Pager Navigation Shell

Stage 1: Dependency Check (`BlockedByDependencies`)

Stage 4: Resolving SQLite Foreign Key Constraints (Commit `fd19ad0`)

Fixing the Blank Query Edge Case (Commit `8922c14`)

The Solution: ACID Atomicity with `withTransaction`

Guaranteeing ACID Atomicity via `withTransaction`