Data Layer

Scope: owns the DB schema story — entities, DAOs, migrations, schema history, encryption wiring.

Everything that persists lives behind Room + SQLCipher. There is exactly one database (autobudget.db, schema version 8), owned by AppDatabase.

ER diagram

erDiagram
    ACCOUNTS ||--o{ TRANSACTIONS : "accountId (SET NULL)"
    CATEGORIES ||--o{ TRANSACTIONS : "categoryId (SET NULL)"
    RULES ||--o{ TRANSACTIONS : "ruleId (SET NULL)"
    CATEGORIES ||--o{ CORRECTIONS : "categoryId (CASCADE)"
    CATEGORIES ||--o{ BUDGETS : "categoryId (CASCADE)"
    TRANSACTIONS ||--o{ TRANSACTION_ITEMS : "transactionId (CASCADE)"
    TRANSACTIONS ||--o{ ATTACHMENTS : "transactionId (CASCADE)"

    ACCOUNTS {
        long id PK "autoincrement"
        string bankLabel
        string maskedAccount
        string type "AccountType"
        string currency
        boolean isActive
    }
    CATEGORIES {
        long id PK "autoincrement"
        string name
        string icon "material icon id or legacy emoji"
        string kind "CategoryKind EXPENSE|INCOME"
        boolean isDefault
        int sortOrder
    }
    TRANSACTIONS {
        long id PK "autoincrement"
        string notificationKey "unique — dedupe"
        long accountId FK "nullable"
        long amountMillis "minor units"
        string currency
        string direction "Direction"
        string status "Status"
        string merchant
        string rawText "sanitized"
        long occurredAt "notification post time"
        long capturedAt
        string sourcePackage
        long categoryId FK "nullable"
        long ruleId FK "nullable"
        string note
        boolean isReviewed
        boolean isHidden "status != COMPLETED"
        string parseSource "ParseSource JSON|REGEX"
        string rawJson "embedded payload span, JSON only"
        double latitude "nullable — captured-location fix"
        double longitude "nullable"
        float accuracyMeters "nullable"
        string locationProvider "nullable"
        long locationCapturedAt "nullable"
        string placeName "nullable — future reverse geocode"
        string placeId "nullable"
    }
    RULES {
        long id PK "autoincrement"
        string packageName
        string label
        string pattern "Java named-group regex"
        string amountGroup
        string merchantGroup
        string accountGroup
        string directionKind "AUTO|DEBIT|CREDIT"
        string statusKind "AUTO|COMPLETED|PENDING|FAILED|REVERSED"
        int priority
        boolean isEnabled
        string sourceId "unique, nullable — stable seed id (ADR-0019)"
    }
    CORRECTIONS {
        long id PK "autoincrement"
        string packageName
        string merchantNormalized
        long categoryId FK "unique (packageName, merchantNormalized)"
    }
    SETTINGS {
        string key PK
        string value
    }
    UNMATCHED {
        long id PK "autoincrement"
        string sourcePackage
        string rawText
        long capturedAt
        boolean isDismissed
        boolean isMasked "v3+"
        double latitude "nullable — captured-location fix"
        double longitude "nullable"
        float accuracyMeters "nullable"
        string locationProvider "nullable"
        long locationCapturedAt "nullable"
        string placeName "nullable — future reverse geocode"
        string placeId "nullable"
    }
    BUDGETS {
        long id PK "autoincrement"
        long categoryId FK "unique (categoryId, monthStart)"
        long amountMillis
        string currency
        long monthStart
    }
    TRANSACTION_ITEMS {
        long id PK "autoincrement"
        long transactionId FK "CASCADE"
        string name
        long amountMillis "signed minor units"
        int position
    }
    ATTACHMENTS {
        long id PK "autoincrement"
        long transactionId FK "CASCADE"
        string fileName
        string mimeType
        long sizeBytes
        string type "AttachmentType TXT|IMAGE|PDF|CSV|XLSX|DOCX"
        string storedPath "relative path under filesDir/attachments"
        long createdAt
    }

Tables

Enums are stored as strings via Converters (Direction, Status, AccountType, CategoryKind, ParseSource, AttachmentType) with stable dbValue names.

DAOs

Schema versions & migrations

Room schema JSON is exported to app/schemas/ (see ksp { arg("room.schemaLocation", …) } in app/build.gradle.kts) — the basis for schema validation and future migration tests.

Encryption

flowchart LR
    A[DatabasePassphrase.passphrase] -->|AES/GCM decrypt| B[Keystore key: autobudget_sqlcipher_key]
    B -->|256-bit AES key, never exported| K[Android Keystore]
    A --> C[SupportOpenHelperFactory]
    C --> D[Room.databaseBuilder.openHelperFactory]
    D --> E[autobudget.db encrypted by SQLCipher]

• The SQLCipher passphrase is a random 32-byte value generated on first launch, encrypted with an Android Keystore AES-GCM key (autobudget_sqlcipher_key), and stored base64 in the autobudget_crypto SharedPreferences (encrypted_db_passphrase).
• The Keystore key never leaves the device. Wiping app data destroys the key and the ciphertext — history is unrecoverable.
• android:allowBackup="false" plus data_extraction_rules.xml / backup_rules.xml prevent the encrypted DB from leaking into cloud backups or device-to-device transfers.

Repository layer

Repositories are the single funnel for DAO access:

SettingsStore is a tiny interface (get/put/remove) so AppLockManager can be unit-tested against an in-memory fake.

Wiring

Hilt: DatabaseModule provides the SupportOpenHelperFactory (passphrase, loads libsqlcipher.so), the AppDatabase (with addMigrations(MIGRATION_1_2, …, MIGRATION_7_8)), and all ten DAOs. AppModule binds SettingsStore → SettingsRepository, CategoryClassifier → KeywordClassifier, and LocationProvider → AndroidLocationProvider, and provides TransactionNotifier.