Architecture Overview

Scope: owns the system map, layer diagram, module map, and the descriptive ADR index table.

What AutoBudget is

AutoBudget is an offline-first Android budget tracker for the Malaysian market. A NotificationListenerService captures bank and e-wallet push notifications, a pure-Kotlin parser engine turns them into transactions, a keyword classifier categorizes them, and everything is stored in a SQLCipher-encrypted Room database and shown in a Jetpack Compose UI.

There is no server and no cloud. No app code performs network I/O; the release manifest nevertheless carries network permissions merged from the MapLibre map renderer (ADR-0015 Amendment).

System context

flowchart LR
    subgraph Device
        subgraph "Bank & wallet apps (user-enrolled)"
            B1[Maybank2u / MAE]
            B2[TNG eWallet / GrabPay / Boost]
            B3[BigPay / CIMB / PBe / RHB / ShopeePay / Wise]
        end

        subgraph AutoBudget
            L[NotificationListenerService]
            P[CapturePipeline]
            D[(SQLCipher Room DB)]
            U[Compose UI]
            K[Android Keystore]
        end

        subgraph "System services"
            NL[NotificationManagerService]
        end
    end

    B1 -->|notification| NL
    B2 -->|notification| NL
    B3 -->|notification| NL
    NL -->|posted + replay| L
    L --> P
    P --> D
    D <--> U
    D -.passphrase encrypted.-> K
    U -->|user actions| D

Layered architecture

flowchart TB
    subgraph UI["ui/ — Compose screens + ViewModels"]
        NAV[AutoBudgetNavHost]
        VM[Home / Transactions / Budgets / Reports / Settings / Onboarding / Unmatched / Lock ViewModels]
        SHARED[shared components: TransactionRow, MonthSelector, EmptyState, SectionHeader, CategoryIcon]
    end

    subgraph DOMAIN["domain/ — use cases and seams"]
        CC[CategoryClassifier interface]
        KC[KeywordClassifier]
        TR[TransactionRunner seam]
        SU[TransactionSaveUseCase]
        DU[TransactionDeletionUseCase]
    end

    subgraph PARSER["parser/ — pure Kotlin, no Android deps"]
        PE[ParserEngine]
        AP[AmountParser]
        ND[DirectionDetector / StatusDetector]
        EJ[EmbeddedJsonParser]
        NK[NotificationKey]
        MN[MerchantNormalizer]
    end

    subgraph LISTENER["listener/ — capture"]
        NLS[TransactionNotificationListener]
        EX[NotificationExtractor]
        NF[NotificationFilter]
        CP[CapturePipeline]
        TN[TransactionNotifier / NotificationGate]
        LOC[LocationProvider]
    end

    subgraph DATA["data/ — Room, repositories"]
        DB[AppDatabase + SQLCipher]
        ENT[Entities]
        DAO[DAOs]
        REPO[Repositories]
        SEED[DefaultCategories + BankRuleSets]
    end

    subgraph COMMON["common/ — money, export, security, time"]
        MONEY[Currency / MoneyFormatter / MoneyText]
        EXP[ExportCodec / UnmatchedJsonCodec / UnmatchedExportCodec]
        LOCK[AppLockManager / LockClock]
        TR[TimeRange]
        NA[NotificationAccess]
    end

    NAV --> VM
    VM --> REPO
    VM --> COMMON
    VM --> SHARED

    REPO --> DAO
    DAO --> ENT
    ENT --> DB
    SEED --> DAO

    CP --> NF
    CP --> PE
    CP --> CC
    CP --> REPO
    CP --> NK
    CP --> TN
    NLS --> EX
    NLS --> LOC
    NLS --> CP

    PE --> AP
    PE --> ND
    PE --> EJ
    CC --> MN
    CC --> DAO

    MONEY --> AP
    LOCK --> REPO

Layering rule: parser/ and the money codecs in common/ plus the export codecs in data/export/ are pure Kotlin — no Android imports — so they are unit-testable on the JVM without Robolectric. Everything else may depend on Android. Nothing may depend upward: common/ never imports data/ (breaking the old cycle), listener/ and qs/ never import ui/, domain/ has no android.* imports, and parser/ never imports ui/. ui/ talks to data/ only through repositories and ViewModels. scripts/arch-guard.sh enforces these edges in CI (issue #326).

Startup

AutoBudgetApp runs first-run seeding, the orphan sweep and the receipt-cache sweep through StartupCoordinator, which retries once and exposes Loading | Ready | Failed. MainActivity gates content with StartupGate: a failure shows a recoverable "Try again" screen instead of an uncaught coroutine exception (issue #321).

Module map

Capture & deduplication

The notification → transaction sequence, routing table, replay behavior, duplicate suppression and cross-source dedupe live in ingestion-pipeline.md; the dedupe key formula is defined in parser.md.

Why the design looks the way it does

Each decision below is formalized as a numbered ADR under docs/adr/ with context, decision, and consequences — read the ADR before changing behavior in its area:

Related docs

• Data layer — ER diagram, entities, DAOs, migrations
• Ingestion pipeline — listener, filter, pipeline sequence
• Parser engine — rules, amount parsing, confidence, golden tests
• Classification — the CategoryClassifier seam
• Money — minor units, currency tables, formatting
• UI layer — navigation graph, screens, ViewModels, adaptive layout
• Security — app lock, masking, backup policy
• Tooling — build, 16 KB support, CI, tests, release