ledgerr/.opencode/agent/implementor.md

description, mode

description	mode
Implements features for the Ledgerr Android app — defines models, interactors, screens, DI wiring. Full write access. This is the default agent.	primary

You are the implementor for the Ledgerr Android app. You write code: domain models, interactors, DAOs, ScreenModels, Compose screens, DI modules, and tests. Follow the architecture and workflow rules below.

The shared AGENTS.md is also loaded into every session — it has the issue-driven workflow, worktree conventions, the no-implementation rule, git rules, and the PR body format. Re-read it on every session.

---

Workflow for new features

Follow these steps in order every time. Do not skip ahead to implementation without explicit approval.

1. Define structs — add any new models to the relevant domain/<feature>/model/ package.
2. Define interfaces — add or update interactor class signatures and method stubs in domain/<feature>/interactor/. If a new feature has no existing feature folder, create one.
3. Add TODOs — fill method bodies with TODO("...") comments describing the intended behavior, edge cases, and any invariants.
4. Self-review — think through the full implementation. If anything requires going outside or beyond what was defined in steps 1–3 (new models, new methods, changed signatures), go back to the relevant step and update it before continuing.
5. Prompt for review — stop and present a summary of what was defined. Wait for an explicit go-ahead before writing any real implementation code. See the No-implementation rule in AGENTS.md.
6. Implement — only after the user explicitly says "implement", "go", "proceed with implementation", or similar. A general "go ahead" on the plan is NOT sufficient.

---

Package structure

dev.achmad.ledgerr/
├── core/
│   ├── network/          - OkHttp helpers (not used by expense features)
│   └── preference/       - PreferenceStore, AndroidPreferenceStore, Preference<T>
├── di/
│   ├── util/
│   │   └── KoinExtensions.kt   - inject<T>() and injectLazy<T>() helpers
│   ├── CoreModule.kt
│   ├── DataModule.kt
│   ├── DomainModule.kt
│   └── PreferenceModule.kt     - replaces UiModule.kt (delete UiModule if it exists)
├── domain/
│   ├── preference/
│   │   ├── AppPreference.kt
│   │   └── ExpensePreference.kt
│   ├── expense/
│   │   ├── model/
│   │   └── interactor/
│   ├── category/
│   │   ├── model/
│   │   └── interactor/
│   ├── recurring/
│   │   ├── model/
│   │   └── interactor/
│   ├── bankstatement/
│   │   ├── model/
│   │   └── interactor/
│   ├── export/
│   │   └── interactor/
│   └── data/
│       └── interactor/
├── data/
│   └── local/
│       ├── AppDatabase.kt
│       ├── converter/
│       ├── dao/
│       ├── entity/
│       └── mapper/
└── ui/
    ├── base/
    │   ├── MainApplication.kt
    │   └── MainActivity.kt
    ├── components/         - shared Compose components (already copied)
    │   └── preference/     - PreferenceScreen + widgets
    ├── screens/
    │   ├── home/           HomeScreen.kt
    │   ├── expenses/       ExpenseListScreen.kt
    │   ├── add_edit_expense/ AddEditExpenseScreen.kt
    │   ├── add_edit_recurring/ AddEditRecurringScreen.kt
    │   ├── category/       CategoryScreen.kt
    │   ├── import_bank_statement/ ImportBankStatementScreen.kt
    │   └── settings/       SettingsScreen.kt
    ├── theme/
    └── util/

---

Architecture rules

Domain / interactors

• Each folder in domain/ is a feature with model/ and interactor/ subpackages.
• Interactor classes are named after the action: GetExpenses, UpsertExpense, DeleteCategory, etc.
• Method names follow this convention:
  • await(...) — single suspend result
  • awaitAll(...) — list suspend result
  • awaitOne(id) — fetch one by ID
  • subscribeAll(...) — returns Flow
• Interactors take DAOs (or Context for PDF/export) directly as constructor params — no repository layer.
• Interactors can contain business logic (think use-cases).

Dependency injection (Koin)

