Introduction & Features
Relevant source files
The following files were used as context for generating this wiki page:
Hesabyar is a Persian-first personal finance management application for Android, designed with an offline-first philosophy. It provides a robust suite of tools for tracking transactions, managing debts and loans, and monitoring installments. The project distinguishes itself through its hybrid architecture, utilizing a high-performance shared core written in Rust (hesabyar-core) integrated with a modern Android frontend built using Jetpack Compose and Material 3.
The application leverages Artificial Intelligence as an optional enhancement to provide smart insights, natural language transaction parsing, and financial advisory services. By offloading critical business logic—such as Persian NLP, Jalali calendar conversions, and financial analytics—to the Rust core, Hesabyar ensures high performance, memory safety, and cross-platform potential.
Sources: README.md:14-25, AGENTS.md:5-7, rust/hesabyar-core/README.md:5-18
Core Features
Hesabyar provides several modules for comprehensive financial oversight, ranging from basic record-keeping to advanced AI-driven analysis.
Transaction & Debt Management
- Smart Registration: Users can record income and expenses using natural language in Persian.
- Debt/Credit Tracking: Comprehensive management of loans and credits with specific individuals.
- Installment Management: Tracking of recurring payments with automated reminders before due dates.
- Currency Support: Native support for Toman and Rial units, with internal calculations handled in Rial using 64-bit integers to maintain precision.
Sources: README.md:33-58, AGENTS.md:27-29, rust/hesabyar-core/src/ai_validation.rs:207-210
Analytical Dashboard & Reporting
- Visual Analytics: Monthly summaries and category-based breakdowns of financial health.
- Excel Export: Generation of detailed financial reports in
.xlsxformat for external analysis. - Full-Text Search: High-speed transaction search with relevance scoring powered by the Rust core.
Sources: README.md:65-71, README.md:81-85, rust/hesabyar-core/README.md:14-15
AI-Powered Assistant
The "Smart Assistant" module serves as the primary interface for advanced features:
- Natural Language Parsing: Converting Persian sentences (e.g., "I bought chicken for 450,000 Toman today") into structured transaction data.
- Budget Advisory: Providing insights and recommendations based on spending habits, available in both online (Gemini/OpenRouter) and offline modes.
- AI Validation: A dedicated layer in the Rust core that sanitizes and repairs AI-generated JSON to ensure data integrity before database insertion.
Sources: README.md:59-64, rust/hesabyar-core/src/ai_validation.rs:114-120, app/src/main/java/io/github/mojri/hesabyar/ui/screens/SmartAssistantScreen.kt:156-170
Technical Architecture
The application follows a layered architecture, separating the UI, business logic, and data persistence. The most critical component is the Rust Core, which acts as the "Single Source of Truth" for complex logic.
High-Level Component Flow
The following diagram illustrates how user input moves from the Android UI through the Rust logic layer to final storage.
This diagram shows the data flow from the UI layer to the Rust core for processing, and back to the Android repository for persistence.
Sources: README.md:95-125, AGENTS.md:50-55, rust/hesabyar-core/README.md:65-75
Feature Summary Table
| Feature | Description | Implementation Layer |
|---|---|---|
| Persian NLP | Parses natural language sentences into transactions | Rust Core (parser/) |
| Jalali Calendar | High-precision Gregorian ↔ Jalali conversion | Rust Core (calendar.rs) |
| Currency Logic | Formatting and Toman/Rial conversion | Rust Core (currency.rs) |
| AI Sanitization | Repairs and validates LLM outputs | Rust Core (ai_validation.rs) |
| Data Persistence | Encrypted storage of financial records | Android Room (Kotlin) |
| UI Framework | Material 3 and Jetpack Compose | Android (Kotlin) |
Sources: README.md:104-124, rust/hesabyar-core/README.md:7-18, rust/hesabyar-core/src/ai_validation.rs:10-25
Smart Assistant & AI Integration
The Smart Assistant is the central hub for AI-enhanced interactions. It handles two primary workflows: Smart Registration and Budget Advice.
Smart Registration Sequence
The system uses a validation-correction loop to ensure that AI-extracted data adheres to the application's strict data models.
This sequence shows the interaction between the Android ViewModel and the Rust Core's validation logic during a smart transaction entry.
Sources: rust/hesabyar-core/src/ai_validation.rs:114-190, app/src/main/java/io/github/mojri/hesabyar/ui/screens/SmartAssistantScreen.kt:564-600
AI Validation Logic
The hesabyar-core implements rigorous validation for AI responses to prevent database corruption from hallucinated data.
- Category Normalization: Maps diverse AI-generated categories to 8 core database categories (e.g., "Personal Care" → "Shopping").
- Value Clamping: Ensures numeric values like hours (0-23), minutes (0-59), and date offsets (±365 days) are within valid ranges.
- Automatic Repair: If the AI returns a float for an amount, the core truncates it to an integer and logs a "repair note" for the UI to display.
Sources: rust/hesabyar-core/src/ai_validation.rs:64-85, rust/hesabyar-core/src/ai_validation.rs:140-155
Technical Constraints & Standards
To maintain financial accuracy and system stability, the project adheres to several hard constraints:
- Financial Precision: Floating-point numbers (
Float/Double) are strictly forbidden for money. All calculations useLong(representing Rial) orBigDecimal. - Offline First: All core features (tracking, Jalali conversion, offline budget analysis) must function without an internet connection.
- Security: Sensitive data is protected using AES-256-GCM encryption, implemented in the Rust core for high security.
- Memory Safety: The Rust core is compiled without
unsafecode, providing memory safety guarantees that standard JNI implementations lack.
Sources: README.md:88-91, AGENTS.md:38-42, rust/hesabyar-core/README.md:75-80
Conclusion
The Hesabyar system combines the modern UI capabilities of Android with the performance and safety of Rust. By centering its architecture around a shared native core, it provides a highly responsive experience for Persian users while maintaining the rigorous precision required for financial software. The integration of AI, managed through a specialized validation layer in Rust, allows for innovative features like natural language parsing without compromising data integrity.