Getting Started & Setup
Relevant source files
The following files were used as context for generating this wiki page:
Hesabyar is a Persian-first personal finance application for Android that utilizes an offline-first architecture. The project is built using a hybrid technology stack, combining Kotlin for the Android UI (Jetpack Compose) and Rust for the shared business logic core (hesabyar-core). This technical guide provides the necessary steps to configure the development environment, build the native components, and execute the application.
The setup process involves preparing both the Android and Rust toolchains. The Rust core handles critical performance-sensitive tasks such as Persian NLP, Jalali calendar conversions, and financial analytics, which are exposed to the Kotlin layer via UniFFI.
Sources: README.md:1-55, AGENTS.md:1-10, rust/hesabyar-core/README.md:1-15
Prerequisites
Before starting, ensure your development machine meets the following requirements:
Software Requirements
| Category | Requirement |
|---|---|
| JDK | Version 21 or higher |
| Android Studio | Latest stable version |
| Rust Toolchain | Version 1.75.0 or higher |
| Android NDK | Required for cross-compiling Rust for Android |
Sources: README.md:144-150, rust/hesabyar-core/README.md:21-23
Native Build Targets
To support the various Android architectures, the following Rust targets must be installed:
aarch64-linux-android(arm64-v8a)armv7-linux-androideabi(armeabi-v7a)i686-linux-android(x86)x86_64-linux-android(x86_64)
Additionally, the cargo-ndk tool is required for the cross-compilation process.
Sources: README.md:162-167, rust/hesabyar-core/README.md:25-28
Environment Configuration
The project uses a .env file to manage secrets and API keys. This file is mapped to BuildConfig fields via a secrets plugin.
- Copy the Template: Copy
.env.exampleto.env. - AI Features: Set the
GEMINI_API_KEYto enable optional AI-driven financial insights. - Release Signing: For release builds, provide
KEYSTORE_PASSWORD,KEY_ALIAS, andKEY_PASSWORD.
Sources: README.md:156-160, AGENTS.md:26-30
Building the Project
The build process is divided into compiling the Rust core and building the Android application.
1. Build Rust Shared Core
The Rust logic must be compiled into native libraries (.so files) for each Android ABI. This can be done via Gradle or Cargo.
# Via Gradle (Recommended)
./gradlew :app:assembleRust --no-daemon
# Via Cargo (Manual)
cd rust && cargo build --target aarch64-linux-android --release
Sources: README.md:175-180, rust/hesabyar-core/README.md:33-40
2. Generate Kotlin Bindings
The project uses UniFFI to bridge Kotlin and Rust. Bindings must be generated after the native library is built.
./gradlew :app:generateRustBindings --no-daemon
Sources: README.md:184-186, rust/hesabyar-core/README.md:43-51
3. Build & Install Android App
Once native libraries and bindings are ready, build the debug APK:
./gradlew installDebug --no-daemon
Sources: README.md:190-192, AGENTS.md:11-13
Initialization & Runtime Flow
The application initializes the Rust core lazily. The HesabyarApp companion object manages the loading of the hesabyar_core native library.
The initialization ensures that features like the Jalali calendar are wired to the Rust core upon first call.
Sources: app/src/main/java/io/github/mojri/hesabyar/HesabyarApp.kt:25-75, app/src/main/java/io/github/mojri/hesabyar/rust/RustBridge.kt:19-30
Testing & Verification
The project enforces a strict verification workflow after any code modification.
Core Testing Commands
| Command | Description |
|---|---|
./gradlew test --no-daemon | Executes Kotlin unit tests (JUnit/Robolectric) |
cd rust/hesabyar-core && cargo test | Executes Rust core logic tests |
./gradlew ktlintCheck detekt --no-daemon | Runs static analysis and linting |
cd rust/hesabyar-core && cargo bench | Runs performance benchmarks using Criterion |
Sources: README.md:200-216, AGENTS.md:88-105
Rust Bridge Verification
The RustBridgeTest.kt file ensures that the Kotlin-to-Rust communication is functional. It checks if the native core is available and verifies that methods like gregorianToJalaliSync produce deterministic results.
Sources: app/src/test/java/io/github/mojri/hesabyar/rust/RustBridgeTest.kt:20-60
Conclusion
Setting up Hesabyar requires a synchronized configuration of Android and Rust environments. By compiling the native core and generating UniFFI bindings, developers enable high-performance financial logic within the Android application. Following the mandatory verification workflow ensures that code changes maintain project standards for financial accuracy and offline functionality.