# hoblayerta/stellar-account-abstraction-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/hoblayerta/stellar-account-abstraction-sdk
- Repository: https://github.com/hoblayerta/stellar-account-abstraction-sdk

## Overview

##### Project type and purpose
- This is a client-centric dApp project composed of three parts:
- A Soroban Rust smart-contracts module under `contracts/`
- A TypeScript SDK (`stellar-social-sdk/`) that abstracts social authentication and blockchain interactions
- A Next.js demo front-end (`demo-app/`) showcasing login, account management, and payments
- Purpose: let web apps onboard users with Google/Facebook/phone/Freighter, deterministically generate Stellar keypairs, and manage a social wallet via on-chain contracts.

##### File structure
- Top-level directories:
- `contracts/social-account/` – Rust code, tests, build scripts for the on-chain logic
- `stellar-social-sdk/` – a rollup’d TS library exposing SDK methods (`authenticateWithGoogle()`, `connectFreighter()`, `sendPayment()`, etc.)
- `demo-app/` – Next.js front-end integrating the SDK, with pages under `src/app` and static assets under `public`
- Config and build files:
- Rust/Cargo files in `contracts`
- `rollup.config.js`, `tsconfig.json` in `stellar-social-sdk`
- `next.config.js`, ESLint, PostCSS in `demo-app`
- No separate backend service—everything runs in the browser or on the Soroban network.

##### README for additional insights
- SDK config (contract ID, network) points at the Soroban RPC/Horizon endpoints
- Demo connects directly to OAuth providers (Google/Facebook mock), phone OTP, and the Freighter browser extension
- Smart contracts handle account initialization, auth-method CRUD, and transaction validation on-chain

