# unicamp-dl/retailgpt architecture

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

- Interactive diagram: https://gitdiagram.com/unicamp-dl/retailgpt
- Repository: https://github.com/unicamp-dl/retailgpt

## Overview

##### Project type and purpose
- This is a full-stack, microservice-style chatbot application (“Retail-GPT”) built to deliver a RAG-powered conversational sales agent.
- It consists of four discrete services:
- A Streamlit chat interface (“chat_interface”)
- A Rasa core NLP/chatbot server (“rasa_chatbot”)
- A Rasa actions server hosting custom actions and the RAG subsystem (“actions_server”)
- A Redis database for session/cart storage

##### File structure
- Top-level:
- docker-compose.yml: orchestrates all containers
- chat_interface/: front end
- retailGPT/rasa_chatbot/: Rasa core
- retailGPT/actions_server/: Rasa custom actions + RAG
- retailGPT/datasets/: static/evaluation data
- Within actions_server/src/LLMChatbot/services: micro-services handling database, product retrieval, cart/memory, guardrails, and llm calls.

##### README for additional insights
- Rasa server handles intents, NLU, entity extraction, dialogue policies, and forwards “action” requests to actions_server.
- actions_server implements:
- A “cart_handler” to maintain shopping cart in Redis
- A “memory_handler” for conversation context (also Redis)
- A “product_handler” pulling product info from JSON datasets
- A “llm_handler” that issues OpenAI GPT-4o function calls
- Guardrails enforcement
- chat_interface communicates via HTTP to rasa_chatbot endpoints.

##### Main components & their relationships
a. Components:
- Client/UI: Streamlit app
- Rasa Core server: NLU + dialogue management
- Rasa Actions server: custom actions + RAG logic
- Redis: tracker store & cart store
- External LLM API: OpenAI (GPT-4o)
- Static datasets: JSON product definitions, evaluation sets
b. Interactions/data flow:
1. UI → Rasa Core (REST endpoint)
2. Rasa Core: intent classification → slot filling → policy → if custom action → HTTP → Actions server
3. Actions server:
– fetch conversation state/cart from Redis
– call product/memory handlers as needed
– call llm_handler → OpenAI API → receive function calls → dispatch to local services (e.g., cart_handler)
– save updated state in Redis
4. Actions server → HTTP response back to Rasa Core → Rasa orchestrates next reply → UI
c. Architectural patterns:
- Microservices for separation of concerns (UI, NLU, actions, storage)
- Function-call pattern with GPT for external tool integration
- Event-driven/custom-action pattern in Rasa
- Redis as a distributed in-memory store for session/cart
d. Key technologies:
- Streamlit (UI)
- Rasa (NLU & Core)
- Python-based Rasa SDK for actions
- OpenAI API (GPT-4o)
- Redis (via Docker compose)
- Docker & Docker-Compose

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Services
    UI["Streamlit UI"]:::service
    RasaCore["Rasa Core Server"]:::service
    ActionsServer["Custom Actions Server"]:::service
    RedisDB["Redis DB"]:::db
    Datasets["Static JSON Datasets"]:::db
    OpenAI["OpenAI GPT-4o API"]:::external

    %% Action Server Sub-components
    subgraph "Custom Actions Server"
        LLMHandler["LLM Handler"]:::component
        ProductHandler["Product Handler"]:::component
        CartHandler["Cart Handler"]:::component
        MemoryHandler["Memory Handler"]:::component
        Guardrails["Guardrails Module"]:::component
        DBService["Database Service"]:::component
    end

    %% Data Flow
    UI -->|"1. POST /webhooks/rest"| RasaCore
    RasaCore -->|"2. /webhooks/rest"| ActionsServer
    ActionsServer -->|"3a. Redis GET/SET"| RedisDB
    ActionsServer -->|"3b. Read JSON"| Datasets
    ActionsServer -->|"3c. OpenAI API call"| OpenAI
    OpenAI -->|"4. function call response"| ActionsServer
    ActionsServer -->|"5. response"| RasaCore
    RasaCore -->|"6. reply"| UI

    %% Internal Action Server Flow
    LLMHandler -->|"calls"| ProductHandler
    LLMHandler -->|"calls"| CartHandler
    LLMHandler -->|"calls"| MemoryHandler
    LLMHandler -->|"calls"| Guardrails
    LLMHandler -->|"uses"| DBService

    %% Click Events
    click UI "https://github.com/unicamp-dl/retailgpt/tree/main/chat_interface/"
    click RasaCore "https://github.com/unicamp-dl/retailgpt/tree/main/retailGPT/rasa_chatbot/"
    click ActionsServer "https://github.com/unicamp-dl/retailgpt/tree/main/retailGPT/actions_server/"
    click LLMHandler "https://github.com/unicamp-dl/retailgpt/blob/main/retailGPT/actions_server/src/LLMChatbot/services/llm_handler.py"
    click ProductHandler "https://github.com/unicamp-dl/retailgpt/blob/main/retailGPT/actions_server/src/LLMChatbot/services/product_handler.py"
    click CartHandler "https://github.com/unicamp-dl/retailgpt/blob/main/retailGPT/actions_server/src/LLMChatbot/services/cart_handler.py"
    click MemoryHandler "https://github.com/unicamp-dl/retailgpt/blob/main/retailGPT/actions_server/src/LLMChatbot/services/memory_handler.py"
    click Guardrails "https://github.com/unicamp-dl/retailgpt/blob/main/retailGPT/actions_server/src/LLMChatbot/services/guardrails/guardrails.py"
    click DBService "https://github.com/unicamp-dl/retailgpt/blob/main/retailGPT/actions_server/src/LLMChatbot/services/database.py"
    click Datasets "https://github.com/unicamp-dl/retailgpt/tree/main/retailGPT/datasets/"

    %% Styling
    classDef service fill:#D6EAF8,stroke:#21618C,color:#1B4F72;
    classDef component fill:#D5F5E3,stroke:#27AE60,color:#1D8348;
    classDef db fill:#FCF3CF,stroke:#B7950B,color:#7D6608;
    classDef external fill:#E5E7E9,stroke:#7B7D7D,color:#717D7E;
```
