# blockstream/green_android architecture

> Architecture diagram of the GitHub repository blockstream/green_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/blockstream/green_android
- Repository: https://github.com/blockstream/green_android

## Overview

##### Overall Structure and Major Layers
- Client Layer: Represent the mobile client applications. For Android, you have several UI components (modules like “compose”, “green”, “ui-common”) developed with Jetpack Compose and traditional Android components. The iOS client can be represented as a parallel entity (in the iosApp folder).
- Core Business Logic: This comes from the “common” module (containing commonMain, androidMain, iosMain, jvmMain, etc.) and the gdk library (in the “gdk” folder). These layers implement cross-platform wallet functionality, core Bitcoin logic, and data models.
- Platform/Integration Services: Include modules for integration with Google Mobile Services (GMS), push notifications (Firebase in “gms” and “base-gms”), and even non-GMS variants (“no-gms”). These modules manage external integrations, notifications, and platform-specific services.
- Hardware Wallet Integration: The “hardware” module handles interactions with external hardware wallets (e.g. Ledger, Trezor). It provides the communications layer to interact with hardware devices.
- Dependency Injection and Shared Utilities: Note the use of DI frameworks (via Koin in several submodules across common, androidMain, iosMain, etc.) and shared utilities such as logging, extensions, and data converters.

##### Depicting Relationships and Data Flow
- User Interface (UI): Elements in the UI modules (compose, ui-common, green) interact with ViewModels (found in common models, such as “MainViewModel”, “LoginViewModel”, etc.) following an MVVM pattern.
- Business/Wallet Logic: The ViewModels call into the shared business logic provided by the common module and gdk library. This layer handles transactions, network state, and Bitcoin-specific data.
- Data Persistence: Database directories in the “common” & “green” modules (with SQL migrations, adapters, and repositories) indicate local storage for wallet data and events.
- Hardware Communication: The hardware module sits in parallel, providing an interface for sending commands to physical devices. This component interfaces ‘downstream’ to actual hardware protocols and external libraries.

##### Important Architectural Patterns and Concepts
- MVVM – There is extensive use of ViewModels, particularly in modules like “common/models” and “compose/screens”. Indicate that UI components bind to view models which then delegate to core business logic.
- External Dependencies – Integration with external services (Google/Firebase, push notifications, possibly even external API calls within gdk) should be represented as “external services” that interface with the wallet application.

##### Elements
- Clear labels for each module/component.
- Optional: A “container” for external entities like "External Bitcoin Network" or "Push Notification Service" to show interactions.
- Integration points such as database layers (local wallet and events databases) and API integration points (Firebase, analytics).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External actor
    User["User"]:::external

    %% Client Layer
    subgraph "Client Layer"
        composeUI["Compose UI Module - Jetpack Compose based UI"]:::uiStyle
        greenUI["Green Wallet App - Traditional Android UI"]:::uiStyle
        iosClient["iOS Client Application"]:::uiStyle
    end

    %% Core Business Logic
    subgraph "Core Business Logic"
        commonLogic["Common Module - Cross-platform business logic & shared models"]:::businessStyle
        gdkEngine["GDK Wallet Engine - Core wallet engine"]:::businessStyle
    end

    %% Platform/Integration Services
    subgraph "Platform/Integration Services"
        baseGMS["Base GMS Integration - Core services"]:::integrationStyle
        gmsServices["GMS Services - Firebase/Play Services integration"]:::integrationStyle
        noGms["No GMS Module - Non-GMS alternatives"]:::integrationStyle
    end

    %% Hardware Wallet Integration
    subgraph "Hardware Wallet Integration"
        hardwareIntegration["Hardware Wallet Integration - Ledger/Trezor communication"]:::hardwareStyle
    end

    %% Dependency Injection and Shared Utilities
    subgraph "Dependency Injection"
        diCommon["Common DI (Koin)"]:::diStyle
        diGreen["Green DI (Koin)"]:::diStyle
        diJade["Jade DI (Koin)"]:::diStyle
    end

    %% User interactions with Client Layer
    User -->|"interacts"| composeUI
    User -->|"interacts"| greenUI
    User -->|"interacts"| iosClient

    %% Client Layer -> Core Business Logic
    composeUI -->|"bindsTo"| commonLogic
    greenUI -->|"bindsTo"| commonLogic
    iosClient -->|"bindsTo"| commonLogic

    %% Core Business Logic internal flow
    commonLogic -->|"delegatesTo"| gdkEngine

    %% Core Business Logic -> Integration Services
    commonLogic -->|"calls"| baseGMS
    commonLogic -->|"calls"| gmsServices
    commonLogic -->|"calls"| noGms

    %% Core Business Logic -> Hardware Integration (for device pairing etc.)
    gdkEngine -->|"utilizes"| hardwareIntegration

    %% Dependency Injection wiring
    diCommon -->|"injectsInto"| commonLogic
    diCommon -->|"injectsInto"| gdkEngine
    diGreen -->|"injectsInto"| greenUI
    diJade -->|"injectsInto"| commonLogic

    %% Styles
    classDef uiStyle fill:#fceabb,stroke:#e9a628,stroke-width:2px;
    classDef businessStyle fill:#bbf7d0,stroke:#0f5132,stroke-width:2px;
    classDef integrationStyle fill:#d7dbe0,stroke:#6c757d,stroke-width:2px;
    classDef hardwareStyle fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef diStyle fill:#d1d5db,stroke:#6b7280,stroke-width:2px;
    classDef external fill:#ffffff,stroke:#000000,stroke-width:1px;

    %% Click Events
    click composeUI "https://github.com/blockstream/green_android/tree/master/compose/"
    click greenUI "https://github.com/blockstream/green_android/tree/master/green/"
    click iosClient "https://github.com/blockstream/green_android/tree/master/iosApp/"
    click commonLogic "https://github.com/blockstream/green_android/tree/master/common/src/commonMain/"
    click gdkEngine "https://github.com/blockstream/green_android/tree/master/gdk/"
    click baseGMS "https://github.com/blockstream/green_android/tree/master/base-gms/"
    click gmsServices "https://github.com/blockstream/green_android/tree/master/gms/"
    click noGms "https://github.com/blockstream/green_android/tree/master/no-gms/"
    click hardwareIntegration "https://github.com/blockstream/green_android/tree/master/hardware/"
    click diCommon "https://github.com/blockstream/green_android/tree/master/common/src/commonMain/kotlin/com/blockstream/common/di/"
    click diGreen "https://github.com/blockstream/green_android/tree/master/green/src/main/java/com/blockstream/green/di/"
    click diJade "https://github.com/blockstream/green_android/tree/master/jade/src/commonMain/kotlin/com/blockstream/jade/…"
```
