# nextcloud/android architecture

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

- Interactive diagram: https://gitdiagram.com/nextcloud/android
- Repository: https://github.com/nextcloud/android

## Overview

##### Project type and purpose
- It’s a monolithic Android client app for Nextcloud (mobile front‑end)
- Written in Kotlin/Java with Gradle, Dagger (DI), Room (local DB), WorkManager, ExoPlayer, AIDL (SSO), Compose, traditional Activities/Fragments

##### Main components
A. UI Layer
– Activities, Fragments, Compose screens
– ViewModels (Android Architecture Components)
B. Domain/Business Logic
– Use‑cases (e.g. GeneratePDFUseCase, FileLockingHelper)
– AsyncRunner/Task abstractions
C. Data Layer (Repository Pattern)
– Repositories (ClientRepository, OfflineOperationsRepository, AssistantRepository, etc.)
– Local DataSource: Room database (NextcloudDatabase + DAOs + Entities + Migrations)
– Remote DataSource: Nextcloud Server API (ClientFactory → HTTP client modules)
D. Background & Services
– WorkManager jobs (SyncWork, BackupWork, OfflineOperationsWorker, FileUploadWorker, etc.)
– Foreground/Bound services (PlayerService, PowerManagementService, ConnectivityServiceImpl)
– AIDL SSO service for streaming remote content
E. External/Device Integrations
– Nextcloud server (HTTPS REST APIs)
– Firebase Messaging or Huawei Push (in gplay/huawei flavors)
– Camera/File storage (document scan, media playback, downloads)
– Local notifications (NotificationManager)

##### Relationships and data flows
- User taps UI → ViewModel → Repository
- Repository decides:
– Query Room DB (DAO) → returns LiveData/Flow
– Or call HTTP client → parse JSON → write to DB
- Background sync: WorkManager schedules jobs → executes OfflineSyncWork → uses Repository → updates DB
- Push arrives → Firebase/HMS → triggers BroadcastReceiver → enqueues WorkManager task
- AIDL SSO: UI binds to InputStreamService → streams content from server
- Media playback: UI → PlayerService → ExoPlayer → streams remote URLs

