# lucasboscatti/sales-ai-agent-langgraph architecture

> Architecture diagram of the GitHub repository lucasboscatti/sales-ai-agent-langgraph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucasboscatti/sales-ai-agent-langgraph
- Repository: https://github.com/lucasboscatti/sales-ai-agent-langgraph

## Overview

##### Project Type and Purpose
- This project is an AI-driven Virtual Sales Agent that interacts with customers over a Streamlit-built web interface.
- Its core functionalities include handling product inquiries, order placement, order tracking, and providing personalized recommendations.
- The system leverages LangChain and LangGraph for the conversational and workflow management, uses a SQLite database for product and order data management, and integrates Google’s Gemini Flash for natural language processing.

##### Analyzing the File Structure
- Key directories and files:
- database: Has DB configuration files (config.py), the DB manager (db_manager.py), and actual data files (products.json, schemas.sql in db/ folder), plus a setup script (setup_database.py) to initialize the database.
- virtual_sales_agent: Contains the core logic of the agent (graph.py for LangGraph state machine, tools.py for custom tools, and utils functions).
- main.py: Acts as the entry point for the Streamlit web interface.
- Environment templates and dependency files which support configuration and smooth deployment.

##### Understanding the README Insights
- The README clearly outlines the features, use-cases, and the technologies used, such as LangChain, LangGraph, SQLite, Streamlit, and Gemini Flash.
- The documentation emphasizes a human-in-the-loop system for sensitive operations like order placement, which is a key architectural detail.

a. Main Components:
- User Interface: Powered by Streamlit (represented by main.py along with assets for styling and images) that the end-user interacts with.
- Conversational Agent: The core logic is handled by components inside virtual_sales_agent (graph.py for the state machine, tools.py for AI interactions).
- Database: Managed through the database module (db_manager.py, config.py, and data files), which stores product details and orders.
- External AI Services: This includes components like Gemini Flash for language processing and LangChain for orchestrating interactions.
- Human-in-the-Loop Module: A checkpoint mechanism to review and approve sensitive actions (order creation).

b. Relationships and Data Flow:
- Users initiate requests on the web interface (Streamlit app) which then are forwarded to the virtual_sales_agent component.
- The conversational agent processes the request using LangChain and state management from LangGraph, possibly calling custom tools (from tools.py) and utility functions.
- For product or order data, the agent interacts with the SQLite database via the database’s DB manager.
- For sensitive actions, an intermediate step provides a human-in-the-loop approval before the operation is finalized.
- External APIs (e.g., Gemini Flash) are called as needed to enhance natural language understanding.

c. Architectural Patterns:
- Separation of Concerns: Clear division between the UI, business logic (agent logic), and data management.
- Modular Design: The project is split into distinct directories each handling a specific concern (interface, database, agent logic).
- State-based Workflow: Using LangGraph’s state machine to manage different agent states and transitions.
- Human-in-the-Loop: Incorporation of user confirmation for high-stake actions to balance automation with manual oversight.

d. Relevant Technologies and Frameworks:
- Streamlit for the front-end.
- LangChain and LangGraph for the agent’s conversational abilities and workflow management.
- SQLite for the lightweight database component.
- Python as the main programming language with all necessary packages listed in requirements.txt.

##### Elements
- Labels: Name each component clearly (e.g., “Streamlit UI”, “Virtual Sales Agent (LangGraph)”, “Database Manager”, “Gemini Flash API”).
- From the user to the Streamlit frontend.
- From the frontend to the Virtual Sales Agent logic.
- From agent logic toward the database and back.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    Agent["Virtual Sales Agent (LangGraph Core)"]:::agent
    PI(("Product Inquiry Tool")):::tool
    OC(("Order Creation Tool")):::tool
    OT(("Order Tracking Tool")):::tool
    RT(("Recommendations Tool")):::tool

    %% Workflow: Agent delegations and feedback
    Agent -->|"process_query"| PI
    PI -->|"send_response"| Agent

    Agent -->|"process_order"| OC
    OC -->|"approval+response"| Agent

    Agent -->|"track_order"| OT
    OT -->|"send_status"| Agent

    Agent -->|"generate_recommendation"| RT
    RT -->|"send_recommendation"| Agent

    %% Click Events
    click Agent "https://github.com/lucasboscatti/sales-ai-agent-langgraph/blob/main/virtual_sales_agent/graph.py"
    click PI "https://github.com/lucasboscatti/sales-ai-agent-langgraph/blob/main/virtual_sales_agent/tools.py"
    click OC "https://github.com/lucasboscatti/sales-ai-agent-langgraph/blob/main/virtual_sales_agent/tools.py"
    click OT "https://github.com/lucasboscatti/sales-ai-agent-langgraph/blob/main/virtual_sales_agent/tools.py"
    click RT "https://github.com/lucasboscatti/sales-ai-agent-langgraph/blob/main/virtual_sales_agent/tools.py"

    %% Styles
    classDef agent fill:#a9d0f5,stroke:#000,stroke-width:2px,color:#000;
    classDef tool fill:#a8d08d,stroke:#000,stroke-width:2px,color:#000;
```
