# deepgram-devs/deepgram-ai-agent-demo architecture

> Architecture diagram of the GitHub repository deepgram-devs/deepgram-ai-agent-demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deepgram-devs/deepgram-ai-agent-demo
- Repository: https://github.com/deepgram-devs/deepgram-ai-agent-demo

## Overview

##### Component Details

a. Frontend Layer (React/Next.js):
- Conversation Components (ConversationAgent, ChatBubble, MessageAudio)
- Control Components (AgentControls)
- A "Context Providers" section showing:
- WebSocketContext
- AuthContext
- ToastContext

b. API Layer (Next.js API Routes):
- /api/authenticate
- /api/generate-token
- /api/verify-token
- Middleware authentication flow

c. External Services Layer:
- Deepgram Services
- Speech-to-Text (Streaming)
- Text-to-Speech (Aura)
- OpenAI
- LLM (Chat Completions API)

d. WebSocket Layer:
- A vertical container showing WebSocket connection flow
- Real-time audio streaming pathway

##### Connection Flows

- Frontend → API (REST calls)
- Frontend ↔ WebSocket (Bidirectional)
- API → External Services
- WebSocket → Deepgram (Audio streaming)

##### Additional Elements

- Configuration (deepgram.toml, .env.local)
- Authentication flow
- Error handling paths

##### Technical Stack Indicators

Labels for key technologies:
- Next.js
- TypeScript
- Tailwind CSS
- WebSocket
- JWT Authentication

##### Real-time nature of the application by highlighting
- WebSocket connections for live audio
- Streaming speech-to-text conversion
- Bidirectional communication flows

##### Security layers
- JWT token flow
- API route protection
- Authentication middleware

##### Error handling paths
- Connection failures
- Service unavailability
- Token expiration

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Frontend
        FC[Frontend Components]
        CC[Conversation Components]
        CTRL[Control Components]
        UI[UI Components]
        CP[Context Providers]

        FC --> CC
        FC --> CTRL
        FC --> UI
        FC --> CP

        subgraph "Conversation Components"
            CA["ConversationAgent"]:::component
            CB["ChatBubble"]:::component
            MA["MessageAudio"]:::component
            RB["RightBubble"]:::component
        end

        subgraph "Control Components"
            AC["AgentControls"]:::component
            IL["InitialLoadAgent"]:::component
        end

        subgraph "UI Components"
            UA["UserAvatar"]:::component
            MH["MessageHeader"]:::component
            IC["Icons"]:::component
        end

        subgraph "Context Providers"
            WC["WebSocketContext"]:::component
            AuC["AuthContext"]:::component
            TC["ToastContext"]:::component
        end
    end

    subgraph API
        AR["API Routes"]:::api

        Auth["/api/authenticate"]:::api
        GT["/api/generate-token"]:::api
        VT["/api/verify-token"]:::api

        AR --> Auth
        AR --> GT
        AR --> VT

        AM["Auth Middleware"]:::security
        JWT["JWT Handler"]:::security
    end

    subgraph External
        DG["Deepgram Services"]
        STT["Speech-to-Text"]
        TTS["Text-to-Speech"]
        
        DG --> STT
        DG --> TTS

        OAI["OpenAI LLM"]
    end

    subgraph WebSocket
        WS["WebSocket Server"]
        AS["Audio Streaming"]
        RT["Real-time Processing"]

        WS --> AS
        AS --> RT
    end

    subgraph Config
        CF["Configuration Files"]:::config
        ENV["Environment Variables"]:::config
        CONST["Constants"]:::config
    end

    Frontend --> API
    Frontend <--> WebSocket
    API --> External
    WebSocket --> DG
    
    %% Click Events
    click CA "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/components/ConversationAgent.tsx"
    click CB "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/components/ChatBubble.tsx"
    click MA "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/components/MessageAudio.tsx"
    click RB "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/components/RightBubble.tsx"
    click AC "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/components/AgentControls.tsx"
    click IL "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/components/InitialLoadAgent.tsx"
    click UA "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/components/UserAvatar.tsx"
    click MH "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/components/MessageHeader.tsx"
    click IC "https://github.com/deepgram-devs/deepgram-ai-agent-demo/tree/main/app/components/icons/"
    click WC "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/context/WebSocketContext.tsx"
    click AuC "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/context/Auth.tsx"
    click TC "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/context/Toast.tsx"
    click Auth "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/api/authenticate/route.ts"
    click GT "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/api/generate-token/route.ts"
    click VT "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/api/verify-token/route.ts"
    click AM "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/lib/authMiddleware.ts"
    click JWT "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/lib/jwt.ts"
    click CF "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/config/index.ts"
    click CONST "https://github.com/deepgram-devs/deepgram-ai-agent-demo/blob/main/app/lib/constants.ts"

    classDef component fill:#3498db,stroke:#2980b9,color:white
    classDef api fill:#2ecc71,stroke:#27ae60,color:white
    classDef security fill:#e74c3c,stroke:#c0392b,color:white
    classDef config fill:#95a5a6,stroke:#7f8c8d,color:white

    %% Legend
    subgraph Legend
        L1["Frontend Component"]:::component
        L2["API Endpoint"]:::api
        L3["Security Component"]:::security
        L4["Configuration"]:::config
    end
```
