How mohamediliasskaddar/smartbudget works
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: ExpenseRepository.kt Expense Repo · SmartBudgetDatabase.kt Database · AppNavigation.kt App Nav · ExpensesViewModel.kt Expenses VM
Components 34
Presentation
Compose UI, navigation, and screen state
- App Nav · Top-level screen routing and tab structure
app/src/main/java/com/example/smartbudget/ui/navigation/AppNavigation.kt - Bottom Nav · Bottom tab bar for the main app sections
app/src/main/java/com/example/smartbudget/ui/navigation/BottomNavBar.kt - Expenses · Monthly expense list and add/edit entry surface
app/src/main/java/com/example/smartbudget/ui/expenses/ExpensesScreen.kt - Stats · Monthly analytics and category breakdowns
app/src/main/java/com/example/smartbudget/ui/stats/StatsScreen.kt - Settings · App preferences and export surface
app/src/main/java/com/example/smartbudget/ui/settings/SettingsScreen.kt - Expense Sheet · Add and edit expense form presented as a sheet
app/src/main/java/com/example/smartbudget/ui/expenses/AddEditExpenseSheet.kt - Expenses VM · Coordinates expense list state and mutations
app/src/main/java/com/example/smartbudget/ui/expenses/ExpensesViewModel.kt - Stats VM · Prepares aggregated monthly stats for the UI
app/src/main/java/com/example/smartbudget/ui/stats/StatsViewModel.kt - Settings VM · Handles settings actions and export flow
app/src/main/java/com/example/smartbudget/ui/settings/SettingsViewModel.kt - UI Components · 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 · Creates a new expense
app/src/main/java/com/example/smartbudget/domain/usecase/AddExpense.kt - Update Expense · Updates an existing expense
app/src/main/java/com/example/smartbudget/domain/usecase/UpdateExpense.kt - Delete Expense · Deletes an expense
app/src/main/java/com/example/smartbudget/domain/usecase/DeleteExpense.kt - Month Expenses · Fetches expenses for a given month
app/src/main/java/com/example/smartbudget/domain/usecase/GetExpensesByMonth.kt - Month Stats · Builds monthly totals and category stats
app/src/main/java/com/example/smartbudget/domain/usecase/GetMonthStats.kt - Categories · Fetches available categories
app/src/main/java/com/example/smartbudget/domain/usecase/GetCategories.kt - Export CSV · Exports a month to CSV
app/src/main/java/com/example/smartbudget/domain/usecase/ExportMonthCsv.kt
Data
Repositories, models, and local persistence
- Expense Repo · Expense data access boundary
app/src/main/java/com/example/smartbudget/data/repository/ExpenseRepository.kt - Category Repo · Category data access boundary
app/src/main/java/com/example/smartbudget/data/repository/CategoryRepository.kt - Budget Repo · Monthly budget data access boundary
app/src/main/java/com/example/smartbudget/data/repository/BudgetRepository.kt - Expense DAO · Local expense queries and writes
app/src/main/java/com/example/smartbudget/data/local/dao/ExpenseDao.kt - Category DAO · Local category queries and writes
app/src/main/java/com/example/smartbudget/data/local/dao/CategoryDao.kt - Budget DAO · Local monthly budget queries and writes
app/src/main/java/com/example/smartbudget/data/local/dao/MonthlyBudgetDao.kt - Database · System-of-record local database
app/src/main/java/com/example/smartbudget/data/local/SmartBudgetDatabase.kt - Expense Entity · Stored expense record
app/src/main/java/com/example/smartbudget/data/local/entity/ExpenseEntity.kt - Category Entity · Stored category record
app/src/main/java/com/example/smartbudget/data/local/entity/CategoryEntity.kt - Budget Entity · Stored monthly budget record
app/src/main/java/com/example/smartbudget/data/local/entity/MonthlyBudgetEntity.kt - Expense · Core expense business object
app/src/main/java/com/example/smartbudget/data/model/Expense.kt - Category · Core category business object
app/src/main/java/com/example/smartbudget/data/model/Category.kt
Platform
Android app entry and dependency wiring
- MainActivity · Android entry point for the app
app/src/main/java/com/example/smartbudget/MainActivity.kt - App Bootstrap · Application-level composition and startup
app/src/main/java/com/example/smartbudget/SmartBudgetApp.kt - Manifest · Declares the app entry and Android configuration
app/src/main/AndroidManifest.xml - DB Module · Provides database wiring
app/src/main/java/com/example/smartbudget/di/DatabaseModule.kt - Repo Module · Provides repository wiring
app/src/main/java/com/example/smartbudget/di/RepositoryModule.kt
Connections 43
- 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