# pennyroyaltea/gibberlink architecture

> Architecture diagram of the GitHub repository pennyroyaltea/gibberlink, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pennyroyaltea/gibberlink
- Repository: https://github.com/pennyroyaltea/gibberlink

## Overview

##### Project type and purpose
- This is a full-stack hackathon demo built with Next.js (App Router).
- Purpose: expose a browser UI where two AI agents (via ElevenLabs) chat about booking a hotel and switch into a data-over-sound protocol (ggwave) when they detect another AI. The demo uses WebAssembly (ggwave.wasm), custom API routes, and front-end components to orchestrate this.

##### File structure
- Top-level “hackathon_demo” folder contains:
- next.config.ts, tsconfig.json, tailwind.config.ts, package.json/lock → build & tooling
- public/ggwave → static JS/WASM for audio codec
- src/app → React entrypoints, layouts, global styles, API routes under `/api/chat` and `/api/signed-url`
- src/components → UI building blocks (AudioMessenger.tsx, ConvAI.tsx, Code.tsx, etc.)
- src/services → wrappers for chat & audio logic (AudioMessengerService.ts)
- src/utils & src/lib → shared helper functions and types

##### README
- Describes demo flow: two independent ElevenLabs AI agents converse, switch to ggwave for AI-to-AI.
- Mentions ggwave library (data-over-sound), ElevenLabs conversational API.

a. Main Components
- Frontend (Browser clients)
– React UI (Next.js pages & components)
– Audio capture/playback & ggwave codec (ggwave.js + ggwave.wasm)
- Next.js Server (API layer)
– /api/chat route: orchestrates message exchange between AI agents (text ↔ ElevenLabs)
– /api/signed-url route: provides pre-signed URLs (e.g., S3) for uploading/serving encoded audio blobs
– AudioMessengerService: server-side logic to manage audio message state
- External Services
– ElevenLabs Conversational AI & TTS API
– (Optional) Cloud storage for audio blobs (S3 or similar)
b. Relationships & Interactions
1. User’s browser captures audio → passes raw PCM to ggwave codec → produces encoded data blob.
2. Encoded blob uploaded via signed URL → stored in cloud storage.
3. Browser calls /api/chat with text or audio reference → Next.js server forwards to ElevenLabs → receives text response & TTS audio.
4. Server returns text + audio URL to client → browser fetches audio file or raw blob → ggwave decodes and plays.
5. Cycle repeats for each chat turn.
c. Architectural Patterns & Principles
- Jamstack style: separation of UI (static + dynamic React) & serverless functions (Next.js API routes).
- Componentized UI (Atomic design in src/components/ui).
- Service layer (AudioMessengerService) to abstract external API calls.
- Use of WebAssembly for performance-critical audio codec.
d. Core Technologies
- Next.js (React, App Router)
- Tailwind CSS for styling
- WebAssembly (ggwave.wasm + JS shim)
- ElevenLabs API (HTTP)
- Cloud storage (signed URLs, e.g., AWS S3)
- TypeScript, ts-node

