Inside Cash Ledger: Engineering an Offline-First, Privacy-Centric Android Finance Engine

Cash Ledger for Android

Kotlin Native • Offline-First Architecture • GPL-3.0 License • Zero Telemetry

Personal financial data is among the most sensitive information we produce every day. Yet, the vast majority of modern budgeting applications mandate cloud account creation, connect directly to commercial data aggregators, and harvest telemetry for ad-targeting networks. Cash Ledger was engineered on an uncompromising principle: Your money stays on your phone, in your hands, under your complete control.

code Explore on GitHub download Download Signed APK

1. The Core Philosophy: Why Offline-First?

When managing personal finance, latency and reliability matter just as much as privacy. You should never be blocked from logging an expense because you are underground in a subway station, traveling internationally without roaming data, or experiencing an unexpected cloud server outage.

Cash Ledger adopts an uncompromising offline-first design:

• Zero Telemetry & Zero Cloud Accounts: No mandatory login forms, no Google Firebase Analytics, no Meta/Facebook SDKs, and no remote crash analytics reporting.
• Deterministic Local Persistence: All transactions, wallets, recurring rules, and custom categories are saved directly into an SQLite database managed via Android's Room abstraction layer.
• Complete Data Portability: Seamless export to CSV, Excel (XLS), and printable PDF formats, alongside backward migration compatibility with Tallybook.

2. Interactive Live Demo: Cash Ledger Budget Simulator

Test Cash Ledger's real-time budgeting and category consumption engine directly in your browser below. Try adding transactions to see the safe spending velocity and color-shifting alerts adapt live:

3. Beautiful Code: Reactive Kotlin Architecture

At the heart of Cash Ledger is a clean, modern Android architecture utilizing Kotlin Coroutines, reactive StateFlow, and Room Database DAO queries. Here is how Cash Ledger calculates budget health asynchronously without blocking UI interactions:

package com.oriondev.moneywallet.domain.engine

import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.combine
import java.math.BigDecimal
import java.math.RoundingMode

/**
 * Real-time Budget Computation Engine
 * Computes consumption percentage and safe spending velocity.
 */
data class BudgetStatus(
    val totalLimit: BigDecimal,
    val currentSpent: BigDecimal,
    val remainingBuffer: BigDecimal,
    val percentConsumed: Float,
    val isOverBudget: Boolean
)

class BudgetEngine(
    private val transactionDao: TransactionDao,
    private val budgetDao: BudgetDao
) {
    /**
     * Observes real-time budget status across one or more monitored categories.
     */
    fun observeBudgetHealth(budgetId: Long, startDateEpoch: Long, endDateEpoch: Long): Flow<BudgetStatus> {
        return combine(
            budgetDao.getBudgetByIdFlow(budgetId),
            transactionDao.getExpensesSumForPeriod(startDateEpoch, endDateEpoch)
        ) { budget, totalExpense ->
            val limit = budget.amount
            val spent = totalExpense ?: BigDecimal.ZERO
            val remaining = (limit - spent).max(BigDecimal.ZERO)
            
            val consumptionRatio = if (limit > BigDecimal.ZERO) {
                spent.divide(limit, 4, RoundingMode.HALF_UP).toFloat()
            } else 0f

            BudgetStatus(
                totalLimit = limit,
                currentSpent = spent,
                remainingBuffer = remaining,
                percentConsumed = (consumptionRatio * 100f).coerceAtMost(100f),
                isOverBudget = spent > limit
            )
        }
    }
}

4. Zero-Knowledge Private Backups: WebDAV & Local Storage

Users should never be forced to trust third-party servers with their financial ledgers. Cash Ledger supports user-controlled WebDAV sync, allowing automated backups directly to your own Nextcloud instance, Synology NAS, or any standard WebDAV endpoint:

package com.oriondev.moneywallet.data.backup

import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.asRequestBody
import java.io.File
import java.io.IOException

/**
 * Decentralized WebDAV Synchronizer
 * Enables zero-third-party backups to self-hosted cloud storage.
 */
class WebDavBackupManager(
    private val client: OkHttpClient,
    private val config: WebDavConfig
) {
    suspend fun uploadEncryptedSnapshot(localSnapshotFile: File): Result<Unit> {
        val remoteUrl = "${config.serverUrl.trimEnd('/')}/cashledger-backup.zip"
        
        val request = Request.Builder()
            .url(remoteUrl)
            .put(localSnapshotFile.asRequestBody())
            .header("Authorization", config.toBasicAuthHeader())
            .header("Content-Type", "application/octet-stream")
            .build()

        return runCatching {
            client.newCall(request).execute().use { response ->
                if (!response.isSuccessful) {
                    throw IOException("WebDAV sync rejected with HTTP code ${response.code}")
                }
            }
        }
    }
}

5. Current Project Status

Cash Ledger is actively maintained and evolved. Here is a breakdown of what has been achieved so far:

• Modern Kotlin Upgrade: Refactoring legacy Java utilities to idiomatic Kotlin classes, sealed interfaces, and extension functions.
• Reproducible GitHub Actions CI: Continuous integration builds that create signed, verifiable APKs automatically with zero closed-source build dependencies.
• Material Design 3 Polish: Seamless support for Google's dynamic light and dark theme palettes.
• Multi-Currency Wallets: High-precision monetary arithmetic preventing floating-point rounding errors across foreign currency transfers.
• Biometric & Hardware KeyStore Auth: Fingerprint and PIN lock screen verification ensuring your ledger stays inaccessible if you hand your unlocked phone to a peer.

6. The Roadmap: Future Programs & Vision

Here is the strategic development roadmap planned for upcoming Cash Ledger releases:

7. Join & Star the Initiative

Cash Ledger is free software published under the GNU General Public License v3.0. Open-source thrives on community feedback, bug reports, and code contributions.

Star on GitHub bug_report Report an Issue