##### Architectural patterns & principles
- MVVM (UI ↔ ViewModel ↔ Repository)
- Repository pattern + data sources
- Dependency Injection (Dagger modules in /di)
- Single source of truth: Room DB
- Reactive UI: LiveData/Flow
- Background processing: WorkManager
- Flavor‑based configuration: generic, gplay, huawei, debug, qa, release

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        FileDisplayActivity["FileDisplayActivity"]:::ui
        SetStatusDialogFragment["SetStatusDialogFragment"]:::ui
        AssistantScreen["AssistantScreen"]:::ui
    end

    %% ViewModels
    subgraph "ViewModels"
        direction TB
        AssistantViewModel["AssistantViewModel"]:::vm
    end

    %% Domain / Use Cases
    subgraph "Domain Layer"
        direction TB
        GeneratePDFUseCase["GeneratePDFUseCase"]:::domain
        AsyncRunner["AsyncRunner"]:::domain
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        ClientRepository["ClientRepository"]:::data
        NextcloudDatabase["NextcloudDatabase"]:::data
        FileDao["FileDao"]:::data
        FileEntity["FileEntity"]:::data
        ClientFactoryImpl["ClientFactoryImpl"]:::data
    end

    %% Background & Services
    subgraph "Background & Services"
        direction TB
        FileUploadWorker["FileUploadWorker"]:::background
        OfflineSyncWork["OfflineSyncWork"]:::background
        PlayerService["PlayerService"]:::background
        ConnectivityServiceImpl["ConnectivityServiceImpl"]:::background
        IInputStreamService["IInputStreamService"]:::background
    end

    %% External / Device Integrations
    subgraph "External & Device"
        direction TB
        NextcloudServer["Nextcloud Server (HTTPS)"]:::external
        NCFirebaseMessagingService["NCFirebaseMessagingService"]:::external
        PushUtils["PushUtils"]:::external
        DocumentScanActivity["DocumentScanActivity"]:::external
        AppNotificationManagerImpl["AppNotificationManagerImpl"]:::external
    end

    %% Dependency Injection
    subgraph "DI Modules"
        direction TB
        AppModule["AppModule"]:::services
        VariantComponentsModule["VariantComponentsModule"]:::services
    end

    %% Relationships
    FileDisplayActivity -->|"binds to"| AssistantViewModel
    SetStatusDialogFragment -->|"binds to"| AssistantViewModel
    AssistantScreen -->|"uses"| AssistantViewModel

    AssistantViewModel -->|"calls"| GeneratePDFUseCase
    AssistantViewModel -->|"calls"| ClientRepository

    GeneratePDFUseCase -->|"runs via"| AsyncRunner

    ClientRepository -->|"reads/writes"| NextcloudDatabase
    NextcloudDatabase -->|"provides DAO"| FileDao
    FileDao -->|"manages"| FileEntity
    ClientRepository -->|"calls"| ClientFactoryImpl
    ClientFactoryImpl -->|"HTTP/HTTPS"| NextcloudServer

    FileUploadWorker -->|"uses"| ClientRepository
    OfflineSyncWork -->|"uses"| ClientRepository
    NCFirebaseMessagingService -->|"enqueues"| OfflineSyncWork
    PushUtils -->|"enqueues"| OfflineSyncWork
    DocumentScanActivity -->|"invokes"| GeneratePDFUseCase
    FileUploadWorker -->|"notifies via"| AppNotificationManagerImpl
    OfflineSyncWork -->|"notifies via"| AppNotificationManagerImpl

    FileDisplayActivity -->|"bind AIDL"| IInputStreamService
    IInputStreamService -->|"streams from"| NextcloudServer

    PlayerService -->|"streams via ExoPlayer"| NextcloudServer
    ConnectivityServiceImpl -->|"monitors"| NextcloudServer

    AppModule -->|"provides"| ClientRepository
    AppModule -->|"provides"| AssistantViewModel
    VariantComponentsModule -->|"overrides deps for flavor"| AppModule

    %% Click Events
    click FileDisplayActivity "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/android/files/FileDisplayActivity.kt"
    click SetStatusDialogFragment "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/android/ui/SetStatusDialogFragment.kt"
    click AssistantScreen "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/assistant/AsssistantScreen.kt"
    click AssistantViewModel "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/assistant/AssistantViewModel.kt"
    click GeneratePDFUseCase "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/documentscan/GeneratePDFUseCase.kt"
    click AsyncRunner "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/core/AsyncRunner.kt"
    click ClientRepository "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/repository/ClientRepository.kt"
    click NextcloudDatabase "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/database/NextcloudDatabase.kt"
    click FileDao "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/database/dao/FileDao.kt"
    click FileEntity "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/database/entity/FileEntity.kt"
    click ClientFactoryImpl "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/network/ClientFactoryImpl.java"
    click FileUploadWorker "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/jobs/upload/FileUploadWorker.kt"
    click OfflineSyncWork "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/jobs/OfflineSyncWork.kt"
    click PlayerService "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/media/PlayerService.kt"
    click ConnectivityServiceImpl "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/network/ConnectivityServiceImpl.java"
    click IInputStreamService "https://github.com/nextcloud/android/blob/master/app/src/main/aidl/com/nextcloud/android/sso/aidl/IInputStreamService.aidl"
    click NCFirebaseMessagingService "https://github.com/nextcloud/android/blob/master/app/src/gplay/java/com/owncloud/android/services/firebase/NCFirebaseMessagingService.java"
    click PushUtils "https://github.com/nextcloud/android/blob/master/app/src/huawei/java/com/owncloud/android/utils/PushUtils.java"
    click DocumentScanActivity "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/documentscan/DocumentScanActivity.kt"
    click AppNotificationManagerImpl "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/notifications/AppNotificationManagerImpl.kt"
    click AppModule "https://github.com/nextcloud/android/blob/master/app/src/main/java/com/nextcloud/client/di/AppModule.java"
    click VariantComponentsModule "https://github.com/nextcloud/android/blob/master/app/src/gplay/java/com/nextcloud/client/di/VariantComponentsModule.java"

    %% Styles
    classDef ui fill:#f9f,stroke:#333,stroke-width:1px
    classDef vm fill:#ff9,stroke:#333,stroke-width:1px
    classDef domain fill:#9f9,stroke:#333,stroke-width:1px
    classDef data fill:#9ff,stroke:#333,stroke-width:1px
    classDef background fill:#fc9,stroke:#333,stroke-width:1px
    classDef external fill:#ccf,stroke:#333,stroke-width:1px
    classDef services fill:#cfc,stroke:#333,stroke-width:1px
```