##### Detail
- Every major component: React layout, API modules, service layer, static assets.
- Don’t omit the ggwave WASM module.
- Both text & audio flows separately or in parallel lanes for clarity.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser Client Layer
    subgraph "Browser Client" 
        direction TB
        Layout["layout.tsx"]:::ui
        Page["page.tsx"]:::ui
        Styles["globals.css"]:::ui
        subgraph "UI Components"
            direction TB
            AudioMessengerCmp["AudioMessenger.tsx"]:::ui
            ConvAICmp["ConvAI.tsx"]:::ui
            CodeCmp["Code.tsx"]:::ui
            BGWaveCmp["background-wave.tsx"]:::ui
            LogosCmp["logos.tsx"]:::ui
            ButtonUI["button.tsx"]:::ui
            CardUI["card.tsx"]:::ui
            RadioUI["radio-group.tsx"]:::ui
        end
        subgraph "WebAssembly Codec"
            direction TB
            GgwaveJS["ggwave.js"]:::static
            GgwaveWASM["ggwave.wasm"]:::static
        end
        AudioUtils["audioUtils.ts"]:::util
    end

    %% API Server Layer
    subgraph "Next.js API Server"
        direction TB
        ChatRoute["/api/chat\nroute.ts"]:::api
        GroqRoute["_groq_groute.ts"]:::api
        SignedURL["/api/signed-url\nroute.ts"]:::api
        AudioService["AudioMessengerService.ts"]:::service
        Helpers["utils.ts"]:::util
        Types["ggwave.d.ts"]:::util
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ElevenLabs["ElevenLabs AI & TTS"]:::external
        Storage[(Cloud Storage)]:::storage
    end

    %% Configuration & Tooling
    subgraph "Config & Tooling"
        direction TB
        NextConfig["next.config.ts"]:::config
        TSConfig["tsconfig.json"]:::config
        TailwindConfig["tailwind.config.ts"]:::config
        PackageJSON["package.json"]:::config
        PackageLock["package-lock.json"]:::config
        EnvFile["example.env"]:::config
    end

    %% Data Flows
    Layout -->|imports| AudioMessengerCmp
    Page -->|uses| ConvAICmp
    ConvAICmp -->|renders| AudioMessengerCmp
    AudioMessengerCmp -->|calls| AudioUtils
    AudioMessengerCmp -->|loads| GgwaveJS
    GgwaveJS -->|loads| GgwaveWASM

    %% Audio Flow: Capture to Storage
    AudioMessengerCmp -->|"capture PCM"| AudioUtils
    AudioUtils -->|"encode"| GgwaveJS
    GgwaveJS -->|"encoded blob"| SignedURL
    SignedURL -->|"upload blob"| Storage

    %% Chat Flow
    AudioMessengerCmp -->|"POST /api/chat\n(text or audio ref)"| ChatRoute
    ChatRoute -->|"forward text"| ElevenLabs
    ElevenLabs -->|"text response & TTS URL"| ChatRoute
    ChatRoute -->|"response"| AudioMessengerCmp
    AudioMessengerCmp -->|"fetch audio"| Storage
    AudioMessengerCmp -->|"decode"| GgwaveJS
    AudioMessengerCmp -->|"playback"| AudioUtils

    %% Service orchestration
    ChatRoute -->|uses| AudioService
    SignedURL -->|uses| AudioService
    AudioService -->|uses| Helpers
    AudioService -->|types| Types

    %% Config usage
    ChatRoute -->|reads| EnvFile
    SignedURL -->|reads| EnvFile

    %% Click Events
    click Layout "https://github.com/pennyroyaltea/gibberlink/blob/main/src/app/layout.tsx"
    click Page "https://github.com/pennyroyaltea/gibberlink/blob/main/src/app/page.tsx"
    click Styles "https://github.com/pennyroyaltea/gibberlink/blob/main/src/app/globals.css"
    click AudioMessengerCmp "https://github.com/pennyroyaltea/gibberlink/blob/main/src/components/AudioMessenger.tsx"
    click ConvAICmp "https://github.com/pennyroyaltea/gibberlink/blob/main/src/components/ConvAI.tsx"
    click CodeCmp "https://github.com/pennyroyaltea/gibberlink/blob/main/src/components/Code.tsx"
    click BGWaveCmp "https://github.com/pennyroyaltea/gibberlink/blob/main/src/components/background-wave.tsx"
    click LogosCmp "https://github.com/pennyroyaltea/gibberlink/blob/main/src/components/logos.tsx"
    click ButtonUI "https://github.com/pennyroyaltea/gibberlink/blob/main/src/components/ui/button.tsx"
    click CardUI "https://github.com/pennyroyaltea/gibberlink/blob/main/src/components/ui/card.tsx"
    click RadioUI "https://github.com/pennyroyaltea/gibberlink/blob/main/src/components/ui/radio-group.tsx"
    click GgwaveJS "https://github.com/pennyroyaltea/gibberlink/blob/main/public/ggwave/ggwave.js"
    click GgwaveWASM "https://github.com/pennyroyaltea/gibberlink/blob/main/public/ggwave/ggwave.wasm"
    click AudioUtils "https://github.com/pennyroyaltea/gibberlink/blob/main/src/utils/audioUtils.ts"
    click AudioService "https://github.com/pennyroyaltea/gibberlink/blob/main/src/services/AudioMessengerService.ts"
    click ChatRoute "https://github.com/pennyroyaltea/gibberlink/blob/main/src/app/api/chat/route.ts"
    click GroqRoute "https://github.com/pennyroyaltea/gibberlink/blob/main/src/app/api/chat/_groq_groute.ts"
    click SignedURL "https://github.com/pennyroyaltea/gibberlink/blob/main/src/app/api/signed-url/route.ts"
    click Helpers "https://github.com/pennyroyaltea/gibberlink/blob/main/src/lib/utils.ts"
    click Types "https://github.com/pennyroyaltea/gibberlink/blob/main/src/types/ggwave.d.ts"
    click NextConfig "https://github.com/pennyroyaltea/gibberlink/blob/main/next.config.ts"
    click TSConfig "https://github.com/pennyroyaltea/gibberlink/blob/main/tsconfig.json"
    click TailwindConfig "https://github.com/pennyroyaltea/gibberlink/blob/main/tailwind.config.ts"
    click PackageJSON "https://github.com/pennyroyaltea/gibberlink/blob/main/package.json"
    click PackageLock "https://github.com/pennyroyaltea/gibberlink/blob/main/package-lock.json"
    click EnvFile "https://github.com/pennyroyaltea/gibberlink/blob/main/hackathon_demo/example.env"

    %% Styles
    classDef ui fill:#D0E7FF,stroke:#0B69A3,color:#0B69A3
    classDef static fill:#F0E68C,stroke:#B8860B,color:#B8860B
    classDef util fill:#EAD1DC,stroke:#C2185B,color:#C2185B
    classDef api fill:#C8E6C9,stroke:#388E3C,color:#388E3C
    classDef service fill:#DCEDC8,stroke:#689F38,color:#689F38
    classDef external fill:#FFE0B2,stroke:#FF8F00,color:#FF8F00
    classDef storage fill:#FFF9C4,stroke:#F9A825,color:#F9A825
    classDef config fill:#EEEEEE,stroke:#9E9E9E,color:#616161
```
