Achmad Setyabudi Susilo
3e30423083
- Add docs/01-04 covering data model, interfaces, function TODOs, and implementation plan - Add AGENTS.md with project conventions, architecture rules, feature workflow, and git policy - Add CLAUDE.md pointing to AGENTS.md - Copy UI components and utils from info-krl-android (preference widgets, scrollbars, etc.) - Delete obsolete UiModule.kt
413 lines
16 KiB
Markdown
413 lines
16 KiB
Markdown
# 04 — Implementation Plan
|
|
|
|
---
|
|
|
|
## Dependencies to Add
|
|
|
|
In `gradle/libs.versions.toml`:
|
|
|
|
```toml
|
|
[versions]
|
|
room = "2.7.1"
|
|
pdfbox_android = "2.0.27.0"
|
|
|
|
[libraries]
|
|
room-runtime = { group = "androidx.room", name = "room-runtime", version.ref = "room" }
|
|
room-ktx = { group = "androidx.room", name = "room-ktx", version.ref = "room" }
|
|
room-compiler = { group = "androidx.room", name = "room-compiler", version.ref = "room" }
|
|
pdfbox-android = { group = "com.tom-roush", name = "pdfbox-android", version.ref = "pdfbox_android" }
|
|
```
|
|
|
|
In `app/build.gradle.kts`:
|
|
|
|
```kotlin
|
|
ksp(libs.room.compiler)
|
|
implementation(libs.room.runtime)
|
|
implementation(libs.room.ktx)
|
|
implementation(libs.pdfbox.android)
|
|
```
|
|
|
|
**No chart library** — Canvas-based (`drawArc` for pie, `drawRect` for bars).
|
|
**No manifest permissions** — SAF handles file access.
|
|
|
|
---
|
|
|
|
## Package Structure
|
|
|
|
```
|
|
dev.achmad.ledgerr/
|
|
│
|
|
├── core/ (existing)
|
|
│ ├── network/
|
|
│ └── preference/
|
|
│
|
|
├── data/
|
|
│ └── local/
|
|
│ ├── AppDatabase.kt
|
|
│ ├── converter/
|
|
│ │ └── LocalDateConverter.kt - LocalDate <-> Long (epoch day)
|
|
│ ├── dao/
|
|
│ │ ├── CategoryDao.kt
|
|
│ │ ├── ExpenseDao.kt
|
|
│ │ └── RecurringExpenseDao.kt
|
|
│ ├── entity/
|
|
│ │ ├── CategoryEntity.kt
|
|
│ │ ├── ExpenseEntity.kt
|
|
│ │ └── RecurringExpenseEntity.kt
|
|
│ └── mapper/
|
|
│ ├── CategoryMapper.kt
|
|
│ ├── ExpenseMapper.kt
|
|
│ └── RecurringExpenseMapper.kt
|
|
│
|
|
├── di/
|
|
│ ├── CoreModule.kt - provides PreferenceStore as AndroidPreferenceStore
|
|
│ ├── DataModule.kt - DB, DAOs
|
|
│ ├── DomainModule.kt - all interactors
|
|
│ ├── PreferenceModule.kt - preference class singletons
|
|
│ └── util/
|
|
│ └── KoinExtensions.kt (existing)
|
|
│
|
|
├── domain/
|
|
│ ├── preference/
|
|
│ │ ├── AppPreference.kt - app-wide: theme
|
|
│ │ └── ExpensePreference.kt - expense display: default date range filter
|
|
│ │
|
|
│ ├── expense/
|
|
│ │ ├── model/
|
|
│ │ │ ├── DateRange.kt
|
|
│ │ │ ├── Expense.kt
|
|
│ │ │ ├── ExpenseWithCategory.kt
|
|
│ │ │ └── ExpenseSummary.kt
|
|
│ │ └── interactor/
|
|
│ │ ├── GetExpenses.kt
|
|
│ │ ├── UpsertExpense.kt
|
|
│ │ ├── InsertExpenses.kt
|
|
│ │ ├── DeleteExpense.kt
|
|
│ │ ├── ReassignExpenseCategory.kt
|
|
│ │ └── GetExpenseSummary.kt
|
|
│ │
|
|
│ ├── category/
|
|
│ │ ├── model/
|
|
│ │ │ └── Category.kt
|
|
│ │ └── interactor/
|
|
│ │ ├── GetCategories.kt
|
|
│ │ ├── UpsertCategory.kt
|
|
│ │ ├── DeleteCategory.kt
|
|
│ │ └── SeedDefaultCategories.kt
|
|
│ │
|
|
│ ├── recurring/
|
|
│ │ ├── model/
|
|
│ │ │ ├── RecurringExpense.kt
|
|
│ │ │ ├── RecurringExpenseWithCategory.kt
|
|
│ │ │ └── RecurringInterval.kt
|
|
│ │ └── interactor/
|
|
│ │ ├── GetRecurringExpenses.kt
|
|
│ │ ├── UpsertRecurringExpense.kt
|
|
│ │ ├── DeleteRecurringExpense.kt
|
|
│ │ └── ProcessDueRecurringExpenses.kt
|
|
│ │
|
|
│ ├── bankstatement/
|
|
│ │ ├── model/
|
|
│ │ │ ├── PendingImportExpense.kt
|
|
│ │ │ ├── BRIStatementEntry.kt
|
|
│ │ │ ├── JagoStatementEntry.kt
|
|
│ │ │ └── BNIStatementEntry.kt
|
|
│ │ └── interactor/
|
|
│ │ ├── BankStatementImporter.kt - interface
|
|
│ │ ├── ImportBRIBankStatement.kt - stub
|
|
│ │ ├── ImportJagoBankStatement.kt - stub
|
|
│ │ └── ImportBNIBankStatement.kt - stub
|
|
│ │
|
|
│ └── export/
|
|
│ └── interactor/
|
|
│ └── ExportExpensesToCsv.kt
|
|
│
|
|
└── ui/
|
|
├── base/
|
|
│ ├── MainApplication.kt
|
|
│ └── MainActivity.kt (existing)
|
|
├── components/ (copied from info-krl-android, see below)
|
|
│ ├── AppBar.kt
|
|
│ ├── CardSection.kt
|
|
│ ├── FilterChipGroup.kt
|
|
│ ├── HelpCard.kt
|
|
│ ├── LabeledCheckbox.kt
|
|
│ ├── LabeledRadioButton.kt
|
|
│ ├── LazyGridScrollbar.kt
|
|
│ ├── LazyListScrollbar.kt
|
|
│ ├── LinkIcon.kt
|
|
│ ├── Pill.kt
|
|
│ ├── ResultScreen.kt
|
|
│ ├── ScrollbarLazyColumn.kt
|
|
│ ├── ScrollbarLazyGrid.kt
|
|
│ ├── SpotlightOverlay.kt
|
|
│ ├── TabText.kt
|
|
│ └── preference/ (copied from info-krl-android)
|
|
│ ├── Preference.kt
|
|
│ ├── PreferenceItem.kt
|
|
│ ├── PreferenceScreen.kt
|
|
│ └── widget/
|
|
│ ├── AlertDialogPreferenceWidget.kt
|
|
│ ├── BasePreferenceWidget.kt
|
|
│ ├── BasicMultiSelectListPreferenceWidget.kt
|
|
│ ├── CheckPreferenceWidget.kt
|
|
│ ├── EditTextPreferenceWidget.kt
|
|
│ ├── InfoWidget.kt
|
|
│ ├── ListPreferenceWidget.kt
|
|
│ ├── ListSearchPreferenceWidget.kt
|
|
│ ├── MultiSelectListPreferenceWidget.kt
|
|
│ ├── PermissionPreferenceWidget.kt
|
|
│ ├── PreferenceGroupHeader.kt
|
|
│ ├── SwitchPreferenceWidget.kt
|
|
│ ├── TextPreferenceWidget.kt
|
|
│ └── TriStateListDialog.kt
|
|
├── screens/
|
|
│ ├── home/
|
|
│ │ └── HomeScreen.kt - dashboard + recent expenses
|
|
│ ├── expenses/
|
|
│ │ └── ExpenseListScreen.kt - 2-tab screen (Expenses | Recurring)
|
|
│ ├── add_edit_expense/
|
|
│ │ └── AddEditExpenseScreen.kt - shared add & edit
|
|
│ ├── category/
|
|
│ │ └── CategoryScreen.kt
|
|
│ ├── import_bank_statement/
|
|
│ │ └── ImportBankStatementScreen.kt - 1 Voyager Screen, 2 internal composables:
|
|
│ │ ImportBankStatementPickerContent (bank picker + SAF trigger + processing)
|
|
│ │ ImportBankStatementConfirmationContent (review/edit/confirm)
|
|
│ └── settings/
|
|
│ └── SettingsScreen.kt - uses PreferenceScreen component
|
|
├── util/ (copied from info-krl-android)
|
|
│ ├── ColorUtil.kt
|
|
│ ├── ModifierUtil.kt
|
|
│ ├── NavigatorUtil.kt
|
|
│ ├── PreferenceUtil.kt
|
|
│ ├── StringUtil.kt
|
|
│ ├── TextFieldUtil.kt
|
|
│ ├── UiImage.kt
|
|
│ └── UiText.kt
|
|
└── theme/ (existing)
|
|
├── Theme.kt
|
|
└── Type.kt
|
|
```
|
|
|
|
### ScreenModel pattern
|
|
|
|
ScreenModels are **not** registered in Koin. Interactors and preference classes are injected as constructor default parameters using `inject()` from `KoinExtensions`:
|
|
|
|
```kotlin
|
|
class HomeScreenModel(
|
|
private val getExpenses: GetExpenses = inject(),
|
|
private val getExpenseSummary: GetExpenseSummary = inject(),
|
|
private val processRecurring: ProcessDueRecurringExpenses = inject(),
|
|
private val appPreference: AppPreference = inject(),
|
|
) : ScreenModel { ... }
|
|
```
|
|
|
|
In `Screen.Content()`:
|
|
|
|
```kotlin
|
|
val screenModel = rememberScreenModel { HomeScreenModel() }
|
|
```
|
|
|
|
---
|
|
|
|
## Preference Classes
|
|
|
|
### `domain/preference/AppPreference.kt`
|
|
|
|
```kotlin
|
|
class AppPreference(private val store: PreferenceStore) {
|
|
fun appTheme() = store.getEnum("app_theme", defaultValue = AppTheme.SYSTEM)
|
|
}
|
|
|
|
enum class AppTheme { LIGHT, DARK, SYSTEM }
|
|
```
|
|
|
|
### `domain/preference/ExpensePreference.kt`
|
|
|
|
```kotlin
|
|
class ExpensePreference(private val store: PreferenceStore) {
|
|
fun defaultDateRange() = store.getEnum("expense_default_date_range", defaultValue = DateRangeOption.THIS_MONTH)
|
|
}
|
|
|
|
enum class DateRangeOption { THIS_WEEK, THIS_MONTH }
|
|
```
|
|
|
|
---
|
|
|
|
## Navigation
|
|
|
|
Pure stack navigation using Voyager `Navigator`. No `TabNavigator` at the root level.
|
|
|
|
```
|
|
HomeScreen (root)
|
|
├── FAB (expanded) ─────────────────────────── "Manual" → AddEditExpenseScreen
|
|
│ "Import Bank Statement" → ImportBankStatementScreen
|
|
├── Export icon ────────────────────────────── date range dialog → SAF CreateDocument → writes CSV
|
|
├── "See all" / "View expenses" button ──────── → ExpenseListScreen
|
|
│ ├── Tab 1: Expenses list (search + filter)
|
|
│ │ └── FAB (expanded) → "Manual" → AddEditExpenseScreen
|
|
│ │ → "Import" → ImportBankStatementScreen
|
|
│ └── Tab 2: Recurring list
|
|
├── "Manage Categories" button (dashboard) ──── → CategoryScreen
|
|
└── Settings icon ──────────────────────────── → SettingsScreen
|
|
|
|
AddEditExpenseScreen
|
|
└── "Manage Categories" button ───────────────── → CategoryScreen
|
|
|
|
ImportBankStatementScreen (1 Voyager Screen, 1 ScreenModel, 2 composable functions)
|
|
├── ImportBankStatementPickerContent — rendered when state is BankPicker or Processing
|
|
│ • list of banks from List<BankStatementImporter>
|
|
│ • selecting a bank opens SAF OpenDocument picker (PDF)
|
|
│ • loading overlay on top while state is Processing
|
|
└── ImportBankStatementConfirmationContent — rendered when state is Confirmation
|
|
• list of PendingImportExpense
|
|
• toggle selection per row
|
|
• edit amount / date / description / category inline
|
|
• "Import X items" → InsertExpenses.awaitAll() → navigator.pop()
|
|
```
|
|
|
|
Notes:
|
|
- **ExpenseListScreen tabs** are plain Compose `TabRow` / `HorizontalPager` — not Voyager tabs.
|
|
- **FAB expansion** on both `HomeScreen` and `ExpenseListScreen`: tapping reveals two sub-actions; second tap or outside tap collapses it.
|
|
- **Export** — tapping the export icon shows a date range picker dialog (start + end date); after confirming the range the SAF `CreateDocument` picker opens. The ScreenModel writes the CSV (ISO 8601 dates, UTF-8 BOM) when the URI comes back. Export icon lives in `HomeScreen` top bar, `ExpenseListScreen` top bar, and as a `TextPreference` in `SettingsScreen`.
|
|
- **Import** goes through `ImportBankStatementScreen` (one Voyager Screen, one ScreenModel). The ScreenModel owns a `StateFlow<ImportState>` that switches between two internal composables: `ImportBankStatementPickerContent` (BankPicker + Processing overlay) and `ImportBankStatementConfirmationContent` (review, edit, confirm). On confirmation the ScreenModel calls `InsertExpenses.awaitAll()` then pops.
|
|
- **CategoryScreen** reachable from the "Manage Categories" button on `HomeScreen` dashboard and from inside `AddEditExpenseScreen`.
|
|
- **SettingsScreen** uses `PreferenceScreen` component (same pattern as `MoreTab` in info-krl-android). Exposes: theme selector (`ListPreference`), export action (`TextPreference`), clear data (`AlertDialogPreference`).
|
|
|
|
---
|
|
|
|
## DI Wiring
|
|
|
|
### CoreModule
|
|
|
|
```kotlin
|
|
val coreModule = module {
|
|
single {
|
|
get<Context>().getSharedPreferences("ledgerr_prefs", Context.MODE_PRIVATE)
|
|
}
|
|
single<PreferenceStore> { AndroidPreferenceStore(get()) }
|
|
}
|
|
```
|
|
|
|
### DataModule
|
|
|
|
```kotlin
|
|
val dataModule = module {
|
|
single {
|
|
Room.databaseBuilder(androidApplication(), AppDatabase::class.java, "ledgerr.db").build()
|
|
}
|
|
single { get<AppDatabase>().categoryDao() }
|
|
single { get<AppDatabase>().expenseDao() }
|
|
single { get<AppDatabase>().recurringExpenseDao() }
|
|
}
|
|
```
|
|
|
|
### DomainModule
|
|
|
|
```kotlin
|
|
val domainModule = module {
|
|
// expense
|
|
factory { GetExpenses(get(), get()) }
|
|
factory { UpsertExpense(get()) }
|
|
factory { InsertExpenses(get()) }
|
|
factory { DeleteExpense(get()) }
|
|
factory { ReassignExpenseCategory(get()) }
|
|
factory { GetExpenseSummary(get(), get()) }
|
|
|
|
// category
|
|
factory { GetCategories(get()) }
|
|
factory { UpsertCategory(get()) }
|
|
factory { DeleteCategory(get(), get(), get()) }
|
|
factory { SeedDefaultCategories(get()) }
|
|
|
|
// recurring
|
|
factory { GetRecurringExpenses(get(), get()) }
|
|
factory { UpsertRecurringExpense(get()) }
|
|
factory { DeleteRecurringExpense(get()) }
|
|
factory { ProcessDueRecurringExpenses(get(), get()) }
|
|
|
|
// bankstatement
|
|
factory<BankStatementImporter>(named("bri")) { ImportBRIBankStatement(androidContext()) }
|
|
factory<BankStatementImporter>(named("jago")) { ImportJagoBankStatement(androidContext()) }
|
|
factory<BankStatementImporter>(named("bni")) { ImportBNIBankStatement(androidContext()) }
|
|
factory<List<BankStatementImporter>> {
|
|
listOf(get(named("bri")), get(named("jago")), get(named("bni")))
|
|
}
|
|
|
|
// export
|
|
factory { ExportExpensesToCsv(get(), get(), androidContext()) }
|
|
}
|
|
```
|
|
|
|
### PreferenceModule
|
|
|
|
```kotlin
|
|
val preferenceModule = module {
|
|
single { AppPreference(get()) }
|
|
single { ExpensePreference(get()) }
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Key Implementation Details
|
|
|
|
### MainApplication
|
|
|
|
```kotlin
|
|
class MainApplication : Application() {
|
|
override fun onCreate() {
|
|
super.onCreate()
|
|
PDFBoxResourceLoader.init(this)
|
|
startKoin {
|
|
androidLogger()
|
|
androidContext(this@MainApplication)
|
|
modules(coreModule, dataModule, domainModule, preferenceModule)
|
|
}
|
|
CoroutineScope(Dispatchers.IO).launch {
|
|
inject<SeedDefaultCategories>().await()
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Register in `AndroidManifest.xml` as `android:name=".ui.base.MainApplication"`.
|
|
|
|
### AppDatabase seeding
|
|
|
|
After `startKoin` completes in `MainApplication.onCreate`, call `SeedDefaultCategories` via a `CoroutineScope(Dispatchers.IO)`:
|
|
|
|
```kotlin
|
|
CoroutineScope(Dispatchers.IO).launch {
|
|
inject<SeedDefaultCategories>().await()
|
|
}
|
|
```
|
|
|
|
`SeedDefaultCategories.await()` is a no-op if categories already exist, so this is safe to call on every launch. No Room Callback is used for seeding.
|
|
|
|
### Recurring processor trigger
|
|
|
|
`HomeScreen`'s ScreenModel calls `ProcessDueRecurringExpenses` in `init {}`. If any are added, a dismissable banner appears on the dashboard.
|
|
|
|
### SAF file pickers
|
|
|
|
- PDF import: `ActivityResultContracts.OpenDocument(arrayOf("application/pdf"))`
|
|
- CSV export: `ActivityResultContracts.CreateDocument("text/csv")`
|
|
|
|
Launchers registered in the Screen composable; URIs passed to the ScreenModel.
|
|
|
|
---
|
|
|
|
## Build Order
|
|
|
|
1. Domain models (all features)
|
|
2. Domain preference classes
|
|
3. Data: entities, DAOs, `LocalDateConverter`, `AppDatabase`
|
|
4. Mappers
|
|
5. Domain interactors (category → expense → recurring → bank stubs → export)
|
|
6. DI modules
|
|
7. `MainApplication` + manifest
|
|
8. Screens: `HomeScreen` → `ExpenseListScreen` → `AddEditExpenseScreen` → `CategoryScreen` → `ImportBankStatementScreen` → `SettingsScreen`
|
|
9. UI components extracted as needed during screen work
|