# mattermost/mattermost-mobile architecture

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

- Interactive diagram: https://gitdiagram.com/mattermost/mattermost-mobile
- Repository: https://github.com/mattermost/mattermost-mobile

## Overview

##### Project type and purpose
- This is the Mattermost Mobile v2 application: a cross-platform React Native client for Mattermost chat servers.
- It bundles three “front-ends” in one repo:
- A JavaScript/TypeScript layer under `app/` and `share_extension/` powered by React Native.
- Native Android code under `android/` (Gradle, Kotlin/Java helpers, WatermelonDB schema, push handlers, call integrations).
- Native iOS code under `ios/` (Swift/Objective-C wrappers, push extensions, WatermelonDB integration).
- It communicates with external services: a Mattermost Server over REST and WebSocket, a Push Notification Proxy (for APNS/FCM), and a VoIP/calls subsystem via WebRTC or Voximplant.

##### File structure
- Top-level directories:
- `app/` – JS business logic: actions (remote, local, websocket), client wrappers, components, screens, database operator/manager, state stores, hooks, utils, queries, schema, migrations.
- `android/` & `ios/` – native platform shells, native modules, build configurations, asset catalogs, database bridges, push handlers, call services.
- `libraries/` – custom React Native native modules (`@mattermost/hardware-keyboard`, `rnshare`, `rnutils`).
- `share_extension/` – a small React Native bundle for iOS share extension.
- CI/CD: `.github/workflows`, `fastlane/`, `scripts/`, `detox/` for e2e tests.
- Architectural patterns: Flux/Redux-style actions → state stores → React views; persistent data via WatermelonDB (SQLite) with separate “app” and “server” schema layers; a clear split between UI (components/screens), business logic (actions/managers), data layer (database/operator), network layer (client/rest & client/websocket).

##### Key insights from README
- The mobile app requires its own Push Proxy for notifications.
- Communicates with server API v4 (REST + WebSocket).
- Supports monthly releases and community contributions, but no embedded server—pure client.

##### Components
a. **JS/UI Layer**
- React Native bundle (`app/` + `share_extension/`)
- Screens & UI components (screens/, components/)
- Hooks & context providers
b. **State & Data Layer**
- Actions (remote, local, websocket) → dispatch to stores (`app/store/…`)
- Stores / Ephemeral state vs. persisted state
- Database manager & operators (WatermelonDB / SQLite under `app/database/`)
- Query layer (`app/queries/`)
c. **Network Layer**
- REST client (`app/client/rest/`)
- WebSocket client (`app/client/websocket/`)
- Push Notification Bridge (native modules + Push Proxy)
- Calls subsystem (native integration + `app/products/calls/`)
d. **Native Platforms**
- Android shell (Gradle projects, custom Java/Kotlin helpers, AndroidManifest, assets)
- iOS shell (Xcode project, Swift/Obj-C code, Share extension)
- Native modules (`libraries/@mattermost/*`)
e. **External Services**
- Mattermost Server (REST API & WebSocket)
- Mattermost Push Proxy (APNS / FCM)
- Third-party call servers (e.g., Voximplant)
- CDNs / asset hosting (for fonts, emojis, i18n JSON)

##### Relationships and data flows
- UI triggers user actions → dispatch to Action layer →
→ Local actions mutate DB via Operators & Managers → Store updates → UI re-renders.
→ Remote actions call REST/WebSocket client → Server → response persisted to DB → Stores updated → UI.
- WebSocket pushes from server → WebSocket client → dispatch as WebSocket Actions → DB & Stores → UI.
- Push Proxy → platform push SDK → native push handler → JS event → navigate or update Stores.
- Calls subsystem: JS triggers call actions → native module opens WebRTC channel → media flow outside JS.
- Share extension: isolated RN bundle with its own state, network calls, then hands off to main app via deep link or shared storage.

