# isathyam31/polyvoice architecture

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

- Interactive diagram: https://gitdiagram.com/isathyam31/polyvoice
- Repository: https://github.com/isathyam31/polyvoice

## Overview

##### Project type and purpose
- PolyVoice is a single-page, full-stack Python application built with Streamlit.
- It functions as a multilingual voice assistant that:
- Captures user speech via microphone
- Transcribes it (SpeechRecognition + PyAudio)
- Sends text to Google generative AI / Text-to-Speech APIs
- Receives audio output (gTTS / google-api-python-client)
- Plays synthesized speech back to the user

##### File structure
- Top-level files:
- app.py – entry point (Streamlit UI + controller)
- template.py – skeleton or example usage
- setup.py + requirements.txt – packaging and dependencies
- src/helper.py – business logic / wrapper around APIs
- .gitignore, README.md, LICENSE

##### Key insights from README
- Streamlit delivers the UI layer
- helper.py abstracts calls to SpeechRecognition, Google APIs, gTTS
- dotenv for secret management
- External dependencies: google-generativeai, google-api-python-client, gTTS

##### Main components
a. Frontend/UI:
- Streamlit app (app.py)
- Browser client (user interacts via web UI)
b. Audio I/O & Pre-Processing:
- Microphone input → PyAudio → SpeechRecognition module
c. Business Logic Layer:
- helper.py + template.py
- Orchestrates: transcription → API calls → TTS
d. External Services:
- Google Generative AI API (text understanding, responses)
- Google TTS API / gTTS (speech synthesis)
- (Optionally, any REST endpoints via requests)
e. Playback:
- Local audio output using system speaker

##### Relationships & interactions
1. User speaks → Microphone captures audio
2. SpeechRecognition transcribes to text
3. Text is passed to generative AI (if conversational) or downstream logic
4. Generated text is fed to gTTS / Google TTS
5. Synthesized audio is played back to the user
6. Streamlit UI controls user flow and displays any text transcript / status

##### Architectural patterns & design principles
- Layered architecture:
- Presentation (Streamlit)
- Application (helper.py business logic)
- Integration (API clients)
- Single-page app – no separate backend server (app.py contains both UI & controller)
- Dependency injection via dotenv for API keys
- Packaging with setuptools for reusability

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef ui fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef internal fill:#DFFFD0,stroke:#333,stroke-width:1px
    classDef external fill:#FFE6B3,stroke:#333,stroke-width:1px
    classDef hardware fill:#FFF5BA,stroke:#333,stroke-width:1px

    subgraph "Presentation Layer"
        User["User"]:::hardware
        StreamlitUI["Streamlit UI"]:::ui
    end

    subgraph "Application Layer"
        SpeechRec["SpeechRecognition & PyAudio"]:::internal
        BusinessLogic["Business Logic"]:::internal
        Dotenv["dotenv (API keys)"]:::internal
        Template["Template Usage"]:::internal
    end

    subgraph "Project Configuration"
        Setup["Packaging Config"]:::internal
        Requirements["Dependencies"]:::internal
        InitModule["Module Init"]:::internal
    end

    subgraph "Infrastructure Layer"
        GoogleAI["Google Generative AI API"]:::external
        GoogleTTS["Google TTS / gTTS"]:::external
        Playback["Audio Playback (Speakers)"]:::hardware
        Microphone["Microphone"]:::hardware
    end

    User -->|"voice input"| Microphone
    Microphone -->|".wav stream"| SpeechRec
    SpeechRec -->|"text"| StreamlitUI
    StreamlitUI -->|"invoke processing"| BusinessLogic
    BusinessLogic -->|"loads keys"| Dotenv
    BusinessLogic -->|"text request"| GoogleAI
    GoogleAI -->|"text response"| BusinessLogic
    BusinessLogic -->|"text to synth"| GoogleTTS
    GoogleTTS -->|"MP3 bytes"| BusinessLogic
    BusinessLogic -->|"audio stream"| Playback
    Playback -->|"playback"| User
    BusinessLogic -->|"text + status"| StreamlitUI

    click StreamlitUI "https://github.com/isathyam31/polyvoice/blob/main/app.py"
    click BusinessLogic "https://github.com/isathyam31/polyvoice/blob/main/src/helper.py"
    click Template "https://github.com/isathyam31/polyvoice/blob/main/template.py"
    click Setup "https://github.com/isathyam31/polyvoice/blob/main/setup.py"
    click Requirements "https://github.com/isathyam31/polyvoice/blob/main/requirements.txt"
    click InitModule "https://github.com/isathyam31/polyvoice/blob/main/src/__init__.py"
```
