📊 SpendX

Your Money, Local-First. Secure, Subscription-Free Personal Finance.

---

SpendX is a modern, privacy-friendly personal finance tracker designed for developers, creators, and individuals who want full ownership of their financial data. No subscriptions, no cloud lock-in, and no spreadsheet fatigue.

Features • Tech Stack • Architecture • Getting Started • Release Build

---

💡 The Problem & The Solution

The Problem

Most personal finance tools today require constant cloud syncing, force you into expensive monthly subscriptions, or compromise your privacy by linking directly to live bank accounts. When those services shut down or change their models, your history goes with them.

The Solution

SpendX is built on a local-first philosophy. All transactional databases, settings, and credentials live directly on your physical device. It gives you the power of a comprehensive financial ledger, budgeting sheets, analytics, and intelligent imports without sacrificing your data privacy.

---

✨ Key Features

💳 Core Ledger & Money Flows

• Multi-Account Management: Track balances across cash, bank accounts, credit cards, loans, and lending arrangements.
• Granular Tracking: Organize transactions with categories, customizable tags, and advanced search/filters.
• Offline-First Storage: Powered by a local SQLite engine for instantaneous loads and zero-connection operation.

📅 Budgeting & Financial Control

• Flexible Budgets: Set up category-based budgets to visualize monthly or periodic spending.
• Salary Planning Ledger: Integrated flows to allocate and plan salary distribution across goals and bills.
• Recurring Transactions: Automate recurring expense logging (subscriptions, utility bills) on a flexible timeline engine.

📈 Reports & Deep Insights

• Interactive Analytics: View spending breakdowns, category metrics, and tag distributions through native canvas charts.
• Net Worth History: Track your overall net worth over time with local database snapshots.
• Nudges & Health Nudges: Receive subtle behavioral triggers about your spending trends.

🤖 Smart Inputs (OCR & Imports)

• Digital Statement Parser: Import records using bank-agnostic statement template mappings.
• On-Device OCR Receipt Scanning: Scan physical receipts using Google ML Kit to extract transaction details on-device.
• SMS Intent Handler: Optionally parse transaction messages locally to speed up entry.

---

🛠️ Tech Stack

SpendX uses modern mobile components to ensure high performance and maintainability:

• Framework: Flutter (Dart)
• State Management: Riverpod & Provider for reactive state updates
• Local Storage: sqflite (SQLite for Android & iOS)
• ML Engines: Google ML Kit Text Recognition (local, on-device OCR)
• CI/CD: GitHub Actions workflow automatically verifying linting, formatting, and unit tests

---

🏗️ Architecture

SpendX follows a modular, feature-first structure with clean separation of layers:

lib/
  ├── core/          # App configuration, logging, and global utilities
  ├── data/          # Local database schemas, migrations, and shared repositories
  ├── features/      # Feature modules (salary ledger, transactions, budget) with scoped state
  ├── models/        # Scoped serialization and domain models
  ├── screens/       # Core app screen structures and layout routes
  ├── services/      # Business logic, SMS parsing, and file import engines
  ├── shared/        # Reusable global UI elements and layout rules
  └── widgets/       # Core components and modular visual cards

Detailed documentation:

• 📘 Architecture Specifications
• 💡 Design Decisions & Tradeoffs
• 🗺️ Development Roadmap

---

🚀 Getting Started

Prerequisites

• Flutter SDK (3.10.0 or higher)
• Android Studio, VS Code, or Xcode (for iOS compilation)
• CocoaPods (if compiling on macOS for iOS)

Installation & Run

1. Clone the repository:

   git clone https://github.com/masheddesigns/SpendX.git
   cd SpendX

2. Install Flutter packages:

   flutter pub get

3. Configure Environment Variables:

   cp .env.example .env

4. Launch the application:

   flutter run

---

📦 Release Build

To generate a release APK locally:

flutter build apk --release

Expected output:

build/app/outputs/flutter-apk/app-release.apk

---

🔒 Security & Privacy

Since SpendX operates entirely local-first, no personal financial data is ever sent to any remote server.

• SMS parsing is executed on-device using local string patterns.
• Receipt text extraction runs on-device using Google's local ML Kit OCR library.
• Backup and export features generate files locally to place control strictly in your hands.

Review our full security policy in SECURITY.md.

---

🤝 Contributing

We welcome contributions! Please review the setup rules, testing workflows, and branching patterns in CONTRIBUTING.md before opening a pull request.

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.