##### Architectural patterns & design principles
- Flux/Redux pattern for one-way data flow.
- Separation of concerns: UI (components/screens), business logic (actions/managers), persistence (database), network (client).
- Native-JS bridging: React Native modules isolate platform specifics.
- Modular directory structure by feature (e.g., `app/products/calls/`, `app/screens/channel/`, `libraries/` modules).
- CI/CD pipelines automate builds, tests, code analysis (GitHub Actions + Fastlane + Detox/E2E).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% JavaScript UI Layer
    subgraph "JavaScript Layer"
        direction TB
        RNBundle["React Native Bundle"]:::jsLayer
        Screens["Screens"]:::jsLayer
        Components["UI Components"]:::jsLayer
        Hooks["Hooks & Context Providers"]:::jsLayer
    end

    %% Share Extension
    ShareExt["Share Extension Bundle"]:::jsLayer

    %% State & Data Layer
    subgraph "State & Data Layer"
        direction TB
        Actions["Actions (remote/local/websocket)"]:::dataLayer
        Stores["Stores & Ephemeral State"]:::dataLayer
        DBMgr["Database Manager & Operators"]:::dataLayer
        Schema["Schema & Migrations"]:::dataLayer
        Queries["Query Layer"]:::dataLayer
    end

    %% Network Layer
    subgraph "Network Layer"
        direction TB
        REST["REST Client"]:::networkLayer
        WebSocket["WebSocket Client"]:::networkLayer
        PushBridge["Push Notification Bridge"]:::networkLayer
        Calls["Calls Subsystem"]:::networkLayer
    end

    %% Native Platform Layer
    subgraph "Native Platform Layer"
        direction TB
        subgraph Android
            AndroidShell["Android Native Shell & Build Config"]:::nativeLayer
            PushAndroid["Push Notification Helpers"]:::nativeLayer
        end
        subgraph iOS
            IOShell["iOS Native Shell & Xcode Project"]:::nativeLayer
            PushiOS["iOS Push Extension"]:::nativeLayer
        end
        subgraph Libraries
            HWKeyboard["@mattermost/hardware-keyboard"]:::nativeLayer
            RNShare["@mattermost/rnshare"]:::nativeLayer
            RNUtils["@mattermost/rnutils"]:::nativeLayer
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        MMServer["Mattermost Server"]:::external
        PushProxy["Mattermost Push Proxy"]:::external
        CallServer["Third-Party Call Server"]:::external
        CDN["CDN / Asset Hosting"]:::external
    end

    %% CI/CD
    subgraph "CI/CD"
        direction TB
        Workflows["GitHub Actions Workflows"]:::cicd
        Fastlane["Fastlane"]:::cicd
        Scripts["Build & Test Scripts"]:::cicd
        Detox["Detox E2E Tests"]:::cicd
    end

    %% Flows
    RNBundle -->|renders| Screens
    RNBundle -->|uses| Components
    RNBundle -->|provides| Hooks
    Screens -->|dispatch| Actions
    Components -->|dispatch| Actions

    Actions -->|update| Stores
    Actions -->|invoke| DBMgr
    DBMgr -->|persist| Schema
    Stores -->|queried by| Queries
    Stores -->|feed| RNBundle

    Actions -->|calls| REST
    Actions -->|calls| WebSocket
    WebSocket -->|push| Actions

    REST -->|HTTP/REST| MMServer
    WebSocket -->|WebSocket| MMServer
    PushProxy -->|APNS/FCM| PushBridge
    PushBridge -->|native event| RNBundle

    RNBundle -->|trigger call| Calls
    Calls -->|media via WebRTC| CallServer

    ShareExt -->|shares code| RNBundle
    ShareExt -->|uses| Actions
    ShareExt -->|calls| REST
    ShareExt -->|deep link| RNBundle

    AndroidShell -->|bundles| RNBundle
    IOShell -->|bundles| RNBundle

    PushAndroid -->|bridge| PushBridge
    PushiOS -->|bridge| PushBridge

    HWKeyboard -->|native module| RNBundle
    RNShare -->|native module| RNBundle
    RNUtils -->|native module| RNBundle

    Workflows -->|trigger| Fastlane
    Fastlane -->|build/test| Scripts
    Scripts -->|run| Detox

    CDN -->|hosts| RNBundle

    %% Click Events
    click RNBundle "https://github.com/mattermost/mattermost-mobile/tree/main/app/"
    click ShareExt "https://github.com/mattermost/mattermost-mobile/tree/main/share_extension/"
    click Components "https://github.com/mattermost/mattermost-mobile/tree/main/app/components/"
    click Screens "https://github.com/mattermost/mattermost-mobile/tree/main/app/screens/"
    click Hooks "https://github.com/mattermost/mattermost-mobile/tree/main/app/hooks/"
    click Actions "https://github.com/mattermost/mattermost-mobile/tree/main/app/actions/remote/"
    click Actions "https://github.com/mattermost/mattermost-mobile/tree/main/app/actions/local/"
    click Actions "https://github.com/mattermost/mattermost-mobile/tree/main/app/actions/websocket/"
    click Stores "https://github.com/mattermost/mattermost-mobile/tree/main/app/store/"
    click DBMgr "https://github.com/mattermost/mattermost-mobile/tree/main/app/database/manager/"
    click Schema "https://github.com/mattermost/mattermost-mobile/tree/main/app/database/schema/"
    click Schema "https://github.com/mattermost/mattermost-mobile/tree/main/app/database/migration/"
    click Queries "https://github.com/mattermost/mattermost-mobile/tree/main/app/queries/"
    click REST "https://github.com/mattermost/mattermost-mobile/tree/main/app/client/rest/"
    click WebSocket "https://github.com/mattermost/mattermost-mobile/tree/main/app/client/websocket/"
    click PushAndroid "https://github.com/mattermost/mattermost-mobile/tree/main/android/app/src/main/java/com/mattermost/helpers/push_notification/"
    click PushiOS "https://github.com/mattermost/mattermost-mobile/tree/main/ios/Gekidou/Sources/Gekidou/PushNotification/"
    click PushiOS "https://github.com/mattermost/mattermost-mobile/tree/main/ios/NotificationService/"
    click Calls "https://github.com/mattermost/mattermost-mobile/tree/main/app/products/calls/"
    click AndroidShell "https://github.com/mattermost/mattermost-mobile/tree/main/android/"
    click IOShell "https://github.com/mattermost/mattermost-mobile/blob/main/ios/Mattermost.xcodeproj"
    click IOShell "https://github.com/mattermost/mattermost-mobile/blob/main/ios/Mattermost/AppDelegate.*"
    click HWKeyboard "https://github.com/mattermost/mattermost-mobile/tree/main/libraries/@mattermost/hardware-keyboard/"
    click RNShare "https://github.com/mattermost/mattermost-mobile/tree/main/libraries/@mattermost/rnshare/"
    click RNUtils "https://github.com/mattermost/mattermost-mobile/tree/main/libraries/@mattermost/rnutils/"
    click Workflows "https://github.com/mattermost/mattermost-mobile/tree/main/.github/workflows/"
    click Fastlane "https://github.com/mattermost/mattermost-mobile/tree/main/fastlane/"
    click Scripts "https://github.com/mattermost/mattermost-mobile/tree/main/scripts/"
    click Detox "https://github.com/mattermost/mattermost-mobile/tree/main/detox/"

    %% Styles
    classDef jsLayer fill:#D6EAF8,stroke:#3498DB,color:#1B4F72
    classDef dataLayer fill:#FCF3CF,stroke:#F1C40F,color:#7D6608
    classDef networkLayer fill:#E8DAEF,stroke:#9B59B6,color:#4A235A
    classDef nativeLayer fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef external fill:#FADBD8,stroke:#E74C3C,color:#78281F
    classDef cicd fill:#F2F3F4,stroke:#7B7D7D,color:#2C3E50
```
