FinApp — Local-First Personal & Business Finance Ledger

Zero-Knowledge, Offline-First Android Accounting & Expense Management System
Hardware-Backed Key Derivation • SQLCipher Full-Database Encryption • Clean Architecture • Jetpack Compose

---

💡 Architectural Overview

FinApp is an enterprise-grade Android personal and small-business financial ledger engineered with a zero-trust, local-first philosophy.

Unlike conventional cloud-tethered budgeting tools, all user financial records remain strictly on-device. The system operates with complete autonomy in airplane mode, survives forced OS process terminations without data loss, and utilizes military-grade cryptographic primitives to prevent unauthorized data exfiltration.

                      ┌──────────────────────────────────────┐
                      │    Presentation Layer (Compose UI)    │
                      └──────────────────┬───────────────────┘
                                         │ Observes StateFlow
                                         ▼
                      ┌──────────────────────────────────────┐
                      │    Domain Layer (Use Cases / Models)  │
                      └──────────────────┬───────────────────┘
                                         │ Calls Repositories
                                         ▼
                      ┌──────────────────────────────────────┐
                      │     Data Layer (Room / WorkManager)  │
                      └──────────────────┬───────────────────┘
                                         │ SQLite OpenHelper
                                         ▼
                      ┌──────────────────────────────────────┐
                      │  SQLCipher Hardware-Encrypted DB     │
                      │  (Wrapped Key in AndroidKeyStore)    │
                      └──────────────────────────────────────┘

---

🔒 Security & Cryptographic Model

Security Layer	Technical Implementation
Database Encryption	SQLCipher 256-bit AES-GCM encrypts all SQLite pages at rest.
Key Derivation	Master key derived from user passcode / biometric entropy via PBKDF2WithHmacSHA256 with high-iteration salt.
Key Custody	Symmetric key is wrapped and persisted inside the hardware-isolated AndroidKeyStore (StrongBox / TEE).
Biometric Authentication	Integrated with BiometricPrompt; encryption keys are only decrypted in memory during active, authenticated user sessions.
Zero Cloud Exposure	No third-party analytics, no ad SDKs, and zero telemetry pingbacks.

---

🚀 Key Modules & Capabilities

• 📊 Multi-Entity Double-Entry Accounting: Supports dual-entry ledgers with debit/credit balance reconciliation across personal, business, and savings accounts.
• 📩 Deterministic Transaction SMS Parsing: Native on-device SMS parser (feature/sms) that extracts debit/credit amounts, merchants, and timestamps from bank notification strings without sending SMS contents off-device.
• 🧾 On-Device Receipt Processing: Machine vision OCR extraction module (feature/ocr) to digitize and attach physical store receipts to expense entries.
• 🏷️ Intelligent Categorization Engine: Rule-based transaction tagging and classification (feature/categorize) providing instant expense breakdown summaries.
• 🔄 Reactive State Management: Built end-to-end with Kotlin Coroutines and StateFlow, powering 60fps fluid UI transitions in Jetpack Compose.

---

🏗️ Project Structure

app/src/main/java/com/finapp/
├── core/
│   ├── database/       # SQLCipher SupportSQLiteOpenHelper & DB holder
│   ├── di/             # Dagger Hilt dependency injection modules
│   ├── error/          # Sealed error hierarchies & domain exceptions
│   └── security/       # AndroidKeyStore, PBKDF2 crypto, biometric wrappers
├── domain/
│   ├── contract/       # Repository interfaces & gateway contracts
│   ├── model/          # Pure immutable Kotlin domain entities
│   └── usecase/        # Single-responsibility business use cases
├── data/
│   ├── db/             # Room Database, DAO definitions & entities
│   ├── model/          # Database mapping entities & serialization
│   ├── repository/     # Concrete repository implementations
│   └── worker/         # Android WorkManager background sync/reconciliation
├── feature/
│   ├── categorize/     # Auto-categorization rule pipelines
│   ├── ocr/            # On-device receipt text recognition
│   └── sms/            # Bank alert SMS receiver and regex parser
└── ui/                 # Jetpack Compose screens, design tokens & components

---

🛠️ Tech Stack & Dependencies

• Language: Kotlin 2.0 (Strict mode enabled)
• UI Framework: Android Jetpack Compose + Material Design 3
• Dependency Injection: Dagger Hilt 2.51+ with KSP code generation
• Local Persistence: Room Database 2.6+ with SQLCipher 4.5+
• Concurrency: Kotlin Coroutines & Asynchronous Flow
• Background Tasks: AndroidX WorkManager
• Testing: JUnit 5, Mockk, Robolectric 4.12+, and Compose UI Test Runner

---

💻 Getting Started

Prerequisites

• Android Studio Ladybug (2024.2+) or newer
• JDK 17 or higher
• Android SDK Platform 34

Building & Running

# Clone the repository
git clone https://github.com/LifeOfDevD/finance.git
cd finance

# Run unit tests
./gradlew testDebugUnitTest

# Assemble debug APK
./gradlew assembleDebug

---

📄 License

Distributed under the Apache 2.0 License. See LICENSE for more information.