# runonflux/ssp-key architecture

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

- Interactive diagram: https://gitdiagram.com/runonflux/ssp-key
- Repository: https://github.com/runonflux/ssp-key

## Overview

##### Project Type and Purpose
- The project is a secure key management mobile application built with React Native (using TypeScript). It is a 2FA solution that holds the secondary private key for multisig transactions.
- It runs on both Android and iOS (note platform-specific directories and native configuration files), and it integrates with an external wallet system (SSP Wallet) to form a secure 2-of-2 signing system.

##### File Structure
- Top-level Directories:
- Android and ios directories hold platform-specific native code and assets.
- src directory contains the React Native application code. It is organized into components, screens, navigators (for routing), contexts (state management for sockets), hooks, lib (utility functions like encryption and wallet handling), store (Redux or similar state slices), theme (styling and assets), and translations (i18n).
- Native build files and configuration scripts (e.g., build.gradle for Android, Podfile for iOS) denote that proper native integration and deployment is taken care of.
- The existence of test files, TypeScript declarations, and configuration files like jest.config.js indicates a modern, test-driven, and well-configured development setup.
- The file structure suggests separation of concerns with components for UI, navigation for page routing, libraries for business logic (such as constructing transactions and handling encryption), and state management (store).

##### README for Additional Insights
- The README describes the product as “Secure. Simple. Powerful.” emphasizing security and simplicity.
- It details encryption techniques (using “react-native-encrypted-storage”, CryptoJS, and MMKV) along with device-specific security (using DeviceInfo.getUniqueID()).
- It explains the tight integration with SSP Wallet for a multisignature (2-of-2) process, meaning the application must securely interact with external services (the wallet ecosystem).

a. Main components:
- Mobile Client Application (React Native)
- UI Layer: Constituted by components (functional UI elements), screens (pages like Home, Create, Restore, Startup, Welcome), and navigators that drive the user flow.
- State Management & Context: Includes global state (Redux store or similar) and context providers like SocketContext for real-time communication.
- Utility/Library Layer: Contains modules for encryption (e.g., util functions in lib using CryptoJS), wallet operations, token management, and transaction construction.
- Localization and Theming: Managed in the translations and theme directories.
- Secure Storage & Encryption Subsystem:
- Handles secure storage of sensitive data (private keys, salts, IVs) using encrypted storage libraries.
- Device Identification: Integrates calls like DeviceInfo.getUniqueID() to tie encryption to the specific device.
- Native Integration Layers:
- Android and iOS native projects that wrap around the React Native code, including configuration files, native assets, and build scripts.
- External Integration:
- Integration with SSP Wallet (as explained in the README). This includes API calls or linking guidance provided in the documentation.

b. Relationships and Interactions:
- The UI layer (screens and components) interacts with the utility/lib layer whenever a sensitive operation (e.g., key encryption, transaction signing) is triggered.
- The secure storage module is a core dependency, being called by both the encryption service and the wallet functionalities.
- Global state and context (store, hooks, and contexts like SocketContext) propagate state changes throughout the application.
- Platform-specific layers (Android/iOS) serve as wrappers and allow the mobile client to access device-specific features (unique device ID, secure element).
- External calls or linking with SSP Wallet are depicted as outbound connections or API integrations.

c. Architectural Patterns or Principles:
- Separation of Concerns: Clear decoupling between UI (components, screens), business logic (lib and store), and native integration.
- Modular Design: The code is divided into components, hooks, contexts, and libraries that can each be updated or tested independently.
- Security by Design: Strong emphasis on encryption, secure storage, and device-specific key generation.
- Multiplatform Support: Use of React Native ensures a cross-platform design, with tailored native bridges for Android and iOS.

d. Relevant Technologies and Frameworks:
- React Native and React 18 for UI
- TypeScript for type-safe programming.
- Secure libraries such as react-native-encrypted-storage, CryptoJS, and MMKV.
- Navigation libraries for routing (as indicated by directories in navigators).
- Testing frameworks (Jest configuration, tests folder).
- Build tools (Gradle for Android, Xcode/Podfile for iOS).

## Diagram (Mermaid)

```mermaid
graph TD
    UI["Mobile Client UI Layer"]:::uiStyle
    SM["State Management & Context"]:::stateStyle
    LIB["Utility/Library (Encryption & Wallet Ops)"]:::libStyle
    SEC["Secure Storage & Encryption Subsystem"]:::secStyle
    LOC["Localization & Theming"]:::locStyle
    NAT["Native Integration Layers (Android & iOS)"]:::nativeStyle
    EXT["External SSP Wallet Integration"]:::externalStyle

    UI -->|"updates"| SM
    UI -->|"triggers"| LIB
    SM -->|"informs"| LIB
    LIB -->|"stores_keys_in"| SEC
    LIB -->|"integrates_with"| EXT
    UI -->|"styled_by"| LOC
    UI -->|"accesses"| NAT

    click UI "https://github.com/runonflux/ssp-key/tree/master/src/screens"
    click UI "https://github.com/runonflux/ssp-key/tree/master/src/components"
    click SM "https://github.com/runonflux/ssp-key/tree/master/src/store"
    click SM "https://github.com/runonflux/ssp-key/tree/master/src/contexts"
    click LIB "https://github.com/runonflux/ssp-key/blob/master/src/lib/constructTx.ts"
    click LIB "https://github.com/runonflux/ssp-key/blob/master/src/lib/wallet.ts"
    click LIB "https://github.com/runonflux/ssp-key/blob/master/src/lib/transactions.ts"
    click LOC "https://github.com/runonflux/ssp-key/tree/master/src/translations"
    click LOC "https://github.com/runonflux/ssp-key/tree/master/src/theme"
    click NAT "https://github.com/runonflux/ssp-key/tree/master/android"
    click NAT "https://github.com/runonflux/ssp-key/tree/master/ios"
    click EXT "https://github.com/runonflux/ssp-key/tree/master/src/store/ssp"
    click EXT "https://github.com/runonflux/ssp-key/tree/master/src/components/SSPKeyDetails"

    classDef uiStyle fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef stateStyle fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef libStyle fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef secStyle fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef locStyle fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef nativeStyle fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef externalStyle fill:#87CEFA,stroke:#333,stroke-width:2px;
```
