|
| 1 | +# Database Architecture |
| 2 | + |
| 3 | +> **Status:** Proposed direction. This describes the target architecture introduced by Global Database. It is not a |
| 4 | +> description of the current legacy implementation. |
| 5 | +
|
| 6 | +## Purpose |
| 7 | + |
| 8 | +The database architecture provides one local source of truth for mail data in the application, while keeping |
| 9 | +mail domain code independent of storage technology and legacy storage types. |
| 10 | +It establishes the boundaries that Global Database implements. The [RFC](../engineering/rfcs/0007-global-database.md) |
| 11 | +and [technical design](../engineering/technical-designs/0003-global-database.md) remain the authoritative records |
| 12 | +for its scope and implementation. |
| 13 | + |
| 14 | +## Current and target state |
| 15 | + |
| 16 | +Today, legacy mail storage uses one SQLite database and one attachment directory per account. |
| 17 | + |
| 18 | +Global Database introduces one Room 3-backed mail database and one file-backed attachment directory for the |
| 19 | +application. |
| 20 | + |
| 21 | +## Boundaries and ownership |
| 22 | + |
| 23 | +```mermaid |
| 24 | +flowchart LR |
| 25 | + Caller[Mail domain callers] --> Contract[Focused mail repository contracts] |
| 26 | + Contract --> Implementation[Repository implementations] |
| 27 | + Implementation --> GlobalSource[Global local data sources] |
| 28 | + Implementation --> LegacySource[Legacy local data sources during migration] |
| 29 | + GlobalSource --> MailDatabase[Global mail database] |
| 30 | + GlobalSource --> AttachmentFiles[Global attachment files] |
| 31 | + MailDatabase --> CoreDatabase[core:database] |
| 32 | + LegacySource --> LegacyDatabase[Per-account legacy databases] |
| 33 | + LegacySource --> LegacyFiles[Per-account attachment files] |
| 34 | + AppComposition[Application composition] --> Implementation |
| 35 | +``` |
| 36 | + |
| 37 | +- **Mail repository contracts** are the only storage boundary visible to mail-domain callers. They follow the |
| 38 | + [Repository pattern ADR](../engineering/adr/0010-adopt-project-wide-repository-pattern.md): they are focused, |
| 39 | + explicitly account-scoped, and do not expose Room, SQL, cursors, files, or legacy `LocalStore` types. |
| 40 | +- **Repository implementations and local data sources** belong to the mail feature's internal persistence |
| 41 | + implementation. They own mappings between domain data and both global and legacy representations. |
| 42 | +- **The global mail database** owns the legacy-compatible mail schema, migration metadata, and derived data. |
| 43 | + It is one physical database for the application, not one database per account. |
| 44 | +- **The attachment store** remains file-backed for content that legacy already held on disk, which is every body part |
| 45 | + above a size threshold. Parts at or below it stay `message_parts` BLOBs, as in legacy. Database records and attachment |
| 46 | + files are associated through internal persistence mappings. |
| 47 | +- **`core:database`** implements Room 3 as one domain-neutral backend and provides lifecycle, transaction, migration, |
| 48 | + and Android/JVM desktop driver support needed by the mail implementation. It composes feature schema contributions |
| 49 | + deterministically and owns one coordinated schema and migration history. It must not own mail schema, mail entities |
| 50 | + or DAOs, repository contracts, or mail domain types. |
| 51 | +- **Application composition** binds repository contracts to one implementation. It is the only place that switches from |
| 52 | + legacy to global storage after successful migration. |
| 53 | + |
| 54 | +## Data and migration model |
| 55 | + |
| 56 | +The global schema begins as a compatible representation of the legacy mail-store schema and behavior. |
| 57 | +Account-local numeric IDs are preserved through account-qualified legacy keys. Global identifiers are added only where |
| 58 | +repository contracts require them. |
| 59 | +The [legacy table inventory](../engineering/technical-designs/0003-global-database/legacy-table-inventory.md) |
| 60 | +defines the exact source-to-target mapping, including external attachment files. |
| 61 | + |
| 62 | +Migration has one authoritative storage representation at a time: |
| 63 | + |
| 64 | +| Migration phase | Authoritative storage | Normal mail access | |
| 65 | +|------------------------------------|-------------------------------------------|-----------------------------------------------------------------------------------| |
| 66 | +| Before cutover | Legacy per-account storage | Legacy repository implementation | |
| 67 | +| Import and validation | Legacy per-account storage | Migration gate holds UI and background mail work. Global data remains unpublished | |
| 68 | +| After cutover state is established | Global mail database and attachment store | Global repository implementation | |
| 69 | + |
| 70 | +No normal caller may read from or write to both representations. |
| 71 | +Legacy database and attachment artifacts are deleted only after validation and the durable cutover state is established. |
| 72 | +The legacy storage implementation stays in the codebase, unbound and unused, and a later release removes it. |
| 73 | + |
| 74 | +## Constraints |
| 75 | + |
| 76 | +- Global Database does not redesign or normalize the legacy mail schema. |
| 77 | +- Android and JVM desktop drivers are in scope. The global attachment-store contract is KMP-safe on both targets. |
| 78 | + Legacy import is Android-only. |
| 79 | +- On Android, a dedicated migration screen owns the migration UI. It could reuse the existing database-migration |
| 80 | + activity or introduce a suitable replacement. It shows non-sensitive progress and a completion or failure state with |
| 81 | + retry and local report export. The shared migration gate blocks normal mail access and background sync until cutover |
| 82 | + or failure. |
| 83 | +- Database implementation types remain internal and follow the API/internal module boundary. |
| 84 | +- Migration reports are local and user-exportable, but exclude personally identifiable data and are never uploaded. |
| 85 | + |
| 86 | +## Related documentation |
| 87 | + |
| 88 | +- [RFC 0007: Global Database](../engineering/rfcs/0007-global-database.md) |
| 89 | +- [Technical Design 0003: Global Database](../engineering/technical-designs/0003-global-database.md) |
| 90 | +- [Legacy Table Inventory](../engineering/technical-designs/0003-global-database/legacy-table-inventory.md) |
| 91 | + |
0 commit comments