# mohamediliasskaddar/smartbudget architecture

> Architecture diagram of the GitHub repository mohamediliasskaddar/smartbudget, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohamediliasskaddar/smartbudget
- Repository: https://github.com/mohamediliasskaddar/smartbudget

## Overview

1. **Overall shape**
   - SmartBudget is a single Android app module built around an **offline-first personal budget tracker**. There is no server/backend layer in the repository; all persistence and analytics happen locally on-device.

2. **App entry and composition root**
   - `MainActivity.kt` is the Android entry point.
   - `SmartBudgetApp.kt` appears to be the app-level composition/bootstrap layer.
   - `AndroidManifest.xml` wires the app into Android, while `di/DatabaseModule.kt` and `di/RepositoryModule.kt` provide the main wiring for the data layer.

3. **Presentation layer**
   - The UI is organized as a **Jetpack Compose**-style screen/component structure under `ui/`.
   - Main screens are:
     - `ui/expenses/ExpensesScreen.kt`
     - `ui/stats/StatsScreen.kt`
     - `ui/settings/SettingsScreen.kt`
   - Reusable UI pieces live in `ui/components/` such as category chips/pickers, empty states, month navigation, and summary cards.

4. **Navigation and screen boundaries**
   - `ui/navigation/AppNavigation.kt` and `BottomNavBar.kt` define the app’s primary navigation model.
   - The architecture matches the README’s three-tab structure: **Expenses**, **Stats**, and **Settings**, with an add/edit expense surface presented as a modal sheet rather than a full screen.

5. **State management**
   - Each major screen has a dedicated ViewModel:
     - `ExpensesViewModel.kt`
     - `StatsViewModel.kt`
     - `SettingsViewModel.kt`
   - These ViewModels are the boundary between UI and business logic: they gather data, expose screen state, and trigger actions like add/edit/delete/export.

6. **Domain layer**
   - Business operations are separated into use cases under `domain/usecase/`.
   - The app uses a typical “action per use case” structure:
     - expense CRUD: `AddExpense`, `UpdateExpense`, `DeleteExpense`
     - queries: `GetExpensesByMonth`, `GetMonthStats`, `GetCategories`
     - export: `ExportMonthCsv`
   - This keeps the UI/ViewModels thin and makes month-based calculations and validation logic reusable.

7. **Repository layer**
   - Repositories in `data/repository/` mediate between use cases and storage:
     - `ExpenseRepository`
     - `CategoryRepository`
     - `BudgetRepository`
   - This is the main abstraction boundary for data access. Higher layers work with app models, not Room entities or DAO queries directly.

8. **Local persistence**
   - The app uses **Room-style local storage** in `data/local/`.
   - Database classes (`AppDatabase.kt` and `data/local/SmartBudgetDatabase.kt`) define the local persistence core.
   - DAOs are split by aggregate:
     - `ExpenseDao`
     - `CategoryDao`
     - `MonthlyBudgetDao`
   - Entities live alongside them in `data/local/entity/`, matching the repository’s offline-first storage model.

9. **Data model layer**
   - The app separates storage entities from domain models in `data/model/`.
   - Core business objects are:
     - `Expense`
     - `Category`
     - `MonthlyBudget`
     - `CategoryStats`
   - This separation is important for an accurate architecture diagram: Room entities are persistence-specific, while models are what the UI/domain layer should be seen handling.

10. **Key data flows**
   - Typical flow for expense operations is:
     - UI event in `ExpensesScreen` or add/edit sheet
     - ViewModel invokes a use case
     - use case calls a repository
     - repository reads/writes via DAO
     - Room persists the entity locally
     - ViewModel refreshes UI state for the current month
   - Stats follow a similar path, but the repository/use case layer aggregates month/category totals rather than mutating data.

11. **Export and utility services**
   - `util/CsvExporter.kt` supports the CSV export bonus feature.
   - `DateUtils.kt` and `CurrencyUtils.kt` centralize month handling and amount formatting, which are cross-cutting concerns used by both UI and domain logic.

