# linagora/tmail-flutter architecture

> Architecture diagram of the GitHub repository linagora/tmail-flutter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/linagora/tmail-flutter
- Repository: https://github.com/linagora/tmail-flutter

## Overview

Twake Mail is a cross-platform JMAP email client. The README describes reading and managing mail, sending, searching, and mobile/web clients, but the supplied tree omits the main Flutter application, so its UI and most mail-operation wiring cannot be mapped reliably. The visible iOS code supports a notification workflow: receive a push, load shared credentials, fetch email changes from JMAP, filter them, and present a notification. The graph also shows native app entry points and the web smart-banner/deep-link behavior; unsampled feature details are omitted.

Main entry points: [`ios/TwakeMailNSE/NotificationService.swift`](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeMailNSE/NotificationService.swift) (Notification service), [`ios/TwakeCore/Jmap/JmapClient.swift`](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeCore/Jmap/JmapClient.swift) (JMAP client), [`ios/TwakeMailNSE/Keychain/KeychainController.swift`](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeMailNSE/Keychain/KeychainController.swift) (Shared sessions), [`ios/TwakeCore/Network/AlamofireService.swift`](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeCore/Network/AlamofireService.swift) (HTTP service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_native["Native clients"]
  node_android["Android host<br/>[MainActivity.kt]"]
  node_iosapp["iOS app<br/>[AppDelegate.swift]"]
  node_share["Share extension"]
end

subgraph group_push["Push notifications"]
  node_nse["Notification service"]
  node_keychain[("Shared sessions")]
  node_session["Session model"]
  node_payload["Push parser"]
  node_sentry["NSE diagnostics"]
end

subgraph group_jmap["JMAP networking"]
  node_jmap["JMAP client<br/>[JmapClient.swift]"]
  node_generator["Request generator"]
  node_network["HTTP service"]
  node_auth["Auth interceptor"]
  node_refresh["Token refresh"]
  node_email["Email model<br/>[Email.swift]"]
end

subgraph group_web["Web entry"]
  node_webworker["Web banner<br/>[worker_service.js]"]
end

node_user(("Mail user"))
node_stores["App stores"]
node_backend["JMAP server"]
node_tokenendpoint["OIDC token endpoint"]

node_user -->|"uses"| node_android
node_user -->|"uses"| node_iosapp
node_user -->|"shares content"| node_share
node_user -->|"opens webmail"| node_webworker
node_webworker -.->|"opens deep link"| node_iosapp
node_webworker -.->|"fallback redirects"| node_stores
node_nse -->|"loads sessions"| node_keychain
node_keychain -->|"decodes"| node_session
node_nse -->|"parses push"| node_payload
node_nse -->|"reports events"| node_sentry
node_sentry -->|"loads config"| node_keychain
node_nse -->|"fetches changes"| node_jmap
node_nse -->|"updates delivery state"| node_keychain
node_jmap -->|"builds request"| node_generator
node_jmap -->|"configures authentication"| node_auth
node_jmap -->|"posts request"| node_network
node_network -->|"sends JMAP"| node_backend
node_network -->|"applies interceptor"| node_auth
node_jmap -->|"parses results"| node_email
node_auth -.->|"refreshes credentials"| node_refresh
node_refresh -->|"requests token"| node_tokenendpoint

click node_android "https://github.com/linagora/tmail-flutter/blob/master/android/app/src/main/kotlin/com/linagora/android/tmail/MainActivity.kt"
click node_iosapp "https://github.com/linagora/tmail-flutter/blob/master/ios/Runner/AppDelegate.swift"
click node_share "https://github.com/linagora/tmail-flutter/blob/master/ios/TeamMailShareExtension/ShareViewController.swift"
click node_webworker "https://github.com/linagora/tmail-flutter/blob/master/web/worker_service/worker_service.js"
click node_nse "https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeMailNSE/NotificationService.swift"
click node_keychain "https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeMailNSE/Keychain/KeychainController.swift"
click node_session "https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeMailNSE/Model/KeychainSharingSession.swift"
click node_payload "https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeMailNSE/Utils/PayloadParser.swift"
click node_sentry "https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeMailNSE/Utils/SentryManager.swift"
click node_jmap "https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeCore/Jmap/JmapClient.swift"
click node_generator "https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeCore/Jmap/Utils/JmapRequestGenerator.swift"
click node_network "https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeCore/Network/AlamofireService.swift"
click node_auth "https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeCore/Network/Interceptor/AuthenticationInterceptor.swift"
click node_refresh "https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeCore/Network/TokenRefreshManager.swift"
click node_email "https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeCore/Jmap/Model/Email/Email.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_android,node_iosapp,node_share,node_user toneBlue
class node_nse,node_keychain,node_session,node_payload,node_sentry toneAmber
class node_jmap,node_generator,node_network,node_auth,node_refresh,node_email,node_backend toneMint
class node_webworker toneRose
class node_stores,node_tokenendpoint toneIndigo
```

## Components

### Native clients

- [Android host](https://github.com/linagora/tmail-flutter/blob/master/android/app/src/main/kotlin/com/linagora/android/tmail/MainActivity.kt): `android/app/src/main/kotlin/com/linagora/android/tmail/MainActivity.kt`
- [iOS app](https://github.com/linagora/tmail-flutter/blob/master/ios/Runner/AppDelegate.swift): `ios/Runner/AppDelegate.swift`
- [Share extension](https://github.com/linagora/tmail-flutter/blob/master/ios/TeamMailShareExtension/ShareViewController.swift): `ios/TeamMailShareExtension/ShareViewController.swift`

### Push notifications

- [Notification service](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeMailNSE/NotificationService.swift): `ios/TwakeMailNSE/NotificationService.swift`
- [Shared sessions](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeMailNSE/Keychain/KeychainController.swift): `ios/TwakeMailNSE/Keychain/KeychainController.swift`
- [Session model](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeMailNSE/Model/KeychainSharingSession.swift): `ios/TwakeMailNSE/Model/KeychainSharingSession.swift`
- [Push parser](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeMailNSE/Utils/PayloadParser.swift): `ios/TwakeMailNSE/Utils/PayloadParser.swift`
- [NSE diagnostics](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeMailNSE/Utils/SentryManager.swift): `ios/TwakeMailNSE/Utils/SentryManager.swift`

### JMAP networking

- [JMAP client](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeCore/Jmap/JmapClient.swift): `ios/TwakeCore/Jmap/JmapClient.swift`
- [Request generator](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeCore/Jmap/Utils/JmapRequestGenerator.swift): `ios/TwakeCore/Jmap/Utils/JmapRequestGenerator.swift`
- [HTTP service](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeCore/Network/AlamofireService.swift): `ios/TwakeCore/Network/AlamofireService.swift`
- [Auth interceptor](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeCore/Network/Interceptor/AuthenticationInterceptor.swift): `ios/TwakeCore/Network/Interceptor/AuthenticationInterceptor.swift`
- [Token refresh](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeCore/Network/TokenRefreshManager.swift): `ios/TwakeCore/Network/TokenRefreshManager.swift`
- [Email model](https://github.com/linagora/tmail-flutter/blob/master/ios/TwakeCore/Jmap/Model/Email/Email.swift): `ios/TwakeCore/Jmap/Model/Email/Email.swift`

### Web entry

- [Web banner](https://github.com/linagora/tmail-flutter/blob/master/web/worker_service/worker_service.js): `web/worker_service/worker_service.js`

### Other components

- **Mail user**
- **App stores**
- **JMAP server**
- **OIDC token endpoint**

## Connections

- Mail user → Android host: uses
- Mail user → iOS app: uses
- Mail user → Share extension: shares content
- Mail user → Web banner: opens webmail
- Web banner → iOS app: opens deep link
- Web banner → App stores: fallback redirects
- Notification service → Shared sessions: loads sessions
- Shared sessions → Session model: decodes
- Notification service → Push parser: parses push
- Notification service → NSE diagnostics: reports events
- NSE diagnostics → Shared sessions: loads config
- Notification service → JMAP client: fetches changes
- Notification service → Shared sessions: updates delivery state
- JMAP client → Request generator: builds request
- JMAP client → Auth interceptor: configures authentication
- JMAP client → HTTP service: posts request
- HTTP service → JMAP server: sends JMAP
- HTTP service → Auth interceptor: applies interceptor
- JMAP client → Email model: parses results
- Auth interceptor → Token refresh: refreshes credentials
- Token refresh → OIDC token endpoint: requests token
