# tutao/tutanota architecture

> Architecture diagram of the GitHub repository tutao/tutanota, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tutao/tutanota
- Repository: https://github.com/tutao/tutanota

## Overview

##### Project type and purpose
- This is a mono-repo containing the Tuta Mail client ecosystem: a secure, end-to-end encrypted email client available on Web, Desktop (Electron), Android and iOS.
- It also ships a cross-platform SDK (Rust + TypeScript/WebAssembly), shared business-logic libraries, cryptography packages, and extensive build/CI tooling.

##### Top-level structure and architectural zones
- Clients:
– src/… → Web client (TypeScript + Mithril, Web Workers)
– common/desktop, desktop.js, resources/… → Electron desktop app (Main & Renderer processes, IPC)
– app-android/… → Android app (Kotlin + native Rust/C++ via JNI, Room/SqlCipher, Android Keystore, Google FCM/SSE)
– app-ios/… → iOS app + extensions (Swift, shared TutaSharedFramework, SqlCipher, Keychain, APNs/SSE)
- Shared logic & SDKs:
– common/api, common/native, common/… → Business logic, platform facades, IPC-schema, generated stubs
– packages/… → Independent libraries (tutanota-crypto, tuta-utils, otest, etc.)
– tuta-sdk/… → Official client SDK in Rust + Swift + Java/Kotlin wrappers
- Persistence & Security:
– Local DB: SqlCipher on mobile/desktop, IndexedDB on web
– Crypto: Argon2id, LibOQS/Kyber, AES, HMAC modules in native and WebAssembly
– Credentials: Android Keystore, iOS Keychain, Electron key store facade
- Remote services:
– Tuta Mail REST API (HTTPS)
– SSE for push notifications & sync events
– File upload/download endpoints (blob facade)

##### Key interactions
- Client UI layers call common facades → facade implementations dispatch to platform-specific transports (REST, native IPC, WebWorker)
- Crypto operations often occur in Worker threads or native modules via N-API/UNIFFI bindings
- Local storage and offline migrations managed via common/…/offline and migration scripts
- Notifications delivered via SSE client → routed through façades to UI or native OS notifications