12. **Feature alignment with the README**
   - The repository structure directly reflects the stated product goals: monthly filtering, expense CRUD, category breakdowns, stats, settings, and CSV export.
   - The presence of `MonthlyBudget` and `BudgetRepository` shows the codebase also anticipates the optional monthly budget feature, even though the core app is still centered on expenses and stats.

13. **Testing and project setup**
   - There are standard Android test and unit test directories under `app/src/androidTest` and `app/src/test`.
   - Gradle Kotlin DSL is used for build configuration (`build.gradle.kts`, `settings.gradle.kts`), which is consistent with a modern Android/Kotlin app structure.

14. **Important architectural boundary to draw**
   - The most important separation in this repo is: **Compose UI + ViewModels** on one side, **use cases/repositories/Room** on the other.
   - Since the app is offline-first, the database is not just a cache; it is the system of record for expenses, categories, and monthly budget data.

Main entry points: [`app/src/main/java/com/example/smartbudget/data/repository/ExpenseRepository.kt`](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/repository/ExpenseRepository.kt) (Expense Repo), [`app/src/main/java/com/example/smartbudget/data/local/SmartBudgetDatabase.kt`](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/SmartBudgetDatabase.kt) (Database), [`app/src/main/java/com/example/smartbudget/ui/navigation/AppNavigation.kt`](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/navigation/AppNavigation.kt) (App Nav), [`app/src/main/java/com/example/smartbudget/ui/expenses/ExpensesViewModel.kt`](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/expenses/ExpensesViewModel.kt) (Expenses VM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_app_nav["App Nav<br/>navigation<br/>[AppNavigation.kt]"]
  node_bottom_nav["Bottom Nav<br/>navigation ui<br/>[BottomNavBar.kt]"]
  node_expenses_screen["Expenses<br/>screen<br/>[ExpensesScreen.kt]"]
  node_stats_screen["Stats<br/>screen<br/>[StatsScreen.kt]"]
  node_settings_screen["Settings<br/>screen<br/>[SettingsScreen.kt]"]
  node_expense_sheet["Expense Sheet<br/>modal sheet"]
  node_expense_vm["Expenses VM<br/>viewmodel"]
  node_stats_vm["Stats VM<br/>viewmodel<br/>[StatsViewModel.kt]"]
  node_settings_vm["Settings VM<br/>viewmodel"]
  node_ui_components["UI Components<br/>shared ui<br/>[TotalCard.kt]"]
end

subgraph group_domain["Domain"]
  node_add_expense["Add Expense<br/>use case<br/>[AddExpense.kt]"]
  node_update_expense["Update Expense<br/>use case<br/>[UpdateExpense.kt]"]
  node_delete_expense["Delete Expense<br/>use case<br/>[DeleteExpense.kt]"]
  node_get_month_expenses["Month Expenses<br/>use case"]
  node_get_month_stats["Month Stats<br/>use case<br/>[GetMonthStats.kt]"]
  node_get_categories["Categories<br/>use case<br/>[GetCategories.kt]"]
  node_export_csv["Export CSV<br/>use case<br/>[ExportMonthCsv.kt]"]
end

subgraph group_data["Data"]
  node_expense_repo["Expense Repo"]
  node_category_repo["Category Repo"]
  node_budget_repo["Budget Repo"]
  node_expense_dao["Expense DAO<br/>room dao<br/>[ExpenseDao.kt]"]
  node_category_dao["Category DAO<br/>room dao<br/>[CategoryDao.kt]"]
  node_budget_dao["Budget DAO<br/>room dao"]
  node_database[("Database")]
  node_expense_entity["Expense Entity<br/>persistence entity<br/>[ExpenseEntity.kt]"]
  node_category_entity["Category Entity<br/>persistence entity<br/>[CategoryEntity.kt]"]
  node_budget_entity["Budget Entity<br/>persistence entity"]
  node_expense_model["Expense<br/>domain model<br/>[Expense.kt]"]
  node_category_model["Category<br/>domain model<br/>[Category.kt]"]
end

subgraph group_platform["Platform"]
  node_main_activity["MainActivity<br/>android entry<br/>[MainActivity.kt]"]
  node_app_bootstrap["App Bootstrap<br/>app root<br/>[SmartBudgetApp.kt]"]
  node_manifest["Manifest"]
  node_db_module["DB Module<br/>di module<br/>[DatabaseModule.kt]"]
  node_repo_module["Repo Module<br/>di module"]
end

subgraph group_shared["Shared"]
end

node_manifest -->|"launches"| node_main_activity
node_main_activity -->|"hosts"| node_app_bootstrap
node_app_bootstrap -->|"wires"| node_db_module
node_app_bootstrap -->|"wires"| node_repo_module
node_main_activity -->|"starts"| node_app_nav
node_app_nav -->|"uses"| node_bottom_nav
node_app_nav -->|"routes"| node_expenses_screen
node_app_nav -->|"routes"| node_stats_screen
node_app_nav -->|"routes"| node_settings_screen
node_expenses_screen -->|"observes"| node_expense_vm
node_expenses_screen -->|"opens"| node_expense_sheet
node_stats_screen -->|"observes"| node_stats_vm
node_settings_screen -->|"observes"| node_settings_vm
node_expenses_screen -->|"composes"| node_ui_components
node_stats_screen -->|"composes"| node_ui_components
node_expense_vm -->|"queries"| node_get_month_expenses
node_expense_vm -->|"mutates"| node_add_expense
node_expense_vm -->|"mutates"| node_update_expense
node_expense_vm -->|"mutates"| node_delete_expense
node_stats_vm -->|"queries"| node_get_month_stats
node_stats_vm -->|"queries"| node_get_categories
node_settings_vm -->|"triggers"| node_export_csv
node_add_expense -->|"uses"| node_expense_repo
node_update_expense -->|"uses"| node_expense_repo
node_delete_expense -->|"uses"| node_expense_repo
node_get_month_expenses -->|"uses"| node_expense_repo
node_get_month_stats -->|"aggregates"| node_expense_repo
node_get_month_stats -->|"aggregates"| node_category_repo
node_get_categories -->|"uses"| node_category_repo
node_export_csv -->|"reads"| node_expense_repo
node_expense_repo -->|"persists"| node_expense_dao
node_category_repo -->|"persists"| node_category_dao
node_budget_repo -->|"persists"| node_budget_dao
node_expense_dao -->|"backed by"| node_database
node_category_dao -->|"backed by"| node_database
node_budget_dao -->|"backed by"| node_database
node_database -->|"stores"| node_expense_entity
node_database -->|"stores"| node_category_entity
node_database -->|"stores"| node_budget_entity
node_expense_repo -->|"maps to"| node_expense_model
node_category_repo -->|"maps to"| node_category_model
node_expense_entity -.->|"translates to"| node_expense_model
node_category_entity -.->|"translates to"| node_category_model

click node_main_activity "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/MainActivity.kt"
click node_app_bootstrap "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/SmartBudgetApp.kt"
click node_manifest "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/AndroidManifest.xml"
click node_db_module "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/di/DatabaseModule.kt"
click node_repo_module "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/di/RepositoryModule.kt"
click node_app_nav "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/navigation/AppNavigation.kt"
click node_bottom_nav "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/navigation/BottomNavBar.kt"
click node_expenses_screen "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/expenses/ExpensesScreen.kt"
click node_stats_screen "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/stats/StatsScreen.kt"
click node_settings_screen "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/settings/SettingsScreen.kt"
click node_expense_sheet "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/expenses/AddEditExpenseSheet.kt"
click node_expense_vm "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/expenses/ExpensesViewModel.kt"
click node_stats_vm "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/stats/StatsViewModel.kt"
click node_settings_vm "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/settings/SettingsViewModel.kt"
click node_ui_components "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/components/TotalCard.kt"
click node_add_expense "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/domain/usecase/AddExpense.kt"
click node_update_expense "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/domain/usecase/UpdateExpense.kt"
click node_delete_expense "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/domain/usecase/DeleteExpense.kt"
click node_get_month_expenses "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/domain/usecase/GetExpensesByMonth.kt"
click node_get_month_stats "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/domain/usecase/GetMonthStats.kt"
click node_get_categories "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/domain/usecase/GetCategories.kt"
click node_export_csv "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/domain/usecase/ExportMonthCsv.kt"
click node_expense_repo "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/repository/ExpenseRepository.kt"
click node_category_repo "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/repository/CategoryRepository.kt"
click node_budget_repo "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/repository/BudgetRepository.kt"
click node_expense_dao "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/dao/ExpenseDao.kt"
click node_category_dao "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/dao/CategoryDao.kt"
click node_budget_dao "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/dao/MonthlyBudgetDao.kt"
click node_database "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/SmartBudgetDatabase.kt"
click node_expense_entity "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/entity/ExpenseEntity.kt"
click node_category_entity "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/entity/CategoryEntity.kt"
click node_budget_entity "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/entity/MonthlyBudgetEntity.kt"
click node_expense_model "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/model/Expense.kt"
click node_category_model "https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/model/Category.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_nav,node_bottom_nav,node_expenses_screen,node_stats_screen,node_settings_screen,node_expense_sheet,node_expense_vm,node_stats_vm,node_settings_vm,node_ui_components toneBlue
class node_add_expense,node_update_expense,node_delete_expense,node_get_month_expenses,node_get_month_stats,node_get_categories,node_export_csv toneAmber
class node_expense_repo,node_category_repo,node_budget_repo,node_expense_dao,node_category_dao,node_budget_dao,node_database,node_expense_entity,node_category_entity,node_budget_entity,node_expense_model,node_category_model toneMint
class node_main_activity,node_app_bootstrap,node_manifest,node_db_module,node_repo_module toneRose
```

## Components

### Presentation

Compose UI, navigation, and screen state

- [App Nav](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/navigation/AppNavigation.kt): navigation · Top-level screen routing and tab structure · `app/src/main/java/com/example/smartbudget/ui/navigation/AppNavigation.kt`
- [Bottom Nav](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/navigation/BottomNavBar.kt): navigation ui · Bottom tab bar for the main app sections · `app/src/main/java/com/example/smartbudget/ui/navigation/BottomNavBar.kt`
- [Expenses](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/expenses/ExpensesScreen.kt): screen · Monthly expense list and add/edit entry surface · `app/src/main/java/com/example/smartbudget/ui/expenses/ExpensesScreen.kt`
- [Stats](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/stats/StatsScreen.kt): screen · Monthly analytics and category breakdowns · `app/src/main/java/com/example/smartbudget/ui/stats/StatsScreen.kt`
- [Settings](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/settings/SettingsScreen.kt): screen · App preferences and export surface · `app/src/main/java/com/example/smartbudget/ui/settings/SettingsScreen.kt`
- [Expense Sheet](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/expenses/AddEditExpenseSheet.kt): modal sheet · Add and edit expense form presented as a sheet · `app/src/main/java/com/example/smartbudget/ui/expenses/AddEditExpenseSheet.kt`
- [Expenses VM](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/expenses/ExpensesViewModel.kt): viewmodel · Coordinates expense list state and mutations · `app/src/main/java/com/example/smartbudget/ui/expenses/ExpensesViewModel.kt`
- [Stats VM](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/stats/StatsViewModel.kt): viewmodel · Prepares aggregated monthly stats for the UI · `app/src/main/java/com/example/smartbudget/ui/stats/StatsViewModel.kt`
- [Settings VM](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/settings/SettingsViewModel.kt): viewmodel · Handles settings actions and export flow · `app/src/main/java/com/example/smartbudget/ui/settings/SettingsViewModel.kt`
- [UI Components](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/ui/components/TotalCard.kt): shared ui · Reusable Compose building blocks such as chips, pickers, and cards · `app/src/main/java/com/example/smartbudget/ui/components/TotalCard.kt`

### Domain

Use cases and business operations

- [Add Expense](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/domain/usecase/AddExpense.kt): use case · Creates a new expense · `app/src/main/java/com/example/smartbudget/domain/usecase/AddExpense.kt`
- [Update Expense](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/domain/usecase/UpdateExpense.kt): use case · Updates an existing expense · `app/src/main/java/com/example/smartbudget/domain/usecase/UpdateExpense.kt`
- [Delete Expense](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/domain/usecase/DeleteExpense.kt): use case · Deletes an expense · `app/src/main/java/com/example/smartbudget/domain/usecase/DeleteExpense.kt`
- [Month Expenses](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/domain/usecase/GetExpensesByMonth.kt): use case · Fetches expenses for a given month · `app/src/main/java/com/example/smartbudget/domain/usecase/GetExpensesByMonth.kt`
- [Month Stats](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/domain/usecase/GetMonthStats.kt): use case · Builds monthly totals and category stats · `app/src/main/java/com/example/smartbudget/domain/usecase/GetMonthStats.kt`
- [Categories](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/domain/usecase/GetCategories.kt): use case · Fetches available categories · `app/src/main/java/com/example/smartbudget/domain/usecase/GetCategories.kt`
- [Export CSV](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/domain/usecase/ExportMonthCsv.kt): use case · Exports a month to CSV · `app/src/main/java/com/example/smartbudget/domain/usecase/ExportMonthCsv.kt`

### Data

Repositories, models, and local persistence

- [Expense Repo](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/repository/ExpenseRepository.kt): repository · Expense data access boundary · `app/src/main/java/com/example/smartbudget/data/repository/ExpenseRepository.kt`
- [Category Repo](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/repository/CategoryRepository.kt): repository · Category data access boundary · `app/src/main/java/com/example/smartbudget/data/repository/CategoryRepository.kt`
- [Budget Repo](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/repository/BudgetRepository.kt): repository · Monthly budget data access boundary · `app/src/main/java/com/example/smartbudget/data/repository/BudgetRepository.kt`
- [Expense DAO](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/dao/ExpenseDao.kt): room dao · Local expense queries and writes · `app/src/main/java/com/example/smartbudget/data/local/dao/ExpenseDao.kt`
- [Category DAO](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/dao/CategoryDao.kt): room dao · Local category queries and writes · `app/src/main/java/com/example/smartbudget/data/local/dao/CategoryDao.kt`
- [Budget DAO](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/dao/MonthlyBudgetDao.kt): room dao · Local monthly budget queries and writes · `app/src/main/java/com/example/smartbudget/data/local/dao/MonthlyBudgetDao.kt`
- [Database](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/SmartBudgetDatabase.kt): room database · System-of-record local database · `app/src/main/java/com/example/smartbudget/data/local/SmartBudgetDatabase.kt`
- [Expense Entity](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/entity/ExpenseEntity.kt): persistence entity · Stored expense record · `app/src/main/java/com/example/smartbudget/data/local/entity/ExpenseEntity.kt`
- [Category Entity](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/entity/CategoryEntity.kt): persistence entity · Stored category record · `app/src/main/java/com/example/smartbudget/data/local/entity/CategoryEntity.kt`
- [Budget Entity](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/local/entity/MonthlyBudgetEntity.kt): persistence entity · Stored monthly budget record · `app/src/main/java/com/example/smartbudget/data/local/entity/MonthlyBudgetEntity.kt`
- [Expense](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/model/Expense.kt): domain model · Core expense business object · `app/src/main/java/com/example/smartbudget/data/model/Expense.kt`
- [Category](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/data/model/Category.kt): domain model · Core category business object · `app/src/main/java/com/example/smartbudget/data/model/Category.kt`

### Platform

Android app entry and dependency wiring

- [MainActivity](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/MainActivity.kt): android entry · Android entry point for the app · `app/src/main/java/com/example/smartbudget/MainActivity.kt`
- [App Bootstrap](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/SmartBudgetApp.kt): app root · Application-level composition and startup · `app/src/main/java/com/example/smartbudget/SmartBudgetApp.kt`
- [Manifest](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/AndroidManifest.xml): android manifest · Declares the app entry and Android configuration · `app/src/main/AndroidManifest.xml`
- [DB Module](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/di/DatabaseModule.kt): di module · Provides database wiring · `app/src/main/java/com/example/smartbudget/di/DatabaseModule.kt`
- [Repo Module](https://github.com/mohamediliasskaddar/smartbudget/blob/main/app/src/main/java/com/example/smartbudget/di/RepositoryModule.kt): di module · Provides repository wiring · `app/src/main/java/com/example/smartbudget/di/RepositoryModule.kt`

## Connections

- Manifest → MainActivity: launches · Android starts the app through the main activity
- MainActivity → App Bootstrap: hosts · Activity hosts the application bootstrap
- App Bootstrap → DB Module: wires · App bootstrap includes database dependency wiring
- App Bootstrap → Repo Module: wires · App bootstrap includes repository dependency wiring
- MainActivity → App Nav: starts · Entry point opens the navigation shell
- App Nav → Bottom Nav: uses · Top-level navigation is driven by bottom tabs
- App Nav → Expenses: routes · Navigation exposes the expenses tab
- App Nav → Stats: routes · Navigation exposes the stats tab
- App Nav → Settings: routes · Navigation exposes the settings tab
- Expenses → Expenses VM: observes · Screen state comes from the expenses view model
- Expenses → Expense Sheet: opens · Add/edit is shown as a modal sheet
- Stats → Stats VM: observes · Stats screen reads aggregated state from its view model
- Settings → Settings VM: observes · Settings screen reads its view model state
- Expenses → UI Components: composes · Screen reuses shared UI building blocks
- Stats → UI Components: composes · Stats screen reuses shared UI building blocks
- Expenses VM → Month Expenses: queries · Expenses VM loads the current month
- Expenses VM → Add Expense: mutates · Adds new expenses through the use case layer
- Expenses VM → Update Expense: mutates · Edits existing expenses through the use case layer
- Expenses VM → Delete Expense: mutates · Deletes expenses through the use case layer
- Stats VM → Month Stats: queries · Stats VM requests month-level aggregates
- Stats VM → Categories: queries · Stats VM can resolve category data for breakdowns
- Settings VM → Export CSV: triggers · Settings VM initiates CSV export
- Add Expense → Expense Repo: uses · Expense creation goes through the repository boundary
- Update Expense → Expense Repo: uses · Expense updates go through the repository boundary
- Delete Expense → Expense Repo: uses · Expense deletion goes through the repository boundary
- Month Expenses → Expense Repo: uses · Monthly expense queries are delegated to the repository
- Month Stats → Expense Repo: aggregates · Monthly stats are derived from expense data
- Month Stats → Category Repo: aggregates · Stats use category data for breakdowns
- Categories → Category Repo: uses · Category lookup is delegated to the repository
- Export CSV → Expense Repo: reads · Export pulls month data from the repository
- Expense Repo → Expense DAO: persists · Expense repository reads and writes through the DAO
- Category Repo → Category DAO: persists · Category repository reads and writes through the DAO
- Budget Repo → Budget DAO: persists · Budget repository reads and writes through the DAO
- Expense DAO → Database: backed by · Expense DAO is hosted by the Room database
- Category DAO → Database: backed by · Category DAO is hosted by the Room database
- Budget DAO → Database: backed by · Budget DAO is hosted by the Room database
- Database → Expense Entity: stores · Database stores expense entities
- Database → Category Entity: stores · Database stores category entities
- Database → Budget Entity: stores · Database stores monthly budget entities
- Expense Repo → Expense: maps to · Repository exposes domain expense models
- Category Repo → Category: maps to · Repository exposes domain category models
- Expense Entity → Expense: translates to · Persistence entity is mapped into the domain model
- Category Entity → Category: translates to · Persistence entity is mapped into the domain model
