# gemwalletcom/core architecture

> Architecture diagram of the GitHub repository gemwalletcom/core, 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/gemwalletcom/core
- Repository: https://github.com/gemwalletcom/core

## Overview

##### Project Purpose and Nature
- This is the core engine for Gem Wallet, a decentralized multi-chain crypto wallet built in Rust. It provides backend services for transaction indexing, asset pricing, notifications, name resolution (like ENS), NFT handling, swap operations, staking, and fiat ramping.
- It serves both backend APIs (for web or services) and mobile integrations (via the Gemstone library for iOS and Android).

##### Main Architectural Components
- API Server:
– Located in “apps/api” and responsible for handling client requests. It interacts with the core logic (via various crates) and the database.
- Daemon/Background Jobs:
– Found under “apps/daemon”, this component processes periodic updates such as asset prices, NFT updates, price alerts, transaction processing, etc.
- Parser Service:
– Under “apps/parser”, used to parse blockchain/transaction data and possibly feed it to the API and daemon.
- Setup Tools:
– “apps/setup” which can manage initial data migrations or configuration.
- Command-line Utilities:
– Various binaries in “bin” (e.g., generate, img-downloader, swapper-dump, uniffi-bindgen) that support auxiliary processes like code generation or asset management.
- Core Libraries (Crates):
– Located in “crates”: They cover blockchain connectivity (e.g., “blockchain”, “gem_chain_rpc”, “gem_evm”, “gem_solana”, “gem_ton”, “gem_sui”), API connectors, fiat operations, NFT processing, name resolution, caching, job running, and more. They are the building blocks that support the higher-level applications.
- Storage:
– The “crates/storage” directory along with diesel migration files provides the persistence layer (database connectivity and schema).
- Mobile Integration Library:
– The “gemstone” directory bundles the cross-platform library used for native mobile integration (iOS and Android). It abstracts core functionality (async networking, transaction handling, etc.) so that mobile apps can easily integrate with the core engine.
- Configuration, Settings, and Infrastructure:
– Various configuration files (e.g., Cargo.toml, Settings.yaml, diesel.toml, Dockerfile, docker-compose.yml) and CI/CD setups (in .github/workflows) highlight deployment, testing, and build components.

##### Relationships and Data Flow
- The API Server acts as the entry point for client requests and communicates with the Database (managed by Storage crates) to read/write data.
- The Daemon periodically executes background tasks such as updating asset prices, verifying blockchain state via the blockchain-related crates, and pushing notifications.
- The Parser Service ingests data from external blockchain nodes via connectors and feeds processed events to the API and Daemon.
- The Mobile Library (Gemstone) acts as a bridge on client devices, communicating with the API and possibly embedding some of the core functionalities from the crates.
- Common dependencies such as the blockchain connectors, fiat providers, and swap modules are shared across applications building up a cohesive ecosystem.
- The CI/CD pipelines (GitHub workflows) ensure that all components (API, Daemon, mobile libraries, CLI utilities, etc.) remain integrated and well-tested.

