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 10), owned by AppDatabase.

ER diagram

Entities and relationship cardinality only — column types, keys and nullability live in Tables and Schema versions and migrations.

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)"

    SETTINGS
    UNMATCHED

Tables

AppDatabase.VERSION is the single schema-version constant: the @Database annotation, the migration-chain fixture and the tests all read it (issue #354). androidx.room.Database is CLASS-retained for KSP, so tests never read it by runtime reflection.

Every table except settings has an autoincrement long id primary key (settings is keyed by its key string); foreign keys and their delete behavior are in the Notes column, and every nullable or migration-sensitive column is called out here or in Schema versions and migrations.

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

DAOs

Schema versions and 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 for the 1→10 upgrade-chain tests (MigrationChainTest, MigrationCoverageTest), which drive the production MIGRATION_* objects with populated fixtures.

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:

The detail editor's atomic save is owned by domain/TransactionSaveUseCase, not by Room: the row, its itemization, its attachment metadata and any review-queue dismissal commit together inside one injected TransactionRunner transaction, while TransactionDetailViewModel keeps the draft, validation, working serialization, navigation and staged-file cleanup (#222). An edit whose row no longer exists fails with MissingTransactionException (mapped to SaveTransactionResult.Failed) before any dependent write; TransactionDao.update returns the affected-row count so the delete-between-read-and-write race fails the same way, and no category override is written for a missing transaction (#290). Deletion is the mirror image: domain/TransactionDeletionUseCase is the single owner (ADR-0075) called by the Activity list, the detail editor and ExportRepository.deleteAllData; the row delete commits inside one TransactionRunner transaction and the now-unreferenced bytes are unlinked after, with a leftover reclaimed by sweepOrphans, which spares every path a live draft owns — each draft holds a durable per-draft reservation (StagedDraftReservations, 30-day TTL) that survives process death, so the protection is not just an in-memory registry — and falls back to a 10-minute grace window for files no draft claims. An unreadable or invalid reservation store is fail-closed: the sweep deletes nothing and reports FileCleanup.skipped. Room is opened with explicit WAL (WRITE_AHEAD_LOGGING), so the repository's DB reads inside the staged-file mutex never wait behind an open write transaction (issue #318). A draft descriptor restored after delete-all is checked against the ledger: a vanished row lands in the terminal not-found state instead of a phantom editor (issue #319).

SettingsStore is a tiny interface (get/getMany/put/remove) so AppLockManager (now in domain/lock/, issue #326) can be unit-tested against an in-memory fake; getMany is one SQLCipher query so the lock ticker no longer reads eight keys sequentially (issue #324).

Wiring

Hilt: DatabaseModule provides the SupportOpenHelperFactory (passphrase, loads libsqlcipher.so), the AppDatabase (with addMigrations(*AppDatabase.PRODUCTION_MIGRATIONS.toTypedArray()) — one list shared with MigrationCoverageTest, issue #354), and all 11 DAOs. AppModule binds SettingsStore → SettingsRepository, CategoryClassifier → KeywordClassifier, LocationProvider → AndroidLocationProvider, TransactionRunner → RoomTransactionRunner, AttachmentSource → AndroidAttachmentSource, and NotificationTapIntents → AndroidNotificationTapIntents, and provides TransactionNotifier.