# blockstream/green_ios architecture

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

- Interactive diagram: https://gitdiagram.com/blockstream/green_ios
- Repository: https://github.com/blockstream/green_ios

## Overview

This project is an iOS native wallet application—Blockstream Green—that lets users securely store, send, and receive Bitcoin. It is structured as a full-fledged mobile app integrating several specialized subsystems, including wallet core functionality from the shared gdk library, hardware wallet integration, lightning network support, notification services, and extensive UI components for a native iOS experience.

##### Main Components
- UI/Presentation Layer (“gaios”): This directory holds nearly all the user interface components (storyboards, view controllers, views, localization, etc.). It implements industry patterns such as MVC/MVVM.
- Core Business Logic (“core” and “gdk”): The “core” folder houses analytics, session, repositories, and models that represent the wallet’s internal state. “gdk” provides the cross-platform wallet library to handle core Bitcoin functionality such as accounts, transactions, network settings, and security.
- Hardware and External Integrations (“hw”, “greenaddress”, “lightning”): The “hw” directory supports integration with hardware wallets (e.g., Ledger and Jade), while “greenaddress” offers additional wallet-related utilities and “lightning” interfaces for the Lightning network.
- Notification and Background Services (“NotificationService”): This service module handles background tasks such as confirming transactions or updating swap statuses.
- Configuration and Build Tools (“configs”, “fastlane”, “tools”): These directories contain configuration files (xcconfig settings for development/production) and build/deployment scripts.

##### Relationships and Data Flows
- The core modules communicate with hardware integration modules (“hw”) and external integrations (“lightning”, “greenaddress”) to fetch or update wallet data.
- The NotificationService consumes events (e.g., confirmation of transactions) and interacts with the core to update state, while also using local configuration settings.
- Analytics and logging (found in “core/Countly” and “core/Managers/Logger.swift”) propagate usage events upward for remote monitoring.
- Build scripts and CI configuration files facilitate deployment and integration, but usually reside off to the side of the operational architecture.

##### Architectural Patterns
- MVC/MVVM Patterns: The project extensively uses view controllers, view models, and storyboards (especially in the “gaios” and “OnBoard” directories) to separate UI from business logic.
- Modular Design: The separation into distinct directories (UI, core wallet logic, hardware wallet integration, network communication, and notifications) shows a modular design. Each module’s responsibility is clearly delimited.
- Cross-Platform Integration: The use of gdk indicates that the wallet’s core functions are shared across platforms, with this iOS version focusing on native UI and experience.

##### Relevant Technologies, Frameworks, and Libraries
- Swift and Xcode: The entire project is built using Swift with Xcode projects (“gaios.xcodeproj”).
- External dependencies: gdk serves as the wallet’s core library; integrations with hardware wallet modules and lightning network components are present.
- Localization: Multiple localization directories (e.g., “en.lproj”, “de.lproj”, etc.) indicate a robust multi-language support strategy.
- Fastlane: Used for automated builds and deployments.
- CI/CD: GitHub Actions, GitLab CI configurations are included for continuous integration/deployment.

##### Capturing Essential Architectural Elements
- Out every major component as a node.
- Design patterns (MVC/MVVM) where appropriate by annotating components with their responsibilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI/Presentation Layer"
        A["UI (gaios)"]:::ui
    end

    subgraph "Core Business Logic"
        B["Core (core)"]:::core
        C["GDK (gdk)"]:::core
    end

    subgraph "Integration Layer"
        D["Hardware Wallet Integration (hw)"]:::integration
        E["GreenAddress (greenaddress)"]:::integration
        F["Lightning & Network (lightning)"]:::integration
    end

    subgraph "Notification & Services"
        G["Notification Service (NotificationService)"]:::service
    end

    subgraph "Configuration & Build Tools"
        H["Configs (configs)"]:::config
        I["Fastlane (fastlane)"]:::config
        J["Tools (tools)"]:::config
    end

    %% Connections from UI to Core Business Logic
    A -->|"UserAction"| B
    A -->|"UserAction"| C

    %% Core Business Logic to Integration Layer
    B -->|"calls"| D
    B -->|"calls"| E
    B -->|"calls"| F
    C -->|"calls"| D
    C -->|"calls"| E
    C -->|"calls"| F

    %% Notification Service updates Core Business Logic
    G -->|"updates"| B
    G -->|"updates"| C

    %% Configuration & Build Tools feeding Notification Service
    H -->|"configures"| G
    I -->|"builds"| G
    J -->|"scripts"| G

    classDef ui fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef core fill:#A9DFBF,stroke:#239B56,stroke-width:2px;
    classDef integration fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef service fill:#F5CBA7,stroke:#CD6155,stroke-width:2px;
    classDef config fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;

    click A "https://github.com/blockstream/green_ios/tree/master/gaios"
    click B "https://github.com/blockstream/green_ios/tree/master/core"
    click C "https://github.com/blockstream/green_ios/tree/master/gdk"
    click D "https://github.com/blockstream/green_ios/tree/master/hw"
    click E "https://github.com/blockstream/green_ios/tree/master/greenaddress"
    click F "https://github.com/blockstream/green_ios/tree/master/lightning"
    click G "https://github.com/blockstream/green_ios/tree/master/NotificationService"
    click H "https://github.com/blockstream/green_ios/tree/master/configs"
    click I "https://github.com/blockstream/green_ios/tree/master/fastlane"
    click J "https://github.com/blockstream/green_ios/tree/master/tools"
```
