# michniks2001/voice-ai-hack architecture

> Architecture diagram of the GitHub repository michniks2001/voice-ai-hack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/michniks2001/voice-ai-hack
- Repository: https://github.com/michniks2001/voice-ai-hack

## Overview

##### Project Type and Purpose
- This is a full-stack, voice-enabled conversational AI web application built with Next.js 14 (App Router).
- It provides a chat interface (frontend) that records user speech, transcribes it via ElevenLabs Speech-to-Text (STT), sends the text to OpenAI’s GPT-3.5-turbo (chat API), and then converts the AI’s response back to audio via ElevenLabs Text-to-Speech (TTS).

##### File Structure Analysis
- Top-level:
- app/            ← Next.js App Router directory
– page.tsx      ← Main UI page (React server component pulling in client components)
– layout.tsx    ← Global layout (navigation, styling)
– api/          ← Serverless API routes
- chat/route.ts
- speech-to-text/route.ts
- text-to-speech/route.ts
- components/     ← Reusable UI components (ChatMessage, VoiceInput, LoadingIndicator, plus Shadcn UI primitives)
- hooks/          ← Client hooks (useVoiceRecording.ts)
- lib/            ← Shared utilities (lib/utils.ts)
- public/         ← Static assets
- styles & config (globals.css, tailwind/postcss configs, eslint.config, tsconfig)
- Key patterns:
- Single monolithic codebase with Next.js server+client components.
- API layer under app/api handling integration with external AI services.
- Client-side voice capture (Web Audio API) via a custom hook.

##### README Insights
- Confirms tech stack: Next.js, React, TypeScript, Tailwind CSS, Shadcn UI, OpenAI GPT-3.5, ElevenLabs STT/TTS, Web Audio API.
- Describes API endpoints and high-level flow:
POST /api/speech-to-text → ElevenLabs STT
POST /api/chat → OpenAI GPT
POST /api/text-to-speech → ElevenLabs TTS

##### Main Components
a. Frontend (Client Browser)
- UI Pages & Components
- Web Audio API (voice capture & playback)
- Custom React Hook: useVoiceRecording
b. Backend (Next.js Serverless Functions)
- /api/speech-to-text (ElevenLabs STT integration)
- /api/chat (OpenAI GPT-3.5 integration, system prompt for Barnaby)
- /api/text-to-speech (ElevenLabs TTS integration)
c. External Services
- ElevenLabs Speech-to-Text API
- OpenAI Chat API (GPT-3.5-turbo)
- ElevenLabs Text-to-Speech API

##### Interactions and Data Flow
1) User clicks “Start Recording” → Web Audio API begins capturing audio.
2) User clicks “Stop Recording” → Hook returns audio Blob.
3) Frontend POSTs Blob to /api/speech-to-text.
4) Next.js route.ts calls ElevenLabs STT → returns transcript.
5) Frontend receives transcript → displays it, then POSTs it along with chat history to /api/chat.
6) Server calls OpenAI GPT with system prompt + history → returns AI message.
7) Frontend displays AI text → POSTs AI text to /api/text-to-speech.
8) Server calls ElevenLabs TTS → returns audio URL/bytes.
9) Frontend plays audio via Web Audio API.

##### Architectural Patterns & Principles
- Separation of concerns: UI vs. API vs. external service integration.
- Serverless functions for each third-party integration (STT, Chat, TTS).
- Single-page React client with server components for static content.
- Hook-based encapsulation of browser APIs.

##### Essential Elements to Capture
- Voice capture layer (Web Audio API + useVoiceRecording).
- Next.js API routes as serverless functions.
- Three external AI services with their roles.
- Chat history management (passed from client to /api/chat).
- UI update & audio playback loop.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Client Browser"
    UIPage["Main UI Page"]:::frontend
    Layout["Global Layout"]:::frontend
    ChatMsg["ChatMessage Component"]:::frontend
    VoiceInput["VoiceInput Component"]:::frontend
    Loading["LoadingIndicator Component"]:::frontend
    UIButton["UI Button"]:::frontend
    UICard["UI Card"]:::frontend
    UIScroll["UI ScrollArea"]:::frontend
    Hook["useVoiceRecording Hook"]:::frontend
    WebAudio["Web Audio API"]:::frontend
    Utils["Shared Utilities"]:::frontend
  end

  subgraph "Next.js Serverless API"
    STT["/api/speech-to-text"]:::backend
    ChatAPI["/api/chat"]:::backend
    TTS["/api/text-to-speech"]:::backend
  end

  subgraph "External AI Services"
    ElevenSTT["ElevenLabs STT"]:::external
    OpenAI["OpenAI GPT-3.5"]:::external
    ElevenTTS["ElevenLabs TTS"]:::external
  end

  UIPage -->|"1: Start recording"| WebAudio
  WebAudio -->|"2: Audio Blob"| Hook
  Hook -->|"3: POST /api/speech-to-text"| STT
  STT -->|"4: Transcript"| UIPage
  UIPage -->|"5: POST /api/chat"| ChatAPI
  ChatAPI -->|"6: AI message"| UIPage
  UIPage -->|"7: POST /api/text-to-speech"| TTS
  TTS -->|"8: Audio URL/bytes"| UIPage
  UIPage -->|"9: Play audio"| WebAudio

  UIPage --> ChatMsg
  UIPage --> VoiceInput
  UIPage --> Loading
  UIPage --> UIButton
  UIPage --> UICard
  UIPage --> UIScroll
  UIPage --> Utils

  STT --> ElevenSTT
  ChatAPI --> OpenAI
  TTS --> ElevenTTS

  click UIPage "https://github.com/michniks2001/voice-ai-hack/blob/main/app/page.tsx"
  click Layout "https://github.com/michniks2001/voice-ai-hack/blob/main/app/layout.tsx"
  click ChatMsg "https://github.com/michniks2001/voice-ai-hack/blob/main/components/ChatMessage.tsx"
  click VoiceInput "https://github.com/michniks2001/voice-ai-hack/blob/main/components/VoiceInput.tsx"
  click Loading "https://github.com/michniks2001/voice-ai-hack/blob/main/components/LoadingIndicator.tsx"
  click UIButton "https://github.com/michniks2001/voice-ai-hack/blob/main/components/ui/button.tsx"
  click UICard "https://github.com/michniks2001/voice-ai-hack/blob/main/components/ui/card.tsx"
  click UIScroll "https://github.com/michniks2001/voice-ai-hack/blob/main/components/ui/scroll-area.tsx"
  click Hook "https://github.com/michniks2001/voice-ai-hack/blob/main/hooks/useVoiceRecording.ts"
  click Utils "https://github.com/michniks2001/voice-ai-hack/blob/main/lib/utils.ts"
  click STT "https://github.com/michniks2001/voice-ai-hack/blob/main/app/api/speech-to-text/route.ts"
  click ChatAPI "https://github.com/michniks2001/voice-ai-hack/blob/main/app/api/chat/route.ts"
  click TTS "https://github.com/michniks2001/voice-ai-hack/blob/main/app/api/text-to-speech/route.ts"

  classDef frontend fill:#D6EFFF,stroke:#333,stroke-width:1px
  classDef backend fill:#D1FFD6,stroke:#333,stroke-width:1px
  classDef external fill:#FFE4B5,stroke:#333,stroke-width:1px
```
