# adarshukla3005/ai-restaurant-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/adarshukla3005/ai-restaurant-assistant
- Repository: https://github.com/adarshukla3005/ai-restaurant-assistant

## Overview

##### Project type and purpose
- This is a modular full-stack AI assistant:
- Frontend: Streamlit web UI (app.py)
- Backend: Local vector database (ChromaDB), embedding service, external LLM API (Gemini-2.0-flash)
- Data-ingestion pipeline: Web scraper + JSON data processing

##### Main components
a. User Interface (Streamlit)
- app.py (Runs locally at localhost:8501)
- Communicates with the query-processing layer
b. Query Processing Layer (src/models/query_processor.py)
- Orchestrates between vector search and LLM API
- Applies business logic, fallback rules (restaurant vs. general queries)
c. Embedding Service (sentence-transformers)
- src/models/embeddings.py
- Generates vector embeddings for queries and data
d. Vector Database (ChromaDB)
- chroma_db folder + src/database/vector_db.py
- Stores/retrieves embeddings + metadata for restaurant data
e. External LLM API (Gemini-2.0-flash)
- Configured in src/config/llm_config.py
- Used for general knowledge responses
f. Data Storage
- Raw JSON data (data/*.json)
- Conversation history (convo_history/*.json)
- Database file (chroma_db/chroma.sqlite3, binary shards)
g. Data Ingestion / Web Scraping
- webscraper.py + utils/zomato_scraper.py + utility scripts (utils/)
- Selenium + BeautifulSoup → JSON → normalization → vector ingestion

##### Relationships and data flows
- User → Streamlit UI → Query Processor
- Query Processor →
- Vector Database (via vector_db.py) for restaurant queries
- Embedding Service to convert text to vectors
- External LLM API for general queries
- Data Ingestion Pipeline (offline) →
- Web Scraper → raw JSON → utils processing → embeddings → ChromaDB
- Conversation History Logger (conversation_history.json) captures Q&A

##### Architectural patterns & design principles
- Modular separation of concerns (config / database / models / prompts)
- “Adapter” layers: vector_db adapter isolates DB implementation
- Single responsibility: each module (scraping, embedding, query logic) is independent
- Data pipeline vs. real-time query path are decoupled

##### Technologies & frameworks
- Frontend: Streamlit
- Embeddings: sentence-transformers/all-MiniLM-L6-v2 (local)
- Vector DB: ChromaDB (local, file-based)
- LLM: Google Gemini-2.0-flash (external API)
- Web Scraping: Selenium + BeautifulSoup4
- Orchestration: Python scripts + app.py

##### Inclusion checklist
- Component labels (UI, services, DB, files, external)
- Arrowed lines illustrating request/response or data-flow direction
- Call out config files (llm_config.py), prompt templates (prompts.py), and model adapters

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    User["User (Browser)"]:::external

    %% UI Layer
    UI["Streamlit UI\n(app.py)"]:::ui

    User --> UI
    UI --> QP

    %% Processing Layer
    subgraph "Processing Layer"
        QP["Query Processor\n(src/models/query_processor.py)"]:::processing
        Emb["Embedding Service\n(src/models/embeddings.py)"]:::service
        LLM["LLM API\n(Gemini-2.0-flash)"]:::external
        Prompt["Prompt Templates\n(prompts.py)"]:::service
        Config["LLM Config\n(src/config/llm_config.py)"]:::service
        ConvModel["Conversation History Model\n(src/models/conversation_history.py)"]:::service
        DBAdapter["Vector DB Adapter\n(src/database/vector_db.py)"]:::service
    end

    UI --> QP
    QP --> Emb
    QP --> LLM
    QP --> Prompt
    QP --> Config
    QP --> ConvModel
    Emb --> DBAdapter
    DBAdapter --> DBFiles

    %% Data Ingestion Pipeline
    subgraph "Data Ingestion Pipeline (Offline)"
        Scraper["Web Scraper Orchestrator\n(webscraper.py)"]:::service
        Zoma["Zomato Scraper\n(utils/zomato_scraper.py)"]:::service
        Combine["Combine Data\n(utils/combine.py)"]:::service
        Insert["Insert Normalized\n(utils/insert_normalized_with_urls.py)"]:::service
        SaveNorm["Save Normalized\n(utils/save_normalized_data.py)"]:::service
        RawData["Raw JSON Data\n(data/*.json)"]:::datastore
        Schema["Restaurant Schema\n(restaurant_schema.json)"]:::datastore
    end

    Scraper --> Zoma
    Zoma --> Combine
    RawData --> Combine
    Schema --> Combine
    Combine --> Insert
    Insert --> SaveNorm
    SaveNorm --> Emb

    %% Data Stores
    subgraph "Data Stores"
        DBFiles["ChromaDB Files\n(chroma_db/chroma.sqlite3)"]:::datastore
        HistoryStore["Conversation History\n(convo_history/conversation_history.json)"]:::datastore
    end

    ConvModel --> HistoryStore

    %% Click Events
    click UI "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/app.py"
    click QP "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/src/models/query_processor.py"
    click Emb "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/src/models/embeddings.py"
    click DBAdapter "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/src/database/vector_db.py"
    click DBFiles "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/chroma_db/chroma.sqlite3"
    click Prompt "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/src/prompts/prompts.py"
    click Config "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/src/config/llm_config.py"
    click ConvModel "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/src/models/conversation_history.py"
    click RawData "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/data/*.json"
    click HistoryStore "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/convo_history/conversation_history.json"
    click Scraper "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/webscraper.py"
    click Zoma "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/utils/zomato_scraper.py"
    click Combine "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/utils/combine.py"
    click Insert "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/utils/insert_normalized_with_urls.py"
    click SaveNorm "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/utils/save_normalized_data.py"
    click Schema "https://github.com/adarshukla3005/ai-restaurant-assistant/blob/main/restaurant_schema.json"

    %% Styles
    classDef ui fill:#D6E4FF,stroke:#1F618D
    classDef processing fill:#E2F0CB,stroke:#4D774E
    classDef service fill:#CFF7F8,stroke:#117A65
    classDef datastore fill:#FDEBD0,stroke:#B9770E,shape:cylinder
    classDef external fill:#FADBD8,stroke:#C0392B,shape:rect
```