##### Architectural patterns & principles
- Layered architecture:
– Presentation (UI)
– Application (controllers, view-models)
– Facade/Transport (common/api, common/native)
– Persistence/Crypto engines
– External services (REST/SSE)
- Code-sharing via “common” modules and generated IPC stubs to avoid duplication
- Clean separation between platform-specific entrypoints and shared business logic
- Extensive use of Web Workers/Electron Worker processes for CPU-heavy tasks
- Monorepo with package-based modularization and independent build pipelines

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layers - Presentation
    subgraph "Presentation Layer"
        direction TB
        subgraph "Web Client" 
            direction TB
            WebUI["RootView.ts"]:::frontend
            WebTop["TopLevelView.ts"]:::frontend
            WebCal["calendar-app/"]:::frontend
            WebMail["mail-app/"]:::frontend
            WebWorker["workerUtils/"]:::frontend
            WebPoly["polyfill.ts"]:::frontend
            WebDir["src/"]:::frontend
        end
        subgraph "Electron App"
            direction TB
            ElecMain["desktop.js"]:::frontend
            ElecLogic["src/common/desktop/"]:::frontend
            ElecRes["resources/desktop-icons/"]:::frontend
            ElecRender["Electron Renderer"]:::frontend
            ElecWorker["Electron Worker"]:::frontend
        end
        subgraph "Android App"
            direction TB
            AndMail["app-android/app/"]:::frontend
            AndCal["app-android/calendar/"]:::frontend
            AndShared["app-android/tutashared/"]:::frontend
        end
        subgraph "iOS App"
            direction TB
            iOSMail["app-ios/tutanota/"]:::frontend
            iOSCal["app-ios/calendar/"]:::frontend
            iOSNotifExt["app-ios/TutanotaNotificationExtension/"]:::frontend
            iOSShareExt["app-ios/TutanotaShareExtension/"]:::frontend
            iOSSharedFW["app-ios/TutanotaSharedFramework/"]:::frontend
        end
    end

    %% Business & SDK Layer
    subgraph "Business & SDK (Green)"
        direction TB
        subgraph "Shared Facades & Logic"
            direction TB
            API["src/common/api/"]:::business
            NativeF["src/common/native/"]:::business
            CoreUtil["src/common/"]:::business
        end
        subgraph "Independent Packages"
            direction TB
            CryptoTK["packages/tutanota-crypto/"]:::business
            WASMLoader["packages/tuta-wasm-loader/"]:::business
            UtilsPKG["packages/tutanota-utils/"]:::business
            ErrPKG["packages/tutanota-error/"]:::business
            TestH["packages/otest/"]:::business
            MailImp["packages/node-mimimi/"]:::business
        end
        subgraph "Tuta SDK"
            direction TB
            SDKAnd["tuta-sdk/android/sdk/"]:::business
            SDKiOS["tuta-sdk/ios/tutasdk/"]:::business
            SDKRust["tuta-sdk/rust/sdk/"]:::business
            UNIFFI["tuta-sdk/rust/uniffi-bindgen/"]:::business
        end
    end

    %% Persistence & Crypto Engines
    subgraph "Persistence & Crypto (Orange)"
        direction TB
        IndexedDB["IndexedDB"]:::storage
        SqlCipher["SqlCipher (Room)"]:::storage
        Keychain["Android Keystore / iOS Keychain"]:::storage
        CryptoEngine["Crypto Engines (WASM / Native)"]:::storage
        WASMLibs["libs/webassembly/"]:::storage
    end

    %% External Services
    subgraph "External Services (Purple)"
        direction TB
        Backend["Tuta Mail Backend\n(REST API & Blob)"]:::external
        SSE["SSE / Push Endpoints"]:::external
    end

    %% CI / Build
    subgraph "CI & Build"
        direction TB
        BuildSrc["buildSrc/"]:::infra
        CIcfg["ci/"]:::infra
        GHactions[".github/workflows/"]:::infra
    end

    %% Connections
    %% Web
    WebDir -->|uses| WebUI
    WebDir --> WebTop
    WebDir --> WebCal
    WebDir --> WebMail
    WebDir --> WebWorker
    WebDir --> WebPoly

    WebCal -->|calls facade| API
    WebMail -->|calls facade| API
    WebUI -->|calls facade| API
    WebWorker -->|crypto ops| CryptoEngine
    WebWorker -->|storage| IndexedDB

    %% Electron
    ElecRender -->|UI| ElecLogic
    ElecMain -->|IPC| ElecLogic
    ElecLogic -->|calls facade| NativeF
    ElecLogic --> CryptoEngine
    ElecLogic --> SqlCipher
    ElecRes --> ElecRender

    %% Android
    AndMail -->|UI/controllers| API
    AndCal -->|UI/controllers| API
    AndShared -->|native modules| CryptoEngine
    AndShared --> SqlCipher
    AndShared --> Keychain

    %% iOS
    iOSMail -->|UI/controllers| API
    iOSCal -->|UI/controllers| API
    iOSSharedFW --> CryptoEngine
    iOSSharedFW --> Keychain
    iOSNotifExt -->|push route| SSE
    iOSShareExt --> CoreUtil

    %% Shared business
    API -->|REST| Backend
    API -->|SSE| SSE
    NativeF -->|native transport| Backend
    CoreUtil -->|utilities| API
    CoreUtil -->|utilities| NativeF

    CryptoEngine -->|secure ops| WASMLibs
    CryptoEngine -->|argon2id, liboqs| WASMLibs

    SSE -->|notifications| ElecLogic
    SSE -->|notifications| iOSNotifExt
    SSE -->|notifications| AndMail

    %% CI
    BuildSrc --> CoreUtil
    BuildSrc --> SDKRust
    CIcfg --> BuildSrc
    GHactions --> CIcfg

    %% Click Events
    click WebDir "https://github.com/tutao/tutanota/tree/master/src/"
    click WebUI "https://github.com/tutao/tutanota/blob/master/src/RootView.ts"
    click WebTop "https://github.com/tutao/tutanota/blob/master/src/TopLevelView.ts"
    click WebCal "https://github.com/tutao/tutanota/tree/master/src/calendar-app/"
    click WebMail "https://github.com/tutao/tutanota/tree/master/src/mail-app/"
    click WebWorker "https://github.com/tutao/tutanota/tree/master/src/workerUtils/"
    click WebPoly "https://github.com/tutao/tutanota/blob/master/src/polyfill.ts"

    click ElecMain "https://github.com/tutao/tutanota/blob/master/desktop.js"
    click ElecLogic "https://github.com/tutao/tutanota/tree/master/src/common/desktop/"
    click ElecRes "https://github.com/tutao/tutanota/tree/master/resources/desktop-icons/"

    click AndMail "https://github.com/tutao/tutanota/tree/master/app-android/app/"
    click AndCal "https://github.com/tutao/tutanota/tree/master/app-android/calendar/"
    click AndShared "https://github.com/tutao/tutanota/tree/master/app-android/tutashared/"

    click iOSMail "https://github.com/tutao/tutanota/tree/master/app-ios/tutanota/"
    click iOSCal "https://github.com/tutao/tutanota/tree/master/app-ios/calendar/"
    click iOSNotifExt "https://github.com/tutao/tutanota/tree/master/app-ios/TutanotaNotificationExtension/"
    click iOSShareExt "https://github.com/tutao/tutanota/tree/master/app-ios/TutanotaShareExtension/"
    click iOSSharedFW "https://github.com/tutao/tutanota/tree/master/app-ios/TutanotaSharedFramework/"

    click API "https://github.com/tutao/tutanota/tree/master/src/common/api/"
    click NativeF "https://github.com/tutao/tutanota/tree/master/src/common/native/"
    click CoreUtil "https://github.com/tutao/tutanota/tree/master/src/common/"

    click CryptoTK "https://github.com/tutao/tutanota/tree/master/packages/tutanota-crypto/"
    click WASMLoader "https://github.com/tutao/tutanota/tree/master/packages/tuta-wasm-loader/"
    click UtilsPKG "https://github.com/tutao/tutanota/tree/master/packages/tutanota-utils/"
    click ErrPKG "https://github.com/tutao/tutanota/tree/master/packages/tutanota-error/"
    click TestH "https://github.com/tutao/tutanota/tree/master/packages/otest/"
    click MailImp "https://github.com/tutao/tutanota/tree/master/packages/node-mimimi/"

    click SDKAnd "https://github.com/tutao/tutanota/tree/master/tuta-sdk/android/sdk/"
    click SDKiOS "https://github.com/tutao/tutanota/tree/master/tuta-sdk/ios/tutasdk/"
    click SDKRust "https://github.com/tutao/tutanota/tree/master/tuta-sdk/rust/sdk/"
    click UNIFFI "https://github.com/tutao/tutanota/tree/master/tuta-sdk/rust/uniffi-bindgen/"

    click WASMLibs "https://github.com/tutao/tutanota/tree/master/libs/webassembly/"

    click BuildSrc "https://github.com/tutao/tutanota/tree/master/buildSrc/"
    click CIcfg "https://github.com/tutao/tutanota/tree/master/ci/"
    click GHactions "https://github.com/tutao/tutanota/tree/master/.github/workflows/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0066CC,color:#003366;
    classDef business fill:#DFFFE0,stroke:#33AA00,color:#336600;
    classDef storage fill:#FFE8C0,stroke:#CC6600,color:#663300;
    classDef external fill:#F0D0FF,stroke:#AA00CC,color:#660066;
    classDef infra fill:#EFEFEF,stroke:#888888,color:#444444;
```
