# zeusln/zeus architecture

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

- Interactive diagram: https://gitdiagram.com/zeusln/zeus
- Repository: https://github.com/zeusln/zeus

## Overview

##### Main Components
- Mobile App UI & Presentation Layer:
- React Native “views” folder: Contains screens for activities, payment requests, channels, settings, etc.
- “components”, “layout”, and “text” folders: Reusable UI components like buttons, forms, QR code scanning UI, etc.
- State Management / Business Logic:
- “stores” and “models” folders: Centralized state containers (e.g., for balance, channels, transactions) and business data structures.
- “utils” folder: Utility functions handling formatting, error handling, cryptographic functions, etc.
- Native Integration Layer:
- “android” and “ios” directories: Platform-specific code, native modules, bridging (e.g. NavigationService.ts, native notifications, QR scanning integrations).
- Node / Backend Communication:
- “backends” folder: Contains various adapters (like CLNRest, EmbeddedLND, LndHub, NostrWalletConnect, etc.) for interfacing with remote lightning nodes.
- “proto” and “zeus_modules” folders: Handle API definitions, gRPC communication protocols, and include libraries from Lightning Labs for LND and Core Lightning.
- External Services & Assets:
- “assets” and “locales”: Static files such as fonts, images, and translation files.
- “push notifications” or “navigation service”: Handling external device events.

##### Relationships and Data Flow
- The UI components display screens and receive user interactions.
- User actions are propagated to the stores (via state management libraries) where business logic and user session data are handled.
- Stores interact with models to prepare data.
- When remote node communication is required (e.g. to query channel info, process payments, or manage invoices), the stores call the corresponding functions in the “backends” layer.
- The backend components use the protocols defined in “proto” and the libraries in “zeus_modules” (from @lightninglabs) to communicate with remote nodes or services.
- Native modules (in the “android” and “ios” directories) are used to bridge platform-specific functionalities (such as notifications, NFC, camera/QR scanning, etc.) with the JavaScript layer.
- Utility modules support data conversion (e.g., for macaroons), error handling, and formatting of data transferred between components.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Clear separation between UI (views, components), state management (stores/models), business logic (utils, backends), and native integrations.
- Abstraction Layers: Backends provide abstracted interfaces to multiple types of node connections (LND, Core Lightning, LNDHub, etc.).
- Modular Design: ZEUS is organized in modules (each in its own directories like “stores”, “backends”, “models”, “views”) to promote easier maintenance and scalability.
- Cross-Platform Consistency: The shared code base (React Native) is supported by platform-specific folders that handle the Android and iOS intricacies.

##### Technical Elements and Notable Technologies
- React Native and TypeScript as the main development stack.
- Native OS support via Android Studio and Xcode projects.
- Use of gRPC and protocol buffers (from the “proto” folder) for node communication.
- Integration with external libraries (e.g., from @lightninglabs in “zeus_modules”) to handle Lightning network connections.
- Handling of localizations and asset management through “locales” and “assets”.

##### Additional Notes
- Integration points for connectivity via Tor (as mentioned in the README) by annotating the communication paths for secure node connections.
- Given the extensive use of third-party libraries (e.g., @lightninglabs packages, bc-bech32, bc-ur), mark these components as “External Libraries” that support the backend communication layer.

## Diagram (Mermaid)

```mermaid
graph TD
    User["User"]:::user

    subgraph "Presentation Layer"
        UI_Views["Views (UI Screens)"]:::ui
        UI_Components["UI Components"]:::ui
    end

    subgraph "State Management"
        SM_Stores["Stores"]:::state
        SM_Models["Models"]:::state
        SM_Utils["Utils"]:::state
    end

    subgraph "Backend Communication"
        Backend_Adapters["Backend Adapters"]:::backend
        Protocol_Def["Protocol Definitions"]:::backend
        LightningLib["Lightning Libraries"]:::backend
    end

    subgraph "Native Integration"
        Native_Android["Android Native Code"]:::native
        Native_iOS["iOS Native Code"]:::native
        subgraph "Native Services"
            NS_Navigation["NavigationService.ts"]:::native
            NS_Push["PushNotificationManager.tsx"]:::native
            Native_Service["Native Bridge"]:::native
        end
    end

    subgraph "External Services & Assets"
        External_Assets["Assets"]:::external
        External_Locales["Locales"]:::external
    end

    Remote_Nodes["Remote Bitcoin/Lightning Nodes"]:::external

    User -->|"interacts"| UI_Views
    User -->|"interacts"| UI_Components

    UI_Views -->|"triggers"| SM_Stores
    UI_Components -->|"triggers"| SM_Stores

    SM_Stores -->|"manages"| SM_Models
    SM_Stores -->|"utilizes"| SM_Utils

    SM_Stores -->|"invokes"| Backend_Adapters
    Backend_Adapters -->|"uses"| Protocol_Def
    Protocol_Def -->|"interfaces"| LightningLib
    LightningLib -->|"communicates"| Remote_Nodes

    Native_Android -->|"bridges"| Native_Service
    Native_iOS -->|"bridges"| Native_Service
    NS_Navigation -->|"feeds"| Native_Service
    NS_Push -->|"feeds"| Native_Service
    Native_Service -->|"updates"| UI_Views

    External_Assets -.->|"resources"| UI_Views
    External_Locales -.->|"translations"| UI_Views

    click UI_Views "https://github.com/zeusln/zeus/tree/master/views"
    click UI_Components "https://github.com/zeusln/zeus/tree/master/components"
    click SM_Stores "https://github.com/zeusln/zeus/tree/master/stores"
    click SM_Models "https://github.com/zeusln/zeus/tree/master/models"
    click SM_Utils "https://github.com/zeusln/zeus/tree/master/utils"
    click Backend_Adapters "https://github.com/zeusln/zeus/tree/master/backends"
    click Protocol_Def "https://github.com/zeusln/zeus/tree/master/proto"
    click LightningLib "https://github.com/zeusln/zeus/tree/master/zeus_modules"
    click Native_Android "https://github.com/zeusln/zeus/tree/master/android"
    click Native_iOS "https://github.com/zeusln/zeus/tree/master/ios"
    click NS_Navigation "https://github.com/zeusln/zeus/blob/master/NavigationService.ts"
    click NS_Push "https://github.com/zeusln/zeus/blob/master/PushNotificationManager.tsx"
    click External_Assets "https://github.com/zeusln/zeus/tree/master/assets"
    click External_Locales "https://github.com/zeusln/zeus/tree/master/locales"

    classDef ui fill:#ffdd57,stroke:#333,stroke-width:2px;
    classDef state fill:#a6dcef,stroke:#333,stroke-width:2px;
    classDef backend fill:#f3a683,stroke:#333,stroke-width:2px;
    classDef native fill:#b8e994,stroke:#333,stroke-width:2px;
    classDef external fill:#dfe6e9,stroke:#333,stroke-width:2px;
    classDef user fill:#ffccff,stroke:#333,stroke-width:2px;
```
