SpendWise

SpendWise is an open-source Android personal finance tracker built as a portfolio-quality sample app. It demonstrates modern Android engineering with Kotlin, Jetpack Compose, Material 3, MVVM, clean architecture-inspired layering, Hilt, Coroutines, Flow, StateFlow, Room, DataStore Preferences, a fake Retrofit-style API layer, WorkManager simulation, and automated tests.

The app uses local storage as the source of truth and ships with demo finance data so it can run without a backend.

Project Status

The seven planned implementation phases are complete. SpendWise is a working portfolio sample with offline data, CRUD flows, reports, recurring reminders, persisted settings, tests, CI, and learning documentation. Planned extensions are listed in the roadmap rather than presented as existing features.

Feature Overview

• Dashboard with monthly balance, income, expenses, remaining budget, recent transactions, and category analytics
• Transactions list with search, filtering, sorting, detail, edit, and delete flows
• Add transaction form with validation, category/account selection, date selection, and notes
• Budgets by category with progress and over-budget states
• Categories management with default and custom category support
• Accounts management with calculated balance summaries
• Monthly reports with income versus expense, top category, highest transaction, and simple charts
• Recurring transactions with weekly/monthly recurrence and WorkManager-based reminder simulation
• Settings backed by DataStore for currency, dark mode, notifications, monthly budget start day, and demo reset
• Offline-first Room database with fake API refresh simulation

Tech Stack

• Kotlin
• Jetpack Compose and Material 3
• Navigation Compose
• MVVM with immutable StateFlow UI state
• Hilt dependency injection
• Kotlin Coroutines and Flow
• Room
• DataStore Preferences
• WorkManager
• Fake Retrofit-style API services
• JUnit, coroutine tests, Room instrumentation tests, fake repositories, and Compose UI tests

Screens

SpendWise includes these top-level and detail experiences:

• Dashboard
• Transactions
• Add transaction
• Transaction detail
• Budgets
• Categories
• Accounts
• Reports
• Recurring transactions
• Settings
• About

Screenshots are tracked in docs/SCREENSHOTS.md.

Documentation

• Architecture
• Testing
• Data model
• Fake API simulation
• Learning notes
• Interview notes
• Roadmap
• Phase 1 summary
• Phase 2 summary
• Phase 3 summary
• Phase 4 summary
• Phase 5 summary
• Phase 6 summary
• Phase 7 summary

Architecture Overview

SpendWise follows a clean MVVM-style architecture. Composables are mostly stateless, ViewModels expose immutable StateFlow, UI events are sent through ViewModel functions, use cases contain business operations, repositories hide local and fake remote data sources, and mappers convert between DTO, entity, domain, and UI models.

Compose UI
   |
ViewModel
   |
UseCase
   |
Domain repository interface
   |
Data repository implementation
   |
Room database + DataStore + FakeFinanceApiService

More detail is available in docs/ARCHITECTURE.md.

Package Structure

co.bitfuse.spendwise/
  SpendWiseApp.kt
  MainActivity.kt
  core/
    database/
    datastore/
    designsystem/
    navigation/
    network/
  data/
    account/
    budget/
    category/
    mapper/
    recurring/
    repository/
    settings/
    transaction/
  domain/
    model/
    repository/
    usecase/
  feature/
    accounts/
    addtransaction/
    budgets/
    categories/
    dashboard/
    recurring/
    reports/
    settings/
    transactiondetail/
    transactions/
  di/

How To Run

1. Open the project in Android Studio.
2. Let Gradle sync.
3. Select the app run configuration.
4. Run on an emulator or Android device.

Terminal commands:

./gradlew :app:assembleDebug
./gradlew :app:installDebug

Fake API

The fake network layer lives in core/network. FinanceApiService defines Retrofit-style suspend functions and FakeFinanceApiService returns hard-coded demo responses after an artificial delay. Error simulation is available through simulateErrors, disabled by default.

The app can later replace FakeFinanceApiService with a real Retrofit implementation while keeping repository and domain contracts stable.

See docs/API_SIMULATION.md.

Offline-First Storage

Room is the app source of truth for transactions, categories, accounts, budgets, and recurring transactions. Repository refresh methods fetch fake remote data and write it locally. UI observes Room-backed flows, so screens update when local data changes.

Settings are stored separately in DataStore Preferences. Dark mode is observed at the app root and applied through the Compose theme.

See docs/DATA_MODEL.md.

Tests

Tests are organized by layer:

• Unit tests for use cases, validation, aggregation, reports, settings, filtering, and sorting
• Room instrumentation tests for DAO insert/read/update/delete behavior
• Compose UI tests for form validation and settings rendering
• Fake repositories for domain-level tests

Run checks from the terminal:

./gradlew :app:assembleDebug
./gradlew :app:testDebugUnitTest
./gradlew :app:assembleDebugAndroidTest
./gradlew :app:connectedDebugAndroidTest
./gradlew :app:lintDebug

See docs/TESTING.md.

Roadmap

• Add richer chart interactions and visual polish
• Add import/export formats beyond the current fake report action
• Add optional biometric app lock
• Add recurring transaction materialization into real transactions
• Add multi-currency conversion with a real exchange-rate API
• Add screenshot assets for store/GitHub presentation

See docs/ROADMAP.md.

Contributing

Contributions are welcome. Read CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md before opening an issue or pull request.

License

SpendWise is available under the MIT License.