# umanggoel21/liquoa-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/umanggoel21/liquoa-chatbot
- Repository: https://github.com/umanggoel21/liquoa-chatbot

## Overview

##### Project Type and Purpose
- Lynqo AI Assistant is a full-stack, voice-enabled AI chatbot.
- It provides both a Streamlit-based web UI and a command-line interface for multilingual, real-time conversation.

##### File Structure Analysis
- Top-level:
- .devcontainer/ – development container settings
- assets/ – static images or UI assets
- backend/ – all Python modules powering UI, voice/text I/O, AI integration
- requirements.txt – dependency list
- backend/ organizes core functional areas:
- frontend.py – Streamlit web server (UI layer)
- main.py – CLI entry point (UI layer)
- listen.py – microphone capture + speech-to-text (I/O layer)
- detect_language.py – language detection (processing layer)
- translate.py & translate_back.py – bidirectional translation (processing layer)
- groq_chat.py – calls Groq AI API (business logic layer)
- speak.py – text-to-speech (I/O layer)
- saved_audio/ – temporary audio files (storage layer)

##### External Dependencies (from README & requirements.txt)
- groq API for AI chat processing
- gTTS for TTS
- SpeechRecognition (and PyAudio) for speech input
- langdetect for language ID
- googletrans for translation
- Streamlit for web UI

##### Main Components and Their Relationships
a. User Interfaces
- Browser (Streamlit UI)
- Terminal (CLI)
b. I/O Layer
- listen.py → produces text transcription
- speak.py ← consumes AI response text, outputs audio
c. Processing Layer
- detect_language.py → language code
- translate.py → normalize non-English input to English
- groq_chat.py → sends English prompt to AI, returns English reply
- translate_back.py → convert English reply to user’s language
d. Storage Layer
- saved_audio/ for intermediary WAV/MP3 files
e. External Services
- Groq AI API
- Google Translate API (via googletrans)
- gTTS service

User → [listen.py] → raw_text → [detect_language.py] → lang_code
raw_text + lang_code → [translate.py] → english_text → [groq_chat.py] → response_en
response_en + lang_code → [translate_back.py] → response_user_lang → [speak.py] → audio
UI ← text + audio

##### Architectural Patterns and Principles
- Layered architecture: separate I/O, processing, business logic
- Single-process monolith with clear module boundaries
- Stateless modules except for temporary audio storage
- External-service façade modules (groq_chat, translate, speak)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Presentation Layer"
        Browser["Streamlit Web UI"]:::presentation
        CLI["Command-Line Interface (CLI)"]:::presentation
    end

    subgraph "I/O Layer"
        Listen["Speech-to-Text Capture"]:::io
        Speak["Text-to-Speech Output"]:::io
    end

    subgraph "Processing Layer"
        Detect["Language Detection"]:::processing
        subgraph "Translation Service"
            InTrans["Input Translation (to English)"]:::processing
            OutTrans["Output Translation (back to user language)"]:::processing
        end
        AI["AI Chat Business Logic (Groq API)"]:::processing
    end

    subgraph "Storage & External Services"
        SavedAudio["Temporary Audio Files"]:::storage
        GroqAPI["Groq AI API"]:::external
        GoogleTrans["Google Translate API"]:::external
        GTTS["gTTS Service"]:::external
        SR["SpeechRecognition Service"]:::external
    end

    subgraph "Infrastructure"
        DevContainer[".devcontainer"]:::infra
        Assets["assets"]:::infra
        Deps["requirements.txt"]:::infra
    end

    Browser -->|"start capture"| Listen
    CLI -->|"start capture"| Listen
    Listen -->|"raw_text"| Detect
    Detect -->|"lang_code"| InTrans
    Detect -->|"raw_text+lang_code"| InTrans
    InTrans -->|"english_text"| AI
    AI -->|"response_en"| OutTrans
    OutTrans -->|"response_user_lang"| Speak
    Speak -->|"audio stream"| Browser
    Speak -->|"audio stream"| CLI
    Speak -->|"save audio"| SavedAudio

    AI -->|"API call"| GroqAPI
    InTrans -->|"translate call"| GoogleTrans
    OutTrans -->|"translate call"| GoogleTrans
    Speak -->|"TTS call"| GTTS
    Listen -->|"speech recog"| SR

    click Browser "https://github.com/umanggoel21/liquoa-chatbot/blob/master/backend/frontend.py"
    click CLI "https://github.com/umanggoel21/liquoa-chatbot/blob/master/backend/main.py"
    click Listen "https://github.com/umanggoel21/liquoa-chatbot/blob/master/backend/listen.py"
    click Speak "https://github.com/umanggoel21/liquoa-chatbot/blob/master/backend/speak.py"
    click Detect "https://github.com/umanggoel21/liquoa-chatbot/blob/master/backend/detect_language.py"
    click InTrans "https://github.com/umanggoel21/liquoa-chatbot/blob/master/backend/translate.py"
    click AI "https://github.com/umanggoel21/liquoa-chatbot/blob/master/backend/groq_chat.py"
    click OutTrans "https://github.com/umanggoel21/liquoa-chatbot/blob/master/backend/translate_back.py"
    click SavedAudio "https://github.com/umanggoel21/liquoa-chatbot/tree/master/backend/saved_audio/"
    click DevContainer "https://github.com/umanggoel21/liquoa-chatbot/blob/master/.devcontainer/devcontainer.json"
    click Assets "https://github.com/umanggoel21/liquoa-chatbot/tree/master/assets/"
    click Deps "https://github.com/umanggoel21/liquoa-chatbot/blob/master/requirements.txt"

    classDef presentation fill:#bfdfff,stroke:#333,stroke-width:1px;
    classDef io fill:#d0f0c0,stroke:#333,stroke-width:1px;
    classDef processing fill:#f0e68c,stroke:#333,stroke-width:1px;
    classDef storage fill:#ffcccb,stroke:#333,stroke-width:1px;
    classDef external fill:#e6e6fa,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef infra fill:#d3d3d3,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2;
```
