Application Screens (Jetpack Compose)
Relevant source files
The following files were used as context for generating this wiki page:
- app/src/main/java/io/github/mojri/hesabyar/ui/screens/DashboardScreen.kt
- app/src/main/java/io/github/mojri/hesabyar/ui/screens/SmartAssistantScreen.kt
- app/src/main/java/io/github/mojri/hesabyar/ui/screens/CategoryManagementScreen.kt
- app/src/main/java/io/github/mojri/hesabyar/MainActivity.kt
- app/src/main/java/io/github/mojri/hesabyar/domain/usecase/GetDashboardDataUseCase.kt
- README.md
Introduction
The Hesabyar application utilizes Jetpack Compose and Material 3 to provide a modern, Persian-first user interface for personal finance management. The UI is designed with an offline-first philosophy, ensuring core functionalities remain accessible without an internet connection, while optionally leveraging AI for enhanced data parsing and financial advisory.
The screen architecture follows the MVVM (Model-View-ViewModel) pattern, where Composable functions observe state from ViewModels. The navigation is handled via a centralized MainActivity, which manages the visibility of primary screens such as the Dashboard, Smart Assistant, and various management modules.
Sources: README.md:129-130, MainActivity.kt:70-160
Main Navigation and Layout
The application’s entry point, MainActivity, defines the high-level layout using a Scaffold. It implements a NavigationBar to switch between primary tabs and a ModalBottomSheet for secondary "More" options.
| Tab ID | Label | Icon | Description |
|---|---|---|---|
DASHBOARD | داشبورد | AccountBalanceWallet | High-level financial overview and recent activity. |
ASSISTANT | دستیار هوشمند | AutoAwesome | AI-powered transaction parsing and budget advice. |
LOANS | قرض و وام | HistoryEdu | Management of debts and credits. |
INSTALLMENTS | اقساط | CreditCard | Tracking and paying upcoming installments. |
Sources: MainActivity.kt:85-135
Navigation Flow
The following diagram illustrates how the user navigates between the primary application modules from the MainActivity context.
The application defaults to the DASHBOARD tab and uses a state-driven approach to switch content within the Scaffold body.
Sources: MainActivity.kt:140-215
Dashboard Screen
The DashboardScreen serves as the primary information hub. It aggregates data from multiple ViewModels to present a comprehensive view of the user's financial health, including balances, upcoming obligations, and AI-generated forecasts.
Key Components
- Balance Card: Displays the current lifetime balance, monthly income, and monthly expenses.
- Smart Forecast Alert: A compact card that previews budget forecasts for the next month, derived from
AiAssistantViewModel. - KPI Row: Shows critical financial metrics like "Savings Rate" and "Debt-to-Income Ratio."
- Activity Lists: Mini-items for upcoming installments and the five most recent transactions.
Sources: DashboardScreen.kt:119-385
Data Aggregation and Fallback
The dashboard relies on GetDashboardDataUseCase to compute metrics. It attempts to use the Rust Core for high-performance calculations but provides a Kotlin fallback if the native bridge is unavailable.
Sources: GetDashboardDataUseCase.kt:22-45
Smart Assistant Screen
The SmartAssistantScreen provides two main functionalities: Smart Registration and Budget Advice. It supports both manual text entry and native Persian voice-to-text via an Intent-based Speech Recognition Launcher.
Smart Registration Flow
Users enter a natural language sentence (e.g., "I bought chicken for 450,000 Tomans"). The system parses this into a structured ParsedResult.
- Input: User types or speaks a sentence.
- Analysis:
AiAssistantViewModelparses the input using local NLP or online AI. - Confirmation: If the result has low confidence, a
ConfirmationDialogis shown. - Validation: A
ParsedResultCardallows the user to edit the detected amount, category, or date before final persistence.
Sources: SmartAssistantScreen.kt:66-150, SmartAssistantScreen.kt:530-580
Technical Features Table
| Feature | Implementation | Source File Reference |
|---|---|---|
| Voice Input | RecognizerIntent (fa-IR) | SmartAssistantScreen.kt:47-64 |
| Rich Text | Custom MarkdownText Composable | SmartAssistantScreen.kt:457-525 |
| Confidence Scoring | Visual color-coding (Green/Orange/Red) | SmartAssistantScreen.kt:597-620 |
| Quick Fill | AmountQuickFillButtons for currency | SmartAssistantScreen.kt:682-687 |
Category Management Screen
The CategoryManagementScreen allows users to customize the classification of their transactions. It distinguishes between Default Categories (non-deletable) and Custom Categories.
Functionality
- List View: Uses a
LazyColumnwithStickyHeadersto separate default and user-defined categories. - Editing: A
CategoryDialogallows modification of the category name, English key, icon (from a predefined map), and color. - Icon Mapping: A local
CATEGORY_ICONSmap links string identifiers toIcons.Filledvectors (e.g., "Restaurant", "DirectionsCar").
Sources: CategoryManagementScreen.kt:97-158, CategoryManagementScreen.kt:33-64
Shared UI Components and Design System
The application maintains a consistent look and feel through a dedicated design system.
- Currency Formatting: The
CurrencyFormatterutility handles Rial/Toman conversions, often displayed with bold weights and financial color coding (Green for income, Red for expense). - Date Handling: Dates are managed using a
JalaliDateTimePicker, which combines aJalaliDatePickerDialogwith a custom time picker to ensure compatibility with the Persian calendar. - Tokens: The UI uses centralized tokens for spacing (
SpacingTokens), shapes (ShapeTokens), and dimensions (Dimens).
Sources: DashboardScreen.kt:1022-1088, DashboardScreen.kt:48-60, SmartAssistantScreen.kt:26-40
Summary
The screens in Hesabyar are architected to handle complex financial data while maintaining a simple user experience. By combining the reactive nature of Jetpack Compose with a high-performance Rust core and flexible AI integration, the application provides a robust environment for Persian-speaking users to manage their personal finances effectively.