# hackbalam/goyoelevenlabs architecture

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

## Overview

##### Project type and purpose
- This is a single-page full-stack-style frontend application built with React, TypeScript & Vite. It acts as a voice-driven crypto wallet assistant (“Goyo”) leveraging the ElevenLabs voice/LLM API and a client-side wallet connector (e.g., WalletConnect).
- Its two main use cases are TRANSFER (sending crypto) and EXCHANGE (swapping tokens) via voice commands.

##### File structure
- Top level:
- package.json / vite.config.ts / tsconfig*.json → build & compile config
- index.html / public → static host page
- src/:
- main.tsx → app entry point
- App.tsx, pages/ (HomePage, ContactsPage, DebugPage) → routing & high-level pages
- components/ → UI building blocks (ActionButtonList, ContactsManager, MicrophoneAnimation, etc.)
- hooks/ (useContacts) → custom React hooks for stateful logic
- utils/ (contactsStorage) → localStorage wrapper for contacts
- config/ → environment & ElevenLabs agent configuration
- conversation.tsx → orchestration of voice interaction & ElevenLabs agent
- types/ → TypeScript type definitions

##### README for insights
- Calls out ElevenLabs React SDK, environment variables (VITE_PROJECT_ID, agentID)
- Describes the voice-assistant flow: initial greeting, system prompts, dynamic variables
- Defines the two tool actions (transfer, exchange) and binding to ‘actionHandler’

##### Main components & their relationships
a. UI Layer (React SPA)
- Pages & Components
- MicrophoneAnimation & input capture
- ActionButtonList to trigger actions manually
b. Voice/LLM Layer
- ElevenLabs React SDK (STT/TTS)
- conversation.tsx orchestrates sendAudio → ElevenLabs → receiveResponse
- actionHandler callback that interprets LLM tool instructions
c. Wallet Layer
- Wallet connector (e.g., WalletConnect or Web3 provider invoked via actionHandler)
- External blockchain network
d. Local Storage
- contactsStorage via utils and useContacts hook
e. Configuration & Environment
- VITE_PROJECT_ID, agentID held in config/index.tsx

##### Architectural patterns & technologies
- Component-based UI (React)
- Single-page routing (React Router or custom)
- Hook-based state management (useContacts, local state in pages/components)
- External service orchestration (ElevenLabs LLM agent as a “tool” pattern)
- Client-side only—no backend microservices

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        MainEntry["main.tsx"]:::frontend
        AppComp["App.tsx"]:::frontend
        subgraph "Routing Pages"
            direction TB
            HomePage["HomePage"]:::frontend
            ContactsPage["ContactsPage"]:::frontend
            DebugPage["DebugPage"]:::frontend
        end
        subgraph "UI Components"
            direction TB
            ActionButtonList["ActionButtonList"]:::frontend
            ContactsManager["ContactsManager"]:::frontend
            MicrophoneAnimation["MicrophoneAnimation"]:::frontend
            InfoList["InfoList"]:::frontend
            Navigation["Navigation"]:::frontend
        end
    end

    %% Voice/LLM Layer
    subgraph "Voice/LLM Layer"
        direction TB
        Conversation["conversation.tsx"]:::logic
        ElevenLabsSDK["ElevenLabs React SDK"]:::external
    end

    %% Wallet Layer
    subgraph "Wallet Layer"
        direction TB
        WalletProvider["WalletConnect Provider"]:::external
        Blockchain["Blockchain Network"]:::external
    end

    %% Storage Layer
    subgraph "Local Storage"
        direction TB
        UseContacts["useContacts"]:::logic
        ContactsStorage["contactsStorage"]:::storage
    end

    %% Config & Types
    subgraph "Configuration & Types"
        direction TB
        ConfigIndex["config/index.tsx"]:::logic
        ViteEnv["vite-env.d.ts"]:::logic
        ContactsTypes["contacts.ts"]:::logic
    end

    %% Assets & Build
    subgraph "Static & Build"
        direction TB
        PublicFolder["public/"]:::storage
        Assets["assets/"]:::storage
        ViteConfig["vite.config.ts"]:::logic
        TSConfigs["tsconfig*.json"]:::logic
        TailwindConfig["tailwind.config.js"]:::logic
    end

    %% Connections
    MainEntry -->|"boots App"| AppComp
    AppComp -->|"renders"| HomePage
    AppComp -->|"renders"| ContactsPage
    AppComp -->|"renders"| DebugPage
    AppComp --> Navigation
    AppComp --> ActionButtonList
    AppComp --> MicrophoneAnimation

    MicrophoneAnimation -->|"audio stream"| Conversation
    ActionButtonList -->|"manual trigger"| Conversation

    Conversation -->|"calls"| ElevenLabsSDK
    ElevenLabsSDK -->|"returns response"| Conversation
    Conversation -->|"actionHandler"| WalletProvider
    WalletProvider -->|"JSON-RPC"| Blockchain

    ContactsPage --> UseContacts
    UseContacts --> ContactsStorage

    ConfigIndex --> Conversation
    ViteEnv --> Conversation

    HomePage --> PublicFolder
    AppComp --> Assets

    ViteConfig --> MainEntry
    TSConfigs --> MainEntry
    TailwindConfig --> MainEntry

    %% Click events
    click AppComp "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/App.tsx"
    click MainEntry "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/main.tsx"
    click HomePage "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/pages/HomePage.tsx"
    click ContactsPage "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/pages/ContactsPage.tsx"
    click DebugPage "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/pages/DebugPage.tsx"
    click ActionButtonList "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/components/ActionButtonList.tsx"
    click ContactsManager "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/components/ContactsManager.tsx"
    click MicrophoneAnimation "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/components/MicrophoneAnimation.tsx"
    click InfoList "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/components/InfoList.tsx"
    click Navigation "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/components/Navigation.tsx"
    click Conversation "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/conversation.tsx"
    click ConfigIndex "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/config/index.tsx"
    click ViteEnv "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/vite-env.d.ts"
    click UseContacts "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/hooks/useContacts.ts"
    click ContactsStorage "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/utils/contactsStorage.ts"
    click ContactsTypes "https://github.com/hackbalam/goyoelevenlabs/blob/main/src/types/contacts.ts"
    click PublicFolder "https://github.com/hackbalam/goyoelevenlabs/tree/main/public/"
    click Assets "https://github.com/hackbalam/goyoelevenlabs/tree/main/src/assets/"
    click ViteConfig "https://github.com/hackbalam/goyoelevenlabs/blob/main/vite.config.ts"
    click TSConfigs "https://github.com/hackbalam/goyoelevenlabs/blob/main/tsconfig.json"
    click TailwindConfig "https://github.com/hackbalam/goyoelevenlabs/blob/main/tailwind.config.js"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#1976D2,color:#0D47A1,stroke-width:1px;
    classDef logic fill:#E8F5E9,stroke:#388E3C,color:#1B5E20,stroke-width:1px;
    classDef external fill:#FFF3E0,stroke:#F57C00,color:#E65100,stroke-width:1px;
    classDef storage fill:#ECEFF1,stroke:#455A64,color:#263238,stroke-width:1px;
```
