# shauryasawai/voice_agent architecture

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

- Interactive diagram: https://gitdiagram.com/shauryasawai/voice_agent
- Repository: https://github.com/shauryasawai/voice_agent

## Overview

##### Project type and purpose
- This is a full-stack web application built on Django that provides a real-time voice AI agent.
- It integrates Google Cloud Speech-to-Text (STT), OpenAI GPT (LLM), and Google Cloud Text-to-Speech (TTS) to turn user speech into AI responses and play them back as audio.

##### File structure
- Top‐level:
- manage.py, setup.py, requirements.txt, vercel.json – deployment and dependency config
- project/ – Django project settings (settings.py, urls.py, asgi.py, wsgi.py)
- base/ – Django app containing:
– views.py + urls.py (controllers/route handlers)
– api_integration.py (layer for calling external APIs)
– templates/base/index.html (UI)
– tests.py, migrations/ (Django testing & schema)
- staticfiles_build/ – compiled static assets for production
- Patterns:
- MVC structure in Django
- Dedicated integration module for third-party calls (api_integration.py)
- Single monolith that acts as an orchestration service for external microservices

##### README for additional insights
- Core workflow:
User Voice Input → Django backend (POST /process-voice) → STT API → GPT API → TTS API → Django → Frontend audio playback
- Key technologies: Django 4.2, Python 3.8+, Web Audio API, JavaScript, Google Cloud APIs, OpenAI GPT
- External dependencies and configuration via .env or direct constants in api_integration.py

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        UI["UI: index.html"]:::frontend
        StaticAssets["Static Assets (JS/CSS)"]:::frontend
        AudioRecorder["AudioRecorder (Web Audio API)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Django)" 
        direction TB
        manage["manage.py"]:::backend
        subgraph "Project Configuration"
            direction TB
            settings["settings.py"]:::backend
            asgi["asgi.py"]:::backend
            wsgi["wsgi.py"]:::backend
        end
        subgraph "URL Routing"
            direction TB
            projectUrls["project/urls.py"]:::backend
            baseUrls["base/urls.py"]:::backend
        end
        views["Django View: process_voice"]:::backend
        apiInt["API Integration Layer"]:::backend
    end

    %% External Services Layer
    subgraph "External Services" 
        direction TB
        STT["Google Cloud Speech-to-Text"]:::service
        GPT["OpenAI GPT API"]:::service
        TTS["Google Cloud Text-to-Speech"]:::service
    end

    %% Configuration Layer
    subgraph "Deployment & Config" 
        direction TB
        requirements["requirements.txt"]:::config
        setupPy["setup.py"]:::config
        vercel["vercel.json"]:::config
    end

    %% Data Flow
    AudioRecorder -->|"1. startRecording()"| UI
    UI -->|"2. POST /process-voice (Audio Blob)"| projectUrls
    projectUrls --> baseUrls
    baseUrls --> views
    views -->|"3. WAV audio →"| apiInt
    apiInt -->|"4. transcript →"| GPT
    apiInt -->|"4. WAV audio →"| STT
    STT -->|"5. transcript ←"| apiInt
    apiInt -->|"6. text →"| GPT
    GPT -->|"7. text response ←"| apiInt
    apiInt -->|"8. text →"| TTS
    TTS -->|"9. MP3 audio ←"| apiInt
    apiInt -->|"10. JSON (transcript+audio)"| views
    views -->|"11. JSON response"| UI
    UI -->|"12. playAudio()"| AudioRecorder

    %% Config dependency
    requirements -->|provides deps| apiInt
    setupPy -->|provides package| apiInt
    vercel -->|deployment config| manage

    %% Click Events
    click UI "https://github.com/shauryasawai/voice_agent/blob/main/base/templates/base/index.html"
    click StaticAssets "https://github.com/shauryasawai/voice_agent/tree/main/staticfiles_build/"
    click projectUrls "https://github.com/shauryasawai/voice_agent/blob/main/project/urls.py"
    click baseUrls "https://github.com/shauryasawai/voice_agent/blob/main/base/urls.py"
    click views "https://github.com/shauryasawai/voice_agent/blob/main/base/views.py"
    click apiInt "https://github.com/shauryasawai/voice_agent/blob/main/base/api_integration.py"
    click settings "https://github.com/shauryasawai/voice_agent/blob/main/project/settings.py"
    click asgi "https://github.com/shauryasawai/voice_agent/blob/main/project/asgi.py"
    click wsgi "https://github.com/shauryasawai/voice_agent/blob/main/project/wsgi.py"
    click manage "https://github.com/shauryasawai/voice_agent/blob/main/manage.py"
    click requirements "https://github.com/shauryasawai/voice_agent/blob/main/requirements.txt"
    click setupPy "https://github.com/shauryasawai/voice_agent/blob/main/setup.py"
    click vercel "https://github.com/shauryasawai/voice_agent/blob/main/vercel.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#333,stroke-width:1px
    classDef service fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef config fill:#f8d7da,stroke:#333,stroke-width:1px
```
