# zooll51/cocktail-advisor architecture

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

- Interactive diagram: https://gitdiagram.com/zooll51/cocktail-advisor
- Repository: https://github.com/zooll51/cocktail-advisor

## Overview

##### Project Type & Core Purpose
- This is a Python full-stack application built to provide cocktail recommendations by integrating Large Language Models (OpenAI GPT), Retrieval-Augmented Generation (via LangChain and FAISS), and a chat interface. It incorporates both a FastAPI backend for the RESTful API and a Gradio-based chat UI.

##### Key Components
a. Frontend Interface:
- Gradio Chat Interface (user input and output for cocktail queries).
b. Backend API:
- FastAPI Server providing endpoints like /chat and API documentation (/docs).
- This backend orchestrates incoming requests and forwards them to other components.
c. RAG and LLM Integration:
- Module for Retrieval-Augmented Generation (indicated by “app/rag.py”).
- Integration with LangChain to manage LLM interactions.
- OpenAI GPT is the underlying language model used for generating responses.
d. Data Processing/Loading:
- The “data_loader” module (app/data_loader.py) which likely handles reading and processing the cocktail dataset.
- The “data” directory, where the cocktail dataset (final_cocktails.csv) is stored.
e. External Services & Databases:
- FAISS Vector Database (used for similarity searches).
- OpenAI’s API (for GPT requests).
- These external services should be depicted as separate components that the backend interacts with.

##### Relationships and Data Flow
- From FastAPI, illustrate the routing: queries are processed and passed to the RAG module.
- The RAG module (app/rag.py) should point to both:
- The FAISS vector database for similarity searches of cocktail data.
- OpenAI’s GPT model for generating natural language responses.
- That the backend is the central hub coordinating between the user interface, data processing, vector database, and the language model.

##### Architectural Patterns & Design Principles
- The project follows a modular design where its components are separated by functionality (API, Chat UI, Data Loading, RAG handling).
- Client-server separation (frontend vs backend).
- Use of a retrieval-based augmentation pattern where user queries are enriched by searching a vector database before querying the language model.

##### Technology Specifics
- Specific libraries: FastAPI (backend server), Gradio (frontend chat interface), FAISS (vector similarity search), LangChain (LLM orchestration), and OpenAI GPT (language model).
- Mention auxiliary libraries (Pandas, NumPy, python-dotenv) where necessary to indicate data processing and configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        GC["Gradio Chat Interface"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend & Modules"
        FAPI["FastAPI Backend"]:::backend
        RAG["RAG Module / LangChain Integration"]:::module
        DPL["Data Processing/Loading Module"]:::module
    end

    %% Data Storage
    subgraph "Data Storage"
        DATA["Cocktail Dataset"]:::dataset
    end

    %% External Services
    subgraph "External Services"
        FAISS["FAISS Vector Database"]:::external
        GPT["OpenAI GPT"]:::external
    end

    %% Connections
    GC -->|"sendsUserInput"| FAPI
    FAPI -->|"callsRAG"| RAG
    RAG -->|"retrievesData"| FAISS
    RAG -->|"queriesLLM"| GPT
    DPL -->|"loadsData"| DATA

    %% Click Events
    click GC "https://github.com/zooll51/cocktail-advisor/blob/master/app/main.py"
    click FAPI "https://github.com/zooll51/cocktail-advisor/blob/master/app/main.py"
    click RAG "https://github.com/zooll51/cocktail-advisor/blob/master/app/rag.py"
    click DPL "https://github.com/zooll51/cocktail-advisor/blob/master/app/data_loader.py"
    click DATA "https://github.com/zooll51/cocktail-advisor/blob/master/data/final_cocktails.csv"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef module fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef dataset fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
```
