# varunkarnati/vois_ai_assignment architecture

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

- Interactive diagram: https://gitdiagram.com/varunkarnati/vois_ai_assignment
- Repository: https://github.com/varunkarnati/vois_ai_assignment

## Overview

##### Project type and purpose
- This is a full-stack, voice-driven ordering system for restaurants.
- Users speak into a browser UI, the speech is transcribed, sent to an LLM for dialog management, tools apply business logic (CRUD on orders), and results are spoken back.

##### File structure
- Top level:
- public/ – static frontend (index.html + JS/CSS)
- api/index.py – serverless FastAPI entrypoint (Vercel)
- app/main.py – FastAPI app definition, WebSocket routes
- app/utils/ – core modules:
– stt.py & tts.py for speech I/O
– llm.py for LangChain orchestration
– tools.py for order-management logic & file_db
– file_db.py for JSON read/write
– graph_definition.py for dialogue flow definitions
- orders_db.json + order_histories/ – JSON files acting as simple persistent store
- requirements.txt, vercel.json, .github – config and CI

##### README for additional insights
- Backend: FastAPI + WebSockets
- LLM: LangChain + Groq API
- TTS: ElevenLabs
- Database: local JSON
- Deployment: Vercel serverless, static hosting for public/

##### Detail
- Order_histories folder as an archive sink.
- Configuration inputs (.env keys for GROQ_API_KEY, ELEVENLABS_API_KEY).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        Browser["Client Browser UI"]:::browser
    end

    %% Serverless API Layer
    subgraph "Serverless API Layer"
        Gateway["API Gateway\n(api/index.py)"]:::compute
    end

    %% Backend Layer
    subgraph "Backend Layer"
        FastAPI["FastAPI App\n(app/main.py)"]:::compute
        WS["WebSocket /ws/converse"]:::compute
        STT["STT Module\n(app/utils/stt.py)"]:::compute
        LLM["LLM Orchestrator\n(app/utils/llm.py)"]:::compute
        GraphDef["Dialogue Flow Def\n(app/utils/graph_definition.py)"]:::compute
        Tools["Tools Layer\n(app/utils/tools.py)"]:::compute
        FileDB["File DB Helper\n(app/utils/file_db.py)"]:::compute
        TTS["TTS Module\n(app/utils/tts.py)"]:::compute
        OrderStore["Primary JSON Store\n(orders_db.json)"]:::storage
        History["Order Histories\n(order_histories/)"]:::storage
    end

    %% External Services
    subgraph "External Services"
        Groq["Groq API"]:::external
        ElevenLabs["ElevenLabs API"]:::external
    end

    %% Data Flows
    Browser -->|"WebSocket"| Gateway
    Gateway --> FastAPI
    FastAPI --> WS
    WS -->|"audio stream"| STT
    STT -->|"text"| LLM
    GraphDef -.-> LLM
    LLM -->|"LLM call"| Groq
    LLM -->|"invoke tools"| Tools
    Tools --> FileDB
    FileDB --> OrderStore
    Tools -->|"archive"| History
    LLM -->|"response text"| WS
    WS --> TTS
    TTS -->|"TTS request"| ElevenLabs
    ElevenLabs -->|"audio stream"| Browser

    %% Click Events
    click Browser "https://github.com/varunkarnati/vois_ai_assignment/blob/main/public/index.html"
    click Gateway "https://github.com/varunkarnati/vois_ai_assignment/blob/main/api/index.py"
    click FastAPI "https://github.com/varunkarnati/vois_ai_assignment/blob/main/app/main.py"
    click STT "https://github.com/varunkarnati/vois_ai_assignment/blob/main/app/utils/stt.py"
    click TTS "https://github.com/varunkarnati/vois_ai_assignment/blob/main/app/utils/tts.py"
    click LLM "https://github.com/varunkarnati/vois_ai_assignment/blob/main/app/utils/llm.py"
    click Tools "https://github.com/varunkarnati/vois_ai_assignment/blob/main/app/utils/tools.py"
    click GraphDef "https://github.com/varunkarnati/vois_ai_assignment/blob/main/app/utils/graph_definition.py"
    click FileDB "https://github.com/varunkarnati/vois_ai_assignment/blob/main/app/utils/file_db.py"
    click OrderStore "https://github.com/varunkarnati/vois_ai_assignment/blob/main/orders_db.json"
    click History "https://github.com/varunkarnati/vois_ai_assignment/tree/main/order_histories/"

    %% Styles
    classDef compute fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef storage fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef browser fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