##### Essential elements
- Don’t forget environment/config: contract ID, network (testnet/mainnet)
- Testing tools: Friendbot, Cargo tests, SDK dev mode
- Deterministic key-generation step and how auth methods map to on-chain storage

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Demo Front-End
    subgraph "Demo Front-End" 
        direction TB
        DConfig["Next.js Config"]:::ui
        LayoutStyling["Global Layout & Styling"]:::ui
        HomePage["Home Page (Onboarding & Login)"]:::ui
        AuthCallback["Auth Callback Handler"]:::ui
        SDKIntegration["SDK Integration Layer"]:::ui
        StaticAssets["Static Assets"]:::ui
        LintStyle["Lint & Style Config"]:::ui
    end

    %% Client-Side SDK
    subgraph "Client-Side SDK" 
        direction TB
        SDKEntry["SDK Entry Point & Public API"]:::sdk
        SDKConfig["SDK Configuration"]:::sdk
        AuthCore["Auth Core Class"]:::sdk
        GoogleProvider["Google OAuth Provider"]:::sdk
        FreighterProvider["Freighter Extension Provider"]:::sdk
        CryptoUtils["Deterministic KeyGen & Crypto Utils"]:::sdk
        TypeDefs["SDK Type Definitions"]:::sdk
        SDKBuildConfig["SDK Build Config"]:::sdk
        SDKBundle["Rollup Bundle Outputs"]:::sdk
    end

    %% External Auth Providers
    subgraph "External Auth Providers"
        direction TB
        Google["Google OAuth"]:::ext
        Facebook["Facebook Mock"]:::ext
        SMS["Phone OTP Service"]:::ext
        Freighter["Freighter Browser Extension"]:::ext
    end

    %% Blockchain Network
    subgraph "Blockchain Network"
        direction TB
        Horizon["Horizon API (REST)"]:::rpc
        SorobanRPC["Soroban RPC"]:::rpc
        Friendbot["Friendbot (Testnet Funding)"]:::rpc
    end

    %% On-Chain Smart Contracts
    subgraph "On-Chain Smart Contracts"
        direction TB
        WASM["Compiled WASM Binary"]:::onchain
        LibRs["Smart Contract Source (lib.rs)"]:::onchain
        Tests["Contract Test Suite"]:::onchain
        Snapshots["Test Snapshots"]:::onchain
        CargoConfig["Rust/Cargo Config"]:::onchain
        Ledger["Stellar Ledger (State)"]:::onchain
    end

    %% Connections
    HomePage -->|"user actions"| SDKIntegration
    AuthCallback -->|"oauth callback"| SDKIntegration
    SDKIntegration -->|"calls SDK API"| SDKEntry
    SDKEntry --> SDKConfig
    SDKEntry --> AuthCore
    AuthCore --> GoogleProvider
    AuthCore --> FreighterProvider
    AuthCore --> CryptoUtils
    AuthCore --> TypeDefs
    SDKBundle --> SDKEntry
    SDKBuildConfig --> SDKBundle
    SDKConfig --> SDKEntry

    GoogleProvider -->|"invoke OAuth"| Google
    FreighterProvider -->|"invoke extension"| Freighter
    SMS -->|"invoke SMS OTP"| AuthCore
    Facebook -->|"invoke mock OAuth"| AuthCore

    SDKEntry -->|"init & tx calls"| Horizon
    SDKEntry -->|"invoke contracts"| SorobanRPC
    SorobanRPC --> WASM
    SorobanRPC --> LibRs
    SorobanRPC --> Tests
    SorobanRPC --> Snapshots
    SorobanRPC --> CargoConfig
    WASM --> Ledger
    Friendbot --> Ledger

    %% Demo assets and config
    DConfig --> LayoutStyling
    LayoutStyling --> HomePage
    HomePage --> AuthCallback
    SDKIntegration --> StaticAssets
    DConfig --> SDKIntegration
    DConfig --> LintStyle

    %% Click Events
    click LibRs "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/contracts/social-account/contracts/social-wallet/src/lib.rs"
    click Tests "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/contracts/social-account/contracts/social-wallet/src/test.rs"
    click Snapshots "https://github.com/hoblayerta/stellar-account-abstraction-sdk/tree/main/contracts/social-account/contracts/social-wallet/test_snapshots/"
    click WASM "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/contracts/social-account/social_wallet_cleaned.wasm"
    click SDKEntry "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/stellar-social-sdk/src/index.ts"
    click SDKConfig "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/stellar-social-sdk/src/config.ts"
    click AuthCore "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/stellar-social-sdk/src/auth/StellarSocialAccount.ts"
    click GoogleProvider "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/stellar-social-sdk/src/providers/GoogleAuthProvider.ts"
    click FreighterProvider "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/stellar-social-sdk/src/providers/FreighterProvider.ts"
    click CryptoUtils "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/stellar-social-sdk/src/utils/crypto.ts"
    click TypeDefs "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/stellar-social-sdk/src/types/index.ts"
    click SDKBuildConfig "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/stellar-social-sdk/rollup.config.js"
    click SDKBuildConfig "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/stellar-social-sdk/tsconfig.json"
    click SDKBundle "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/stellar-social-sdk/dist/index.js"
    click SDKBundle "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/stellar-social-sdk/dist/index.esm.js"
    click DConfig "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/demo-app/next.config.js"
    click DConfig "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/demo-app/tsconfig.json"
    click LayoutStyling "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/demo-app/src/app/layout.tsx"
    click LayoutStyling "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/demo-app/src/app/globals.css"
    click HomePage "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/demo-app/src/app/page.tsx"
    click AuthCallback "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/demo-app/src/app/auth/callback/page.tsx"
    click SDKIntegration "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/demo-app/src/lib/sdk.ts"
    click StaticAssets "https://github.com/hoblayerta/stellar-account-abstraction-sdk/tree/main/demo-app/public/"
    click LintStyle "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/demo-app/eslint.config.mjs"
    click LintStyle "https://github.com/hoblayerta/stellar-account-abstraction-sdk/blob/main/demo-app/postcss.config.mjs"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0288D1,stroke-width:1px
    classDef sdk fill:#D0FFD8,stroke:#2E7D32,stroke-width:1px
    classDef ext fill:#FFE0B2,stroke:#EF6C00,stroke-width:1px
    classDef rpc fill:#E0BBE4,stroke:#6A1B9A,stroke-width:1px
    classDef onchain fill:#F5F5F5,stroke:#9E9E9E,stroke-width:1px
```
