# oxen-io/session-android architecture

> Architecture diagram of the GitHub repository oxen-io/session-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/oxen-io/session-android
- Repository: https://github.com/oxen-io/session-android

## Overview

##### Project Layers and Components
- User Interface / Presentation Layer – Represented by the “app” module. This includes Android activities, fragments, custom views, and UI components (e.g., in app/src/main/java/org/thoughtcrime/securesms/ui/*, components, home, conversation, preferences, etc.).
- Business Logic / Application Layer – This layer incorporates messaging and conversation handling, onboarding, preferences, and other core application logic. Some parts inside “app” are clearly used for handling events, notifications, and dependency injection (look at the “dependencies” folder inside app).
- Core Communication & Cryptography – Several libraries (libsession, libsession-util, libsignal, liblazysodium) contain the backbone for secure messaging, cryptographic operations, key management, and message processing. They incorporate cryptographic primitives, protocols, background jobs, network polling, and file/attachment handling.
- Networking & Service Integration – The app indirectly interfaces with Oxen Service Nodes that provide offline message storage and onion routing. Classes in libraries (for example, in libsession and libsignal) that deal with “messaging”, “pollers”, “network” and “jobs” will be responsible for connectivity, push notifications, and processing incoming/outgoing messages.
- Shared and Common Resources – Modules like “common” and “content-descriptions” also exist to provide shared resources, translations, and possibly reusable code across different parts of the application.
- Build and Configuration – Gradle build files (including build.gradle at various levels and buildSrc) hint that the application is built with a modular, multi-project setup. This should be shown as a separate side component in your architecture for compilation, dependency management, and testing.

##### Interactions and Data Flow
- The UI layer sends user interactions (like starting a new conversation or sending a message) to controllers or view models in the business layer.
- The business logic in turn calls into the secure messaging libraries (libsession, libsession-util, libsignal) to process messages, encrypt/decrypt data, manage attachments, and interact with the persistent storage (databases and content providers in app and libraries).
- The networking components (embedded in the lower-level libraries) perform background polling, request management, and interact with external Oxen Service Nodes – these should be represented as external system components.
- There are also testing modules (androidTest, test, sharedTest) that verify behavior at every layer.

##### Architectural Patterns and Design Principles
- Modularization: The project is clearly broken into multiple Gradle modules (app, common, content-descriptions, libsession, libsignal, etc.) which encapsulates responsibilities.
- Dependency injection: Many “Module” classes in the app (e.g., AppModule.kt, CallModule.kt) suggest DI to decouple modules – represent this with annotations or lines indicating dependency injection.
- Robust use of external libraries for cryptography and media handling.

##### Technologies, Frameworks, and External Systems
- Android SDK components for UI, activities, fragments, and testing (androidTest, test).
- Gradle as the build system, with custom buildSrc plugins.
- Cryptographic libraries: liblazysodium and libsignal.
- Networking protocols for push notifications, WebRTC, and request controllers (websocket, polling, etc.).
- Oxen Service Nodes as external decentralized servers that provide message storage and onion routing services.

##### Putting It All Together
– At the top, the “User Interface” layer (activities, fragments, views).
– In the middle, the “Business/Application Logic” layer (controllers, view models, dependency modules).
– Below, the “Core Messaging and Cryptography” modules (libsession, libsignal, liblazysodium) interfacing with a “Network/Service Node” external system.
– To one side, show “Shared Modules & Build Infrastructure” that connect all modules.
- Then, for a more detailed view, break down the UI layer into activities that lead into feature-specific modules (e.g., conversation handling, onboarding, media handling) and indicate how they call into the shared libraries.
- Testing modules (unit tests, instrumentation tests) off to the side, indicating that every layer is subject to rigorous testing.

- The separation between the front-end Android UI and the underlying secure messaging libraries.
- The interactions between components (data flows, network requests, dependency injection).
- Important architectural patterns like modularization and layered design.
- All the relevant technologies/frameworks (Android SDK, Gradle, external cryptographic libraries, and connections to Oxen Service Nodes).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface / Presentation Layer
    subgraph "User Interface / Presentation Layer"
        UI["Android UI (Activities, Fragments, Views)"]:::ui
    end

    %% Business Logic / Application Layer
    subgraph "Business Logic / Application Layer"
        BL["Business Logic (ViewModels, Controllers, DI Modules)"]:::business
    end

    %% Core Communication & Cryptography
    subgraph "Core Communication & Cryptography"
        subgraph "Secure Messaging Libraries"
            C1["libsession"]:::crypto
            C2["libsignal"]:::crypto
            C3["liblazysodium"]:::crypto
            C4["libsession-util"]:::crypto
        end
        subgraph "Network Utils"
            N1["Network Utils (libsession-util/network)"]:::networking
        end
    end

    %% Networking & Service Integration
    subgraph "Networking & Service Integration"
        NS["Oxen Service Nodes"]:::networking
    end

    %% Shared & Common Resources
    subgraph "Shared & Common Resources"
        Shared1["common"]:::shared
        Shared2["content-descriptions"]:::shared
    end

    %% Build & Configuration
    subgraph "Build & Configuration"
        Build1["build.gradle"]:::build
        Build2["gradle/"]:::build
        Build3["buildSrc"]:::build
        Build4["gradlew"]:::build
        Build5["gradlew.bat"]:::build
    end

    %% Connections between layers
    UI -->|"userActions"| BL
    BL -->|"businessCalls"| C1
    BL -->|"businessCalls"| C2
    BL -->|"businessCalls"| C3
    BL -->|"businessCalls"| C4
    C4 -->|"networkRequest"| N1
    N1 -->|"sendReceive"| NS
    NS -->|"response"| N1
    N1 -->|"update"| C4

    %% Shared Resource interactions
    UI -->|"accesses"| Shared1
    UI -->|"accesses"| Shared2
    BL -->|"uses"| Shared1
    BL -->|"uses"| Shared2

    %% Build & Configuration supports the main modules
    Build1 ---|"builds"| UI
    Build2 ---|"builds"| BL
    Build3 ---|"builds"| C1
    Build3 ---|"builds"| C2
    Build3 ---|"builds"| C3
    Build3 ---|"builds"| C4
    Build3 ---|"builds"| Shared1
    Build3 ---|"builds"| Shared2

    %% Click Events
    click UI "https://github.com/oxen-io/session-android/tree/master/app/src/main/java/org/thoughtcrime/securesms/ui"
    click BL "https://github.com/oxen-io/session-android/tree/master/app/src/main/java/org/thoughtcrime/securesms/dependencies"
    click C1 "https://github.com/oxen-io/session-android/tree/master/libsession"
    click C2 "https://github.com/oxen-io/session-android/tree/master/libsignal"
    click C3 "https://github.com/oxen-io/session-android/tree/master/liblazysodium"
    click C4 "https://github.com/oxen-io/session-android/tree/master/libsession-util"
    click N1 "https://github.com/oxen-io/session-android/tree/master/libsession-util/src/main/java/network"
    click Shared1 "https://github.com/oxen-io/session-android/tree/master/common"
    click Shared2 "https://github.com/oxen-io/session-android/tree/master/content-descriptions"
    click Build1 "https://github.com/oxen-io/session-android/blob/master/build.gradle"
    click Build2 "https://github.com/oxen-io/session-android/tree/master/gradle/"
    click Build3 "https://github.com/oxen-io/session-android/tree/master/buildSrc"
    click Build4 "https://github.com/oxen-io/session-android/tree/master/gradlew"
    click Build5 "https://github.com/oxen-io/session-android/blob/master/gradlew.bat"

    %% Style classes
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef business fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef crypto fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef networking fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef shared fill:#d1ecf1,stroke:#333,stroke-width:2px;
    classDef build fill:#f5f5f5,stroke:#333,stroke-width:2px;
```