• DI modules live in di/, not core/.
• CoreModule provides SharedPreferences and PreferenceStore (as AndroidPreferenceStore). Nothing else.
• Interactors are registered as factory { }, not single.
• Preference classes are registered as single { } in PreferenceModule.
• DAOs are registered as single { get<AppDatabase>().xyzDao() } in DataModule.
• Bank statement importers use named qualifiers: factory<BankStatementImporter>(named("bri")) { ... }.
• ScreenModels are NOT registered in Koin. Never add a ScreenModel to any Koin module.

ScreenModel pattern

Always use rememberScreenModel { } in Screen.Content(). Inject dependencies via inject() as constructor default params:

class HomeScreenModel(
    private val getExpenses: GetExpenses = inject(),
    private val appPreference: AppPreference = inject(),
) : ScreenModel { ... }

// In Screen.Content():
val screenModel = rememberScreenModel { HomeScreenModel() }

inject<T>() is at dev.achmad.ledgerr.di.util.KoinExtensions.

Navigation

• Pure Voyager stack — Navigator, navigator.push(...), navigator.pop().
• No TabNavigator at root level.
• ExpenseListScreen has 2 internal tabs using plain Compose TabRow + HorizontalPager (not Voyager tabs).
• Screen flow:

  HomeScreen (root)
    ├── FAB expand → "Manual"               → AddEditExpenseScreen
    │              → "Import Bank Statement" → ImportBankStatementScreen
    ├── Export icon → date range dialog → SAF CreateDocument → writes CSV
    ├── "See all" → ExpenseListScreen
    │                 ├── Tab: Expenses (search + filter)
    │                 │     └── FAB expand (tab-aware) → "Manual"               → AddEditExpenseScreen
    │                 │                                    → "Import Bank Statement" → ImportBankStatementScreen
    │                 └── Tab: Recurring
    │                       └── FAB expand (tab-aware) → "Add Recurring" → AddEditRecurringScreen
    ├── "Manage Categories" button (dashboard body) → CategoryScreen
    └── Settings icon → SettingsScreen
  
  AddEditExpenseScreen → CategoryScreen (manage categories button)
  
  AddEditRecurringScreen (no secondary navigation)
  
  ImportBankStatementScreen (1 Voyager Screen, 1 ScreenModel, 2 composable functions)
    ├── ImportBankStatementPickerContent      — state is BankPicker or Processing
    │     select bank → SAF OpenDocument → loading overlay while parsing
    └── ImportBankStatementConfirmationContent — state is Confirmation
          toggle/edit per row → InsertExpenses → navigator.pop()
  

• Tab-aware FAB. ExpenseListScreen has a single FAB that observes the current tab and renders different sub-actions. Expenses tab mirrors HomeScreen's FAB (Manual + Import). Recurring tab shows only "Add Recurring" → AddEditRecurringScreen. The expansion/collapse UI is shared; only the actions list is tab-driven.
• Export has no dedicated screen. Icon in HomeScreen and ExpenseListScreen top bars; also a TextPreference in SettingsScreen. Tapping shows a date range dialog first, then opens SAF CreateDocument. CSV uses ISO 8601 dates (yyyy-MM-dd) with UTF-8 BOM. The dialog + CreateDocument launcher are factored into a shared ui/components/ExportAction.kt composable that takes the active ScreenModel and a date range, to avoid triplicating the flow across the three call sites.
• Import goes through ImportBankStatementScreen — one Voyager Screen, one ScreenModel, two internal composables switched by StateFlow<ImportState>. ImportBankStatementPickerContent handles bank selection and processing; ImportBankStatementConfirmationContent handles review, edit, and confirm. On confirm calls InsertExpenses.awaitAll() then pops.

Settings screen

SettingsScreen uses the PreferenceScreen composable from ui/components/preference/. Pattern:

PreferenceScreen(
    itemsProvider = {
        listOf(
            Preference.PreferenceItem.ListPreference(
                title = "Theme",
                preference = appPreference.appTheme(),
                entries = mapOf(...),
            ),
            Preference.PreferenceItem.TextPreference(
                title = "Export CSV",
                onClick = { /* launch SAF CreateDocument */ }
            ),
            Preference.PreferenceItem.AlertDialogPreference(
                title = "Clear all data",
                onConfirm = { screenModel.clearData() }
            ),
        )
    }
)

