# protonmail/proton-mail-android architecture

> Architecture diagram of the GitHub repository protonmail/proton-mail-android, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/protonmail/proton-mail-android
- Repository: https://github.com/protonmail/proton-mail-android

## Overview

##### Main Components and Layers
- User Interface (UI) Layer:
– Encompasses the “app” module’s “src/main/java” directories.
– Contains Activities, Fragments, Composables (in some parts), adapters, view classes, and layouts (XML files in “res/layout”, “res/values”, etc.).
– Also covers integration for testing under “androidTest” and “uiTest”.

- Business/Domain Layer:
– Evident in the “domain” folder that isolates business logic and use cases (e.g. use cases like “DownloadFile”, “UpdateCredentials”, etc.).
– Contains domain entities, repository interfaces, and core business rules.
– This separation supports maintainability and testability.

- Data Layer:
– Contains local databases (e.g. Room databases in local packages under “app/data/local” and related DAOs) and remote API access components (typically in “app/api” folders where Retrofit, OkHttp, and interceptors exist).
– Involves mappers that translate raw API responses to application models.
– Also includes libraries for push notifications (e.g. Firebase Cloud Messaging handling within “app/notifications”) and file attachments.

- Dependency Injection (DI):
– Found in “di” folders (present in both app and production sources) where modules such as ApplicationModule, ViewModelModule, and other DI binders are defined.
– This DI graph organizes presentation, business, and data dependencies.

- Auxiliary Modules and Libraries:
– The project contains additional modules like “tokenAutoComplete”, which is provided both as an example application and as a library.
– There are also separate scripts and “buildSrc” modules that centralize configuration, versioning, and build logic.
– Testing modules (“test”, “androidTest”, “uiTest”, and “sharedTest”) which indicate how the application is validated at various layers.

##### Relationships and Interactions
- UI Layer consumes the Business Layer’s use cases; ViewModels in the UI layer interact with domain operations.
- The Business Layer talks to the Data Layer via repositories and mappers; repositories abstract over both local (database) and remote (network) data sources.
- DI is used across all layers to inject dependencies such as repositories, API clients, and viewmodels.
- Network components (e.g. API clients built on Retrofit/OkHttp) interact with external services (like the ProtonMail API endpoints and Firebase Cloud Messaging for notifications).
- Testing components simulate these flows and provide mocks for data and network calls.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clear division between UI, business logic, and data access.
- Modularization: Different source sets (e.g. alpha, beta, production) indicate feature-based flavors, while “domain”, “app”, and “tokenAutoComplete” are partitioned as separate modules.
- Dependency Injection: DI frameworks (Hilt/Dagger or custom DI as evident from multiple “di” packages) are used extensively.
- MVVM (Model-View-ViewModel) appears to be practiced in the UI layer with observables, viewmodels, and LiveData.
- Repository Pattern: Abstracting data sources and providing a uniform interface.

##### Relevant Technologies, Frameworks, and Libraries
- Android Studio with Gradle (the build system is configured in Kotlin DSL via build.gradle.kts).
- Kotlin as the primary development language.
- Retrofit, OkHttp, and related interceptors for API communication.
- Firebase Cloud Messaging (FCM), albeit in a dummy configuration.
- Room or similar SQLite database libraries for local persistence.
- Testing frameworks that cover unit tests, android tests, and UI tests.
- DI systems coordinated via modules found in “di” directories.
- Custom in-house libraries (such as tokenAutoComplete) and mappers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "ProtonMail Android App"
        UI["\"UI Layer: Activities, Fragments, Composables\""] 
        DM["\"Domain Layer: Use Cases, Entities, Repositories\""]
        
        subgraph "Data Layer"
            LData["\"Local Data: Database, DAOs, Mappers\""]
            RData["\"Remote Data: API Clients & FCM\""]
        end

        DI["\"Dependency Injection\""]
        AUX["\"Auxiliary Modules: tokenAutoComplete\""]
        BUILD["\"Build & Configuration\""]
        TEST["\"Testing Components\""]
    end

    extAPI["\"External: ProtonMail API\""]
    extFCM["\"External: Firebase Cloud Messaging\""]

    UI -->|"calls"| DM
    DM -->|"invokes"| LData
    DM -->|"invokes"| RData

    DI -->|"injects"| UI
    DI -->|"injects"| DM
    DI -->|"injects"| LData
    DI -->|"injects"| RData

    RData -->|"calls"| extAPI
    RData -->|"calls"| extFCM

    AUX ---|"enhances"| UI
    BUILD ---|"configures"| UI
    BUILD ---|"configures"| DM
    BUILD ---|"configures"| LData
    BUILD ---|"configures"| RData
    TEST ---|"validates"| UI
    TEST ---|"validates"| DM
    TEST ---|"validates"| LData
    TEST ---|"validates"| RData

    %% Click Events
    click UI "https://github.com/protonmail/proton-mail-android/tree/release/app/src/main/java/ch/protonmail/android/activities"
    click DM "https://github.com/protonmail/proton-mail-android/tree/release/domain/src/main/kotlin/ch/protonmail/android/domain"
    click LData "https://github.com/protonmail/proton-mail-android/tree/release/app/src/main/java/ch/protonmail/android/data"
    click DI "https://github.com/protonmail/proton-mail-android/tree/release/app/src/main/java/ch/protonmail/android/di"
    click AUX "https://github.com/protonmail/proton-mail-android/tree/release/tokenAutoComplete/tokenAutoComplete-lib"
    click BUILD "https://github.com/protonmail/proton-mail-android/blob/release/build.gradle.kts"
    click TEST "https://github.com/protonmail/proton-mail-android/tree/release/app/src/androidTest"

    %% Styles
    classDef ui fill:#FFE0F0,stroke:#AD1457,stroke-width:2px;
    classDef domain fill:#D0E8FF,stroke:#1565C0,stroke-width:2px;
    classDef data fill:#E0FFD8,stroke:#2E7D32,stroke-width:2px;
    classDef di fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef aux fill:#FFE0B2,stroke:#F57C00,stroke-width:2px;
    classDef build fill:#B3E5FC,stroke:#0288D1,stroke-width:2px;
    classDef test fill:#FFCDD2,stroke:#C62828,stroke-width:2px;

    class UI ui;
    class DM domain;
    class LData data;
    class RData data;
    class DI di;
    class AUX aux;
    class BUILD build;
    class TEST test;
    class extAPI domain;
    class extFCM domain;
```
