# no-cash-7970/duckysigner architecture

> Architecture diagram of the GitHub repository no-cash-7970/duckysigner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/no-cash-7970/duckysigner
- Repository: https://github.com/no-cash-7970/duckysigner

## Overview

##### Project type and purpose
- This is a full-stack desktop application prototype (“Ducky Signer Prototype”) built with Wails v3-alpha.
- Purpose: a simple Algorand wallet for signing transactions on the desktop (for testing, not production keys).

##### File structure
Top-level directories:
- frontend – the Svelte/TypeScript UI, packaged into the Wails desktop window
- kmd – customized Algorand Key Management Daemon (KMD) code and wallet drivers (SQLite, Ledger HID)
- services – Go “Wails services” that bridge frontend events to backend logic
- build – OS-specific build definitions and scripts for packaging the app on Windows/Linux/macOS
Files:
- main.go – Wails application bootstrapping
- go.mod/go.sum – Go module definitions
- Taskfile.yml – shortcut tasks for building/testing with wails3

##### Key insights from README
- Uses Wails v3-alpha to combine Go backend + web-UI frontend.
- Frontend tech: Svelte + Tailwind + Vite + Vitest.
- Backend: Go modules under kmd/, services/, main.go.
- KMD code handles wallet storage & cryptography; services expose high-level RPC endpoints.

##### Components
a. Frontend UI (Svelte)
– Components: pages for wallet list, import/create wallet, sign transaction, account view
– Bundled via Vite into static assets, served locally by Wails
b. Wails Runtime
– Embeds a Chromium webview
– Provides bidirectional RPC between JS/TS and Go
– Handles dev mode watcher and production build packaging
c. Go Backend
– main.go: initializes Wails app, binds services
– services package:
- DappConnectService – handshake + message signing for DApp interactions
- KmdService – wallet management operations (create, open, list)
- GreetService – example/test
– wallet_session.go: per-UI session context
d. KMD Module
– config: configuration loading, error definitions
– crypto: algorand key operations, multisig support
– wallet: high-level wallet functions; delegates to driver
– driver subpackage: concrete back ends
- sqlite – persistent key storage, encrypted with Memguard integration
- ledger (HID) – hardware wallet interaction
e. Storage
– SQLite file under user home for private keys
f. External Interfaces
– (Future) Algorand node or dApp endpoints via HTTP or WebSocket
– Ledger hardware via USB/HID
g. Build & CI
– build/Taskfile.*: packaging for Linux (AppImage), macOS (plist), Windows (manifest + exe)

##### Relationships and Data Flows
1. User clicks button in Svelte UI →
2. Wails RPC call to Go service (e.g., KmdService.CreateWallet) →
3. Go service calls into kmd/wallet to perform storage/encryption →
4. Driver (SQLite or Ledger) persists or fetches key →
5. Response bubbles back via Wails to UI →
6. UI updates state (e.g., new wallet listed)
For transaction signing:
UI → DappConnectService → Kmd crypto → Ledger or in-memory key → returns signed txn blob → UI or external dApp

##### Architectural patterns & design principles
- Layered architecture: UI layer, RPC/service layer, domain module (kmd), driver layer
- Dependency inversion: services depend on wallet abstractions, not concrete storage
- Single-responsibility per package: clear separation between config, crypto, storage, UI bindings
- ADR-driven decisions documented under docs/decisions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User("User"):::user
    External("Algorand Node / DApp"):::external

    %% Desktop App Container
    subgraph "Desktop Application"
        subgraph "Frontend Layer"
            SPA("Svelte SPA"):::frontend
        end
        subgraph "Wails Runtime"
            Wails("Wails Runtime"):::runtime
        end
        subgraph "Go Backend"
            subgraph "RPC Services"
                DappService("DappConnectService"):::backend
                KmdService("KmdService"):::backend
                GreetService("GreetService"):::backend
                SessionCtx("WalletSession"):::backend
            end
            subgraph "KMD Module"
                Config("Config Module"):::domain
                Crypto("Crypto Module"):::domain
                WalletAb("Wallet Abstraction"):::domain
                subgraph "Drivers"
                    SQLDriver("SQLite Driver"):::storage
                    LedgerDriver("Ledger HID Driver"):::storage
                end
            end
        end
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Build("Build & Packaging"):::infra
        CI("CI & Documentation"):::infra
    end

    %% Data Stores & Hardware
    SQLiteDB("SQLite DB"):::storage
    LedgerHW("Ledger Hardware (HID)"):::storage

    %% Relationships
    User -->|"uses UI"| SPA
    SPA -->|"RPC call"| Wails
    Wails -->|"forwards RPC"| DappService
    Wails -->|"forwards RPC"| KmdService
    Wails -->|"forwards RPC"| GreetService

    DappService -->|"invokes crypto"| Crypto
    KmdService -->|"manages wallets"| WalletAb
    SessionCtx -.->|"session context"| KmdService

    WalletAb -->|"delegates to"| SQLDriver
    WalletAb -->|"delegates to"| LedgerDriver

    SQLDriver -->|"persists keys"| SQLiteDB
    LedgerDriver -->|"interfaces with"| LedgerHW

    Crypto -->|"signs txn via"| LedgerDriver
    External -->|"HTTP/WebSocket calls"| DappService

    SPA -->|"bundled by"| Build
    CI -->|"publishes ADRs & diagrams"| CI

    %% Click events
    click SPA "https://github.com/no-cash-7970/duckysigner/tree/master/frontend/src/routes/"
    click SPA "https://github.com/no-cash-7970/duckysigner/tree/master/frontend/"
    click Wails "https://github.com/no-cash-7970/duckysigner/blob/master/main.go"
    click DappService "https://github.com/no-cash-7970/duckysigner/blob/master/services/dapp_connect_service.go"
    click KmdService "https://github.com/no-cash-7970/duckysigner/blob/master/services/kmd_service.go"
    click GreetService "https://github.com/no-cash-7970/duckysigner/blob/master/services/greetservice.go"
    click SessionCtx "https://github.com/no-cash-7970/duckysigner/blob/master/services/wallet_session.go"
    click Config "https://github.com/no-cash-7970/duckysigner/blob/master/kmd/config/config.go"
    click Crypto "https://github.com/no-cash-7970/duckysigner/blob/master/kmd/crypto/util.go"
    click WalletAb "https://github.com/no-cash-7970/duckysigner/blob/master/kmd/wallet/wallet.go"
    click SQLDriver "https://github.com/no-cash-7970/duckysigner/blob/master/kmd/wallet/driver/sqlite.go"
    click LedgerDriver "https://github.com/no-cash-7970/duckysigner/blob/master/kmd/wallet/driver/ledger_hid.go"
    click Build "https://github.com/no-cash-7970/duckysigner/blob/master/Taskfile.yml"
    click CI "https://github.com/no-cash-7970/duckysigner/blob/master/.github/workflows/publish-diagrams.yml"

    %% Styles
    classDef user fill:#a8dadc,stroke:#1d3557,color:#1d3557;
    classDef external fill:#ececec,stroke:#4a4a4a,color:#4a4a4a;
    classDef frontend fill:#a8e6cf,stroke:#379683,color:#379683;
    classDef runtime fill:#d0e1f9,stroke:#1d3557,color:#1d3557;
    classDef backend fill:#caf0f8,stroke:#0077b6,color:#0077b6;
    classDef domain fill:#ffe5b4,stroke:#d89f4c,color:#d89f4c;
    classDef storage fill:#ffd6a5,stroke:#ff7f11,color:#ff7f11;
    classDef infra fill:#e0e0e0,stroke:#7a7a7a,color:#7a7a7a;
```
