UI Layer

Scope: owns navigation, screens, ViewModel pattern, shared components, charts, adaptive layout.

Jetpack Compose (Material 3), single-activity, navigation-compose, Hilt view models. All screens live in ui/; shared components in ui/components.

Navigation graph

flowchart LR
    START([startDestination: onboarding or home]) --> ONB[onboarding]
    ONB -->|finish| HOME
    HOME -->|View all| TX[transactions]
    HOME -->|tap row| TD["transaction/{id}"]
    HOME -->|badge| UN[unmatched]
    TX -->|row tap| TD
    TX -->|FAB +| MT["transaction/manual/true"]
    UN -->|Create transaction| UC["unmatched/{unmatchedId}"]
    TD -->|pop| HOME
    TD -->|pop| TX
    UC -->|pop| UN
    MT -->|pop| TX
    SETTINGS[settings] -->|rules| RULES["settings/rules/{package}"]
    BUD[budgets] -->|FAB + / swipe right| CE["category/{id}"]
    REP[reports]
    REP -->|View transactions| DRILL["transactions/drill?monthStart={monthStart}&categoryId={categoryId}"]

Deep links (autobudget://transaction/{id}) arrive as a pendingRoute on MainActivity and are navigated once the nav graph is attached — the AutoBudgetNavHost pending-route effect is keyed on the first back-stack entry so a cold-start deep link never races the graph setup.

Routes are defined in object Routes in AutoBudgetNavHost.kt:

MANUAL_TRANSACTION and UNMATCHED_CREATE share TransactionDetailScreen — the ViewModel picks the mode from SavedStateHandle args (manual == "true", or unmatchedId != null).

Deep links (ADR-0031)

ui/navigation/DeepLinks.kt is the single owner of the autobudget:// contract: producers build links only through its builders, consumption goes only through DeepLinks.parse(uriString); Routes.fromDeepLink is the thin Uri → route adapter on top. Works cold start and warm start (onNewIntent); everything a link opens sits behind the app lock (ADR-0012).

Grammar: autobudget://{target}[/{segment}][?key=value&…]

Manual prefill params (all optional, validated by DeepLinks, dropped when invalid): amount = positive integer minor units (ADR-0009), currency = supported ISO code, merchant ≤ 120 chars, note ≤ 500, source = triggering package ≤ 120. Unknown hosts/segments/malformed required args ⇒ the link is ignored; unknown params are dropped — forward-compatible in both directions.

Producers today: the captured-notification tap (ADR-0016), the Quick Settings "Add transaction" tile (qs/AddTransactionTileService), and tooling tab launches. There are deliberately no intent-filters and no exported components beyond the launcher activity — see ADR-0031 for the security posture and how to add a new entry point.

Adaptive navigation

AutoBudgetNavHost computes WindowWidthSizeClass:

• Compact (phones) → NavigationBar (bottom). The Home tab sits in the center and uses the default Material 3 selected indicator like every other tab (no custom circle overlay).
• Medium / Expanded (tablets, desktop) → NavigationRail (left), NavHost in a weighted Row.

Tab switching uses direction-aware slide transitions (320 ms): sliding toward the selected tab right when moving down the bar, left when moving up; pushed detail screens always slide in from the end.

Tab navigation never restoreState for the start destination (restoreStateForTab in ui/navigation/TabNavigation.kt): popUpTo(start) { saveState = true } stores the popped stack under the start destination's id, so restoring state on a navigation back to it would immediately re-open the screen we just left. The Home tab therefore always lands on Home, while other tab switches keep their scroll/filter state.

Screens & view models

Reactive state pattern

Screen state is exposed as StateFlows held with stateIn(WhileSubscribed(5_000)). The four month-scoped data screens (Home, Transactions, Budgets, Reports) build it with the shared pattern combine(...) + flatMapLatest over a _monthStart MutableStateFlow; simpler screens (onboarding, lock, rule editor, category editor) use plain MutableStateFlows without flatMapLatest. Aggregation (spent/income/per-category) is computed per screen in the ViewModels — there are no SQL aggregations (ADR-0006: filtering is in-memory).

Shared components (ui/components)

Theming

ui/theme:

• AutoBudgetTheme(darkTheme, dynamicColor) → Material 3 scheme; custom green/teal light + dark palettes (Color.kt); dynamic color on Android 12+ when enabled.
• ThemeMode (SYSTEM / LIGHT / DARK) + dynamic color persisted in settings (KEY_THEME_MODE, KEY_DYNAMIC_COLOR); MainActivity applies edge-to-edge system-bar contrast to match.
• Type.kt / Shape.kt define the design tokens.

Charts

ReportScreen renders its charts with io.github.ehsannarmani:compose-charts 1.0.0 (ADR-0028, superseding ADR-0013):

• Donut (ui/reports/charts/DonutChart.kt): library PieChart in Pie.Style.Stroke; the library's label helper is disabled (LabelHelperProperties(enabled = false), on by default upstream) because legend rows stay app-side; center total and selection bubble stay app-side too (no pie popup/hole text upstream). Legend and tooltip share one percent formatter (formatPercent, rounding half-up, <1% below one percent) so the two never disagree.
• Trend (ui/reports/charts/TrendChart.kt): library ColumnChart with gridlines and a base-currency value scale; month labels are Compose Texts and taps land on an overlay row of per-bar cells that also carry the contentDescription summaries (library canvas labels are invisible to TalkBack). The axis is a nice 1-2-5 scale (niceTrendAxis in ChartAdapters.kt) with compact k/M indicator labels; explicit indicator/gridline lists keep ticks and lines aligned. Non-zero bars shorter than 3% of the axis height are floored to it so small months stay visible. Selection state is keyed to the data (remember(trend) / remember(slices)), so switching months never shows a stale tooltip.

All colors derive from the theme's full-tone accents via buildReportChartPalette (ADR-0029): slots 0–2 are primary/tertiary/ secondary; slots 3–7 are hue-rotated, saturation-stepped derivatives of primary; every slot is contrast-corrected to ≥3:1 against the card's surfaceContainer. Semantic colors (error, containers, outline) are never used. Slices under 2% of the month total merge into one "Other" row (mergeSmallSlices) so hairline wedges stay legible. Mapping to library models is pure Kotlin in ChartAdapters.kt (JVM-unit-tested), and money strings are always formatted from Long minor units via MoneyFormatter. The version is pinned because newer releases require Kotlin 2.3.10; re-check metadata compatibility before bumping. Both charts disable the library's label helper — for PieChart to keep the legend app-side, and for ColumnChart because its default-on legend renders an unlabeled color dot near the card title.

Related

• Architecture overview
• Security — lock screen
• Tooling — Compose previews & tests