# nvidia-ai-blueprints/retail-shopping-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/nvidia-ai-blueprints/retail-shopping-assistant
- Repository: https://github.com/nvidia-ai-blueprints/retail-shopping-assistant

## Overview

##### Project Type and Purpose
- This is a full-stack, microservices AI application: the “Retail Shopping Assistant” blueprint.
- Purpose: provide a conversational, multimodal (text+image) shopping assistant using a multi-agent orchestration (LangGraph), servicing UI requests, product retrieval, memory/cart management, and content safety.

##### File Structure Highlights
- Top-level microservices directories:
- chain_server/ – FastAPI + LangGraph orchestrator (“brain”).
- catalog_retriever/ – Product search & recommendations agent.
- memory_retriever/ – User context & cart state agent.
- guardrails/ – Moderation & safety agent.
- ui/ – React + TypeScript frontend.
- Shared resources: shared/configs/, shared/data/ (product CSVs), shared/images.
- Deployment: Dockerfiles in each service, docker-compose.yaml (and docker-compose-nim-local.yaml) for local vs. cloud deployments.
- Infrastructure as code: nginx.conf (ingress), GitHub workflows, config overrides.

##### Key Components
A. Frontend Layer
- React UI (ui/) served via NGINX reverse proxy (nginx.conf).
B. API Gateway / Ingress
- NGINX routes HTTP traffic to the Chain Server.
C. Orchestration Layer
- Chain Server (FastAPI + LangGraph) implements REST/WebSocket endpoints, agent orchestration, streaming.
D. Agent Microservices
1. Catalog Retriever – searches product catalog (calls vector DB or remote API).
2. Memory Retriever – manages user session context & cart state (in-memory or persistent store).
3. Guardrails – runs content moderation pipelines (NemoGuard models via NIM).
E. Data Stores & External Services
- Vector database (Milvus) for similarity search.
- NVIDIA NGC containers / NIM endpoints for LLM inference (e.g., Llama, NV-EmbedQA, CLIP).
- Product catalog CSVs (shared/data) and other static assets.
F. Configuration & Secrets
- shared/configs for service-specific YAMLs.
- ENV variables (API keys) injected at runtime.

##### Interactions & Data Flow
1. User submits query or image → UI (React)
2. UI → HTTP/WebSocket → NGINX → Chain Server
3. Chain Server uses LangGraph to fan-out tasks:
- Calls Catalog Retriever via REST for product search
- Calls Memory Retriever for past conversation/cart context
- Calls Guardrails for moderation of prompts/responses
- Calls GPU model endpoints (NGC/NIM) for LLM responses
4. Retriever services may query Milvus or CSV data.
5. Chain Server aggregates results, streams back to UI.
6. UI renders streaming chat + images + cart updates.

##### Architectural Patterns & Principles
- Microservices: each concern (retrieval, memory, safety) in its own container.
- Orchestrator Pattern: Chain Server choreographs agents via LangGraph.
- API Gateway: NGINX as ingress.
- Separation of concerns: UI vs. backend vs. data.
- Config-as-code: shared/configs with build vs. override YAMLs.
- Docker Compose for environment reproducibility.

##### Must-Include Elements
- Component labels: e.g., “UI (React)”, “Chain Server (FastAPI + LangGraph)”, “Catalog Retriever”, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["UI (React)"]:::frontend
    end

    %% API Gateway / Ingress
    subgraph "API Gateway / Ingress"
        NG["NGINX"]:::ingress
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        CS["Chain Server\n(FastAPI + LangGraph)"]:::orchestrator
    end

    %% Agent Microservices
    subgraph "Agent Microservices"
        CR["Catalog Retriever"]:::agent
        MR["Memory Retriever"]:::agent
        GR["Guardrails"]:::agent
    end

    %% Data Stores & External Services
    subgraph "Data Stores & External Services"
        DB["Milvus (Vector DB)"]:::datastore
        NIM["NGC/NIM Model Endpoints"]:::external
        CSV["Product CSVs"]:::datastore
    end

    %% Configuration & Deployment
    CONFIG["shared/configs & ENV"]:::external
    COMPOSE["Docker Compose YAMLs"]:::external

    %% Connections
    UI -->|HTTP/WebSocket| NG
    NG -->|HTTP| CS
    CS -->|REST| CR
    CS -->|REST| MR
    CS -->|REST| GR
    CS -->|gRPC| NIM
    CR -->|vector search| DB
    CR -->|reads CSV| CSV
    CS -->|streams| UI

    %% Config mounts
    CONFIG --> CS
    CONFIG --> CR
    CONFIG --> GR

    %% Deployment orchestration
    COMPOSE --> NG
    COMPOSE --> CS
    COMPOSE --> CR
    COMPOSE --> MR
    COMPOSE --> GR

    %% Click Events
    click UI "https://github.com/nvidia-ai-blueprints/retail-shopping-assistant/tree/main/ui/"
    click NG "https://github.com/nvidia-ai-blueprints/retail-shopping-assistant/blob/main/nginx.conf"
    click CS "https://github.com/nvidia-ai-blueprints/retail-shopping-assistant/tree/main/chain_server/"
    click CR "https://github.com/nvidia-ai-blueprints/retail-shopping-assistant/tree/main/catalog_retriever/"
    click MR "https://github.com/nvidia-ai-blueprints/retail-shopping-assistant/tree/main/memory_retriever/"
    click GR "https://github.com/nvidia-ai-blueprints/retail-shopping-assistant/tree/main/guardrails/"
    click CONFIG "https://github.com/nvidia-ai-blueprints/retail-shopping-assistant/tree/main/shared/configs/"
    click CSV "https://github.com/nvidia-ai-blueprints/retail-shopping-assistant/tree/main/shared/data/"
    click COMPOSE "https://github.com/nvidia-ai-blueprints/retail-shopping-assistant/blob/main/docker-compose.yaml"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef ingress fill:#D5F5E3,stroke:#196F3D,color:#145A32;
    classDef orchestrator fill:#FDEBD0,stroke:#B9770E,color:#7E5109;
    classDef agent fill:#E8DAEF,stroke:#6C3483,color:#4A235A;
    classDef datastore fill:#FCF3CF,stroke:#B7950B,color:#7D6608;
    classDef external fill:#F5B7B1,stroke:#C0392B,color:#641E16;
```
