# kalepail/passkey-kit architecture

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

## Overview

##### Main Components
- Client/Frontend:
- The demo application (under ./demo) that uses Svelte to interact with the SDK.
- The client-side of the SDK (the PasskeyKit module) that is used to initiate wallet actions.
- Server/Backend:
- The server-side library (PasskeyServer) within the TypeScript code (under ./src and possibly invoked from the demo or external services).
- The API endpoints that may be used to communicate with the blockchain or your backend services.
- Blockchain/Contracts:
- The Rust smart contracts (found in ./contracts) that implement the Stellar smart wallet functionality.
- Multiple contracts: example contract, sample policy, smart wallet interface, and smart wallet main contract.
- Event Indexer:
- The Zephyr program (in ./zephyr) which is used to deploy the Mercury Zephyr indexing service for wallet events, such as signer registration and reverse lookup.
- Package/Library Modules:
- Additional packages (in ./packages/passkey-kit-sdk and ./packages/sac-sdk) which form part of the overall npm/TypeScript ecosystem, handling specific domains of the SDK.
- Testing:
- The bun_tests for quick testing of some TypeScript functionality.

##### Interactions and Data Flows
- How the client (demo application or other frontends) calls into the PasskeyKit module to create and manage wallets.
- Connection from the SDK to the smart contracts on the Stellar network. This should demonstrate how wallet actions trigger blockchain transactions invoking the Rust contracts.
- Communication pathways between the different npm packages (passkey-kit-sdk and sac-sdk) and the main SDK code in ./src.

##### Architectural Patterns and Design Principles
- Separation of concerns: clearly delineate the client, server, smart contract, and indexing components.
- Modular design: note how the TypeScript code is split into distinct packages and libraries to allow reuse and customization.
- Interoperability between TypeScript and Rust: indicate the boundary where blockchain interactions occur, and the necessary interfaces (e.g., using Soroban contracts on Stellar and the Mercury/JWT-based authentication for Zephyr indexing).

##### Technologies and Frameworks
- TypeScript and Node (pnpm-managed) for the SDK and demo.
- Svelte for the demo front-end.
- Rust (with Cargo and Makefiles) for the smart contracts and Zephyr program.
- Mercurial Zephyr via mercury-cli for the event indexing service.
- Testing tools such as Bun (for bun_tests) and potentially others in the TypeScript ecosystem.
- Configuration files (e.g., tsconfig.json, pnpm-lock.yaml) which indicate build processes and package management.

##### Final Advice
- Every architectural element described in the README is represented.
- Notes on any configuration dependencies (e.g., environment variables needed in the demo and server setup).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Frontend Client"
        DemoSvelte["Demo Application (Svelte Client)"]:::typescript
        PasskeyKit["PasskeyKit Client Module"]:::typescript
    end

    subgraph "Backend Services"
        PasskeyServer["PasskeyServer"]:::typescript
        PCKSDK["passkey-kit-sdk Package"]:::typescript
        SACSDK["sac-sdk Package"]:::typescript
    end

    subgraph "Blockchain Smart Contracts"
        Contracts["Rust Smart Contracts"]:::rust
        ExampleContract["Example Contract"]:::rust
        SamplePolicy["Sample Policy Contract"]:::rust
        SmartWalletInterface["Smart Wallet Interface"]:::rust
        SmartWalletMain["Smart Wallet Main Contract"]:::rust
    end

    subgraph "Event Indexing Service"
        Zephyr["Zephyr Event Indexer"]:::rust
    end

    subgraph "Testing"
        BunTests["Bun Tests"]:::testing
    end

    %% Interactions and Data Flows
    DemoSvelte -->|"initiates"| PasskeyKit
    DemoSvelte -->|"callsAPI"| PasskeyServer
    PasskeyKit -->|"usesLib"| PCKSDK
    PasskeyKit -->|"usesLib"| SACSDK
    PasskeyKit -->|"submitsTx"| PasskeyServer
    PasskeyServer -->|"invokes"| ExampleContract
    PasskeyServer -->|"invokes"| SamplePolicy
    PasskeyServer -->|"invokes"| SmartWalletInterface
    PasskeyServer -->|"invokes"| SmartWalletMain
    ExampleContract -->|"emitsEvent"| Zephyr
    SamplePolicy -->|"emitsEvent"| Zephyr
    SmartWalletInterface -->|"emitsEvent"| Zephyr
    SmartWalletMain -->|"emitsEvent"| Zephyr
    BunTests -->|"tests"| PasskeyKit
    BunTests -->|"tests"| PasskeyServer

    %% Click Events
    click DemoSvelte "https://github.com/kalepail/passkey-kit/tree/next/demo/"
    click PasskeyKit "https://github.com/kalepail/passkey-kit/blob/next/src/kit.ts"
    click PasskeyServer "https://github.com/kalepail/passkey-kit/blob/next/src/server.ts"
    click ExampleContract "https://github.com/kalepail/passkey-kit/blob/next/contracts/example-contract/src/lib.rs"
    click SamplePolicy "https://github.com/kalepail/passkey-kit/blob/next/contracts/sample-policy/src/lib.rs"
    click SmartWalletInterface "https://github.com/kalepail/passkey-kit/blob/next/contracts/smart-wallet-interface/src/lib.rs"
    click SmartWalletMain "https://github.com/kalepail/passkey-kit/blob/next/contracts/smart-wallet/src/lib.rs"
    click Zephyr "https://github.com/kalepail/passkey-kit/tree/next/zephyr/"
    click PCKSDK "https://github.com/kalepail/passkey-kit/tree/next/packages/passkey-kit-sdk/"
    click SACSDK "https://github.com/kalepail/passkey-kit/tree/next/packages/sac-sdk/"
    click BunTests "https://github.com/kalepail/passkey-kit/tree/next/bun_tests/"

    %% Styles & Classes
    classDef typescript fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef rust fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef testing fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