##### Architectural Patterns and Design Principles
- Modular Design: The use of “crates” demonstrates a highly modular architecture, where each service (blockchain communication, storage, swap logic, etc.) is encapsulated.
- Service Separation: There is a clear division between stateless API endpoints, background daemon processes for asynchronous tasks, and specialized utilities (parser, setup).
- Infrastructure as Code: Dockerfiles, docker-compose and CI workflows indicate that deployment, testing, and build processes are automated.
- Cross-Platform Integration: The Gemstone library abstracts the core functionalities for native mobile consumption while the backend remains in Rust.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        M["Mobile Clients (iOS/Android)"]:::client
        W["Web Frontend"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        API["apps/api (API Server)"]:::service
    end

    %% Background Processing
    subgraph "Background Processing"
        DM["apps/daemon (Daemon)"]:::service
    end

    %% Parser/Integration Layer
    subgraph "Parser/Integration Layer"
        P["apps/parser (Parser Service)"]:::service
    end

    %% Setup Tools
    S["apps/setup (Setup Tools)"]:::service

    %% Command-line Utilities
    subgraph "Command-line Utilities"
        CLI["bin (CLI Utilities)"]:::cli
        CLI1["bin/generate"]:::cli
        CLI2["bin/img-downloader"]:::cli
        CLI3["bin/swapper-dump"]:::cli
        CLI4["bin/uniffi-bindgen"]:::cli
    end

    %% Core Libraries
    subgraph "Core Libraries"
        BL["crates/blockchain"]:::library
        GCR["crates/gem_chain_rpc"]:::library
        GEVM["crates/gem_evm"]:::library
        GSOL["crates/gem_solana"]:::library
        GTON["crates/gem_ton"]:::library
        GSUI["crates/gem_sui"]:::library
    end

    %% Storage
    STD["crates/storage (Storage)"]:::storage

    %% Mobile Integration Library
    MEL["gemstone (Mobile Integration)"]:::library

    %% External Services
    EX["External Services (Blockchain,Fiat,ENS,etc.)"]:::external

    %% CI/CD & Infrastructure
    CICD["CI/CD & Infrastructure"]:::infrastructure

    %% Data Flow
    M -->|"requests"| API
    W -->|"requests"| API
    M -->|"uses"| MEL
    MEL -->|"integrates"| API

    API -->|"read/write"| STD
    DM -->|"update/read"| STD

    P -->|"feeds data"| API
    P -->|"feeds data"| DM

    S -->|"configs"| API
    S -->|"configs"| STD

    API -->|"uses"| BL
    API -->|"uses"| GCR
    API -->|"uses"| GEVM
    API -->|"uses"| GSOL
    API -->|"uses"| GTON
    API -->|"uses"| GSUI

    DM -->|"uses"| BL
    P -->|"uses"| BL

    BL -->|"connects"| EX
    DM -->|"fetches"| EX
    P -->|"parses"| EX

    CLI -->|"triggers"| BL

    CICD -->|"builds"| API
    CICD -->|"builds"| DM
    CICD -->|"builds"| P
    CICD -->|"builds"| CLI
    CICD -->|"builds"| S
    CICD -->|"builds"| MEL

    %% Click Events
    click API "https://github.com/gemwalletcom/core/tree/main/apps/api"
    click DM "https://github.com/gemwalletcom/core/tree/main/apps/daemon"
    click P "https://github.com/gemwalletcom/core/tree/main/apps/parser"
    click S "https://github.com/gemwalletcom/core/tree/main/apps/setup"
    click CLI "https://github.com/gemwalletcom/core/tree/main/bin"
    click CLI1 "https://github.com/gemwalletcom/core/tree/main/bin/generate"
    click CLI2 "https://github.com/gemwalletcom/core/tree/main/bin/img-downloader"
    click CLI3 "https://github.com/gemwalletcom/core/tree/main/bin/swapper-dump"
    click CLI4 "https://github.com/gemwalletcom/core/tree/main/bin/uniffi-bindgen"
    click BL "https://github.com/gemwalletcom/core/tree/main/crates/blockchain"
    click GCR "https://github.com/gemwalletcom/core/tree/main/crates/gem_chain_rpc"
    click GEVM "https://github.com/gemwalletcom/core/tree/main/crates/gem_evm"
    click GSOL "https://github.com/gemwalletcom/core/tree/main/crates/gem_solana"
    click GTON "https://github.com/gemwalletcom/core/tree/main/crates/gem_ton"
    click GSUI "https://github.com/gemwalletcom/core/tree/main/crates/gem_sui"
    click STD "https://github.com/gemwalletcom/core/tree/main/crates/storage"
    click MEL "https://github.com/gemwalletcom/core/tree/main/gemstone"

    %% Styles
    classDef client fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef service fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef cli fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef library fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef storage fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef infrastructure fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
