# frak-id/wallet architecture

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

## Overview

##### Overall System Components
- Frontend Clients:
- Wallet Frontend: The wallet application (found under packages/wallet and parts of the SDK) that handles user authentication (e.g., SIWE, WebAuthn), onboarding, and wallet-specific interactions.
- Dashboard/Admin Interface: The Next.js–based dashboard (under packages/dashboard) that lets administrators manage campaigns, monitor referral data, and review metrics.
- SDK Integration (React/Vanilla): The SDK components (found in sdk/react, sdk/core, sdk/legacy, and sdk/components) available to client applications for seamless integration into web2 sites.
- Backend Services:
- API & Service Layer: The backend server is largely located in packages/backend-elysia (powered by Elysia.js) that serves as the interface for business logic, routing, and data processing.
- App Essentials & Shared Modules: The common core business and blockchain logic is bundled into packages like app-essentials and packages/shared to serve as the re-usable foundation for business rules (referral tracking, reward distribution, blockchain session management).
- Blockchain and On-Chain Interaction:
- Blockchain Interaction Layer: Integration components (using wagmi and viem) that manage on-chain activities such as gasless transactions, referral events, and reward distribution.
- Smart Wallet and Account Abstraction: Modules under the wallet package and backend handle smart wallet logic, including delegated sessions and WebAuthn based authentication.
- Infrastructure & Deployment:
- Microservices & IaC: Infrastructure scripts (in infra/) and configuration files (sst.config.ts, docker files) signal deployment via AWS and integrations with third-party services such as SST, OpenNext, Pimlico, ZeroDev, ERPC, and Ponder.

##### Architectural Patterns and Design Principles
- Modularity and separation of concerns: Each package in the monorepo (such as dashboard, wallet, backend-elysia, shared, app-essentials, and SDK libraries) represents a clearly decoupled component.
- Patterns like Account Abstraction (for gasless transactions), microservice separations between frontend and backend, and a dedicated blockchain integration layer.
- Extensibility of the SDK, with separate entry points for legacy vanilla JS, React hooks, and bundled core functionalities.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend"
        ClientApps("Client Applications (External)"):::frontend
        WalletFrontend("Wallet Frontend (React)"):::frontend
        Dashboard("Dashboard/Admin Interface (Next.js)"):::frontend
        subgraph "SDK Integration"
            sdkReact("SDK: React"):::sdk
            sdkCore("SDK: Core"):::sdk
            sdkLegacy("SDK: Legacy"):::sdk
            sdkComponents("SDK: Components"):::sdk
        end
        SmartWalletFrontend("Smart Wallet Abstraction (Frontend)"):::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        BackendAPI("Backend API (Elysia.js)"):::backend
        AppEssentials("App Essentials"):::backend
        SharedModules("Shared Modules"):::backend
        SmartWalletBackend("Smart Wallet Backend Logic"):::backend
    end

    %% Blockchain Layer
    subgraph "Blockchain"
        Blockchain("Blockchain Interaction Layer"):::blockchain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        Infrastructure("Infrastructure & Deployment"):::infra
    end

    %% Connections between Frontend and Backend
    ClientApps -->|"integrates"| sdkReact
    sdkReact -->|"callsAPI"| BackendAPI
    WalletFrontend -->|"callsAPI"| BackendAPI
    Dashboard -->|"callsAPI"| BackendAPI
    WalletFrontend -->|"delegatesABI"| SmartWalletFrontend
    SmartWalletFrontend -->|"syncs_with"| SmartWalletBackend
    BackendAPI -->|"handlesSmartWallet"| SmartWalletBackend

    %% Backend to Blockchain interactions
    BackendAPI -->|"onChainCalls"| Blockchain
    AppEssentials -->|"blockchain_logic"| Blockchain
    SharedModules -->|"blockchain_logic"| Blockchain

    %% Backend deployment via Infrastructure
    BackendAPI -->|"deploys"| Infrastructure

    %% Styling classes
    classDef frontend fill:#add8e6,stroke:#0000ff,stroke-width:2px;
    classDef backend fill:#90ee90,stroke:#008000,stroke-width:2px;
    classDef blockchain fill:#ffa500,stroke:#ff8c00,stroke-width:2px;
    classDef infra fill:#d3d3d3,stroke:#696969,stroke-width:2px;
    classDef sdk fill:#87cefa,stroke:#4682b4,stroke-width:2px;

    %% Click Events
    click WalletFrontend "https://github.com/frak-id/wallet/blob/dev/packages/wallet/app/entry.client.tsx"
    click Dashboard "https://github.com/frak-id/wallet/tree/dev/packages/dashboard"
    click sdkReact "https://github.com/frak-id/wallet/tree/dev/sdk/react"
    click sdkCore "https://github.com/frak-id/wallet/tree/dev/sdk/core"
    click sdkLegacy "https://github.com/frak-id/wallet/tree/dev/sdk/legacy"
    click sdkComponents "https://github.com/frak-id/wallet/tree/dev/sdk/components"
    click BackendAPI "https://github.com/frak-id/wallet/tree/dev/packages/backend-elysia"
    click AppEssentials "https://github.com/frak-id/wallet/tree/dev/packages/app-essentials"
    click SharedModules "https://github.com/frak-id/wallet/tree/dev/packages/shared"
    click Blockchain "https://github.com/frak-id/wallet/tree/dev/packages/app-essentials/src/blockchain"
    click SmartWalletFrontend "https://github.com/frak-id/wallet/tree/dev/packages/wallet/app/module/wallet/smartWallet"
    click SmartWalletBackend "https://github.com/frak-id/wallet/tree/dev/packages/backend-elysia/domain/wallet"
    click Infrastructure "https://github.com/frak-id/wallet/tree/dev/infra/"
```