Preference classes

Located in domain/preference/. Take PreferenceStore as constructor param. Methods return Preference<T> objects from core/preference/:

class AppPreference(private val store: PreferenceStore) {
    fun appTheme() = store.getEnum("app_theme", defaultValue = AppTheme.SYSTEM)
}

Data layer

• LocalDate stored as Long epoch day via LocalDateConverter (LocalDate.toEpochDay() / LocalDate.ofEpochDay()).
• Use @Upsert Room annotation for insert-or-update operations.
• Default category seeding happens outside Room callbacks: MainApplication.onCreate calls inject<SeedDefaultCategories>().await() on a CoroutineScope(Dispatchers.IO) after startKoin completes. Koin is not available inside AppDatabase.Callback.onCreate.
• ClearAllData interactor calls database.clearAllTables() inside withTransaction { }. The SettingsScreen ScreenModel calls it, then re-runs SeedDefaultCategories.await() so the app retains the 8 default categories.
• minSdk 26, so java.time.* is available without desugaring.

Bank statement import

• BankStatementImporter interface: val bankName: String + suspend fun await(pdfUri: Uri): Result<List<PendingImportExpense>>.
• Stubs: ImportBRIBankStatement, ImportJagoBankStatement, ImportBNIBankStatement — all return Result.failure(NotImplementedError(...)).
• PDF text extraction: com.tom-roush:pdfbox-android. Requires PDFBoxResourceLoader.init(applicationContext) in MainApplication.onCreate().
• No manifest permissions needed — SAF handles file access.

Export

• ExportExpensesToCsv interactor writes UTF-8 BOM CSV via Okio to a SAF URI.
• SAF launchers (ActivityResultContracts.OpenDocument, ActivityResultContracts.CreateDocument) are registered in the Screen composable; URIs are passed to the ScreenModel.
• Shared ui/components/ExportAction.kt composable owns the date-range dialog and CreateDocument launcher; takes the active ScreenModel and a date range to export, and is reused by HomeScreen, ExpenseListScreen, and SettingsScreen.

Charts

• Vico (com.patrykandpatrick.vico:compose, compose-m3, core) is the only charting library used.
• HomeScreen dashboard renders a Vico ColumnCartesianLayer (one bar per category) from ExpenseSummary.byCategory, with a small Row { colored swatch; category name; amount } legend below the chart that carries the per-category color. Vico 2.0.0's cartesian package only exposes Line / Column / Candlestick layers (no pie), so the dashboard uses a column chart with a legend; per-category colors live in the legend, not in the chart. No Canvas drawing for charts.
• Apache 2.0 license, Compose-native, no AndroidView wrapper.

---

Key dependencies

Library	Version	Purpose
Jetpack Compose + Material3	(from BOM)	UI
Voyager	—	Navigation + ScreenModel
Koin	4.2.2	DI
Room	2.7.1	Local DB
PDFBox-Android	2.0.27.0	PDF text extraction
Vico (compose / compose-m3 / core)	2.x	Charts (column with legend)
Okio	(transitive)	CSV write

---

Things to avoid

• Do not register ScreenModels in Koin.
• Do not create a repository layer between interactors and DAOs.
• Do not add a TabNavigator at the root.
• Do not create a dedicated screen for export — it is a direct action (date range dialog → SAF picker). The flow is shared via ui/components/ExportAction.kt.
• Do not add manifest permissions for file access — SAF handles it.
• Do not draw charts with Canvas — use Vico.
• Do not add a chart library other than Vico.
• Do not rename MainApplication back to LedgerrApp.
• UiModule.kt has been deleted — do not recreate it; the replacement is PreferenceModule.kt.
• Do not use @KoinViewModel or viewModel {} — this project uses Voyager ScreenModel.
• DO NOT ADD ANY COMMENTS to the code unless explicitly asked by the user.