# fatma-moanes/voice-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/fatma-moanes/voice-assistant
- Repository: https://github.com/fatma-moanes/voice-assistant

## Overview

##### Main Components

A. Frontend Layer:
- Streamlit UI Components (from app/components/)
- Chat Display
- Controls
- Sidebar
- Custom CSS

B. Core Application Layer:
- Configuration Management
- Database Interface
- Agent System

C. Service Layer:
- Speech-to-Text Services
- Text-to-Speech Services
- LLM Integration

D. External Services:
- MongoDB
- AWS Services (Polly, Transcribe)
- LLM Providers (GROQ/OpenAI)
- Whisper Streaming

**[User Interface Layer]**
- ↕️
**[Core Application Layer]**
- ↕️
**[Service Layer]**
- ↕️
**[External Services Layer]**

##### Component Relationships

- User Interface → Speech Services (audio input/output)
- Speech Services → External APIs (AWS, Whisper)
- Core Agent → LLM Providers
- Core Agent → Database
- Service Layer → External Services

##### Detailed Component Breakdown

Frontend Layer:
**[Chat Display] ← → [Controls]**
- ↕️
**[Sidebar] ← → [Audio Controls]**

Core Layer:
**[Config Manager] → [Agent System]**
- ↓
**[Database Interface]**

Service Layer:
**[STT Service] → [Agent Tools]**
**[TTS Service] ← [Chatbot]**

##### Additional Elements

Supporting components:
- Configuration files (config.yml)
- Environment variables
- Logging system
- Debug mode components

##### Technical Details to Highlight

- MongoDB integration for appointment data
- Multiple STT options (Whisper, AWS, Deepgram)
- LLM provider flexibility (GROQ/OpenAI)
- Bilingual support architecture
- Real-time audio processing pipeline

##### The separation of concerns between UI, core logic, and services

This system design should clearly communicate how the voice assistant processes user input, manages conversations, and integrates with various services while maintaining a clean separation of concerns.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph UI["Frontend Layer"]
        CD["Chat Display"]
        CT["Controls"]
        SB["Sidebar"]
        CS["Custom CSS"]
    end

    subgraph Core["Core Application Layer"]
        MA["Main Application"]
        CM["Configuration Management"]
        DI["Database Interface"]
    end

    subgraph Agent["Agent Layer"]
        AT["Agent Tools"]
        CB["Conversation Management"]
        AP["Agent Prompts"]
    end

    subgraph Services["Services Layer"]
        STT["Speech-to-Text Service"]
        TTS["Text-to-Speech Service"]
        WS["Whisper Streaming"]
        WSV["Whisper Server"]
        VAD["Voice Activity Detection"]
    end

    subgraph Utils["Utility Layer"]
        AC["Audio Control"]
        LOG["Logger"]
        DBC["Database Creation"]
    end

    subgraph External["External Services"]
        DB[(MongoDB)]
        AWS["AWS Services"]
        LLM["GROQ/OpenAI"]
    end

    %% Relationships
    UI --> MA
    MA --> Core
    Core --> Agent
    Agent --> Services
    Services --> External

    %% Detailed connections
    AC --> STT
    STT --> WS
    WS --> WSV
    WSV --> VAD
    STT --> AWS
    TTS --> AWS
    CB --> LLM
    DI --> DB
    DBC --> DB

    %% Click events
    click CD "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/components/chat_display.py"
    click CT "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/components/controls.py"
    click SB "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/components/sidebar.py"
    click CS "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/components/custom_css.py"
    click CM "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/core/config.py"
    click DI "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/core/database.py"
    click MA "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/streamlit_app_streaming.py"
    click AT "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/agent/agent_tools.py"
    click CB "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/agent/chatbot.py"
    click AP "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/agent/prompts.py"
    click STT "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/services/stt.py"
    click TTS "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/services/tts.py"
    click WS "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/services/whisper_streaming_repo/whisper_online.py"
    click WSV "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/services/whisper_streaming_repo/whisper_online_server.py"
    click VAD "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/services/whisper_streaming_repo/silero_vad_iterator.py"
    click AC "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/utils/audio_control.py"
    click LOG "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/utils/logger.py"
    click DBC "https://github.com/Fatma-Moanes/voice-assistant/blob/master/app/utils/create_db.py"

    %% Styling
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef core fill:#2ecc71,stroke:#27ae60,color:white
    classDef agent fill:#f1c40f,stroke:#f39c12,color:black
    classDef services fill:#9b59b6,stroke:#8e44ad,color:white
    classDef utils fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef external fill:#e74c3c,stroke:#c0392b,color:white

    class CD,CT,SB,CS frontend
    class MA,CM,DI core
    class AT,CB,AP agent
    class STT,TTS,WS,WSV,VAD services
    class AC,LOG,DBC utils
    class DB,AWS,LLM external
```
