AI Store Assistant Chatbot

Production-oriented AI chatbot for small online stores

A FastAPI backend plus an embeddable vanilla JavaScript widget that answers store/customer questions using verified catalog data, optional LLM providers, and validation so prices, stock, and locations are not invented.

The Problem

Small online stores often receive repeated customer questions:

Customer Question	Store Problem
“Do you have this product?”	Staff must manually check catalog or stock
“How much is it?”	Customers need fast and accurate price answers
“Where is it located?”	Store shelf/location info should not be guessed
“Is it in stock?”	AI must not invent availability
“Can I order now?”	Customers expect fast responses

Generic AI chatbots can sound confident but may invent fake prices, fake stock, or fake locations.

This project explores how to make a small-store AI assistant more useful and safer by grounding answers in verified product data.

The Solution

AI Store Assistant Chatbot is a production-oriented MVP for store support.

It combines:

an embeddable frontend chat widget
a FastAPI backend
product search over mock catalog data
intent parsing
context building
optional LLM providers
rule-based fallback
answer validation

The goal is not just to make an AI chatbot answer questions, but to make it answer using real catalog information.

Core Architecture

flowchart TD
    U[User] --> W[Embeddable Chat Widget]
    W --> API[FastAPI Backend /api/chat]

    API --> ORCH[Assistant Orchestrator]
    ORCH --> INTENT[Intent Parser]
    ORCH --> SEARCH[Product Search Engine]
    ORCH --> STORE[Store Client]

    SEARCH --> MOCK[(Mock Product JSON)]
    STORE --> MOCK
    STORE -. later .-> REAL[Real Store API]

    ORCH --> CTX[Context Builder]
    CTX --> AI[AI Client<br/>Ollama / OpenAI / Gemini / Fallback]
    AI --> VALIDATE[Answer Validator<br/>No fake price/stock/location]
    VALIDATE --> API
    API --> W
    W --> U

Full platform-style diagrams are available in:

docs/architecture.md

Why I Built It

I wanted to build an AI project that feels closer to a real product, not just a simple chatbot demo.

Many small online stores in Mongolia and other countries sell through small websites, Facebook pages, or simple online catalogs. They often do not have large technical teams or full-time customer support.

So I wanted to explore this question:

Can a small store use a simple AI assistant that answers customer questions based on real product data, while avoiding fake or unsupported information?

This project helped me learn that useful AI applications need more than an LLM. They need backend logic, data grounding, validation, fallback behavior, security boundaries, and user experience design.

Features

Feature	Description
Mongolian-first replies	Replies are optimized for Mongolian, while English keywords are supported in intent parsing
Embeddable widget	Minimalist vanilla JS widget for store websites
Movable UI	Drag header, resize bottom-right, minimize, maximize, and close
Text size controls	A− / A+ adjusts text size and saves locally
Mock product catalog	Uses `backend/data/products.json` with compatibility, symptoms, pricing, stock, and shelf location
Product ranking	Ranks products by car, symptom, category, keywords, and stock
Pluggable AI providers	Ollama → OpenAI → Gemini → rule-based fallback
Answer validation	Checks returned answer against product cards to avoid fake price, stock, or location
Safe API design	API keys stay in backend `.env`, never in browser
CORS control	CORS origins are configured from environment variables
Message limits	Limits message length and avoids leaking stack traces to clients
Docker support	Can run through Docker Compose

What Makes It Different

This project is not only:

User message → AI answer

It follows a safer AI product flow:

User message
    ↓
Intent parsing
    ↓
Product search
    ↓
Verified catalog context
    ↓
AI or fallback response
    ↓
Answer validation
    ↓
Safe customer response

That makes it more realistic for store/customer support use cases.

System Design

Layer	Responsibility
Widget	Customer-facing chat interface
API	Receives chat requests and returns assistant responses
Assistant Orchestrator	Coordinates intent, search, context, AI, and validation
Intent Parser	Detects product/search/support intent from user messages
Product Search Engine	Finds relevant products from mock catalog data
Store Client	Reads mock product data now, can later connect to real store APIs
Context Builder	Builds grounded context for the assistant
AI Client	Uses Ollama, OpenAI, Gemini, or fallback templates
Answer Validator	Prevents unsupported price, stock, and location claims
Fallback Builder	Returns safe Mongolian template answers if no AI provider is available

AI Provider Flow

Provider order:

Ollama → OpenAI → Gemini → Rule-based fallback

This means:

Provider	Purpose
Ollama	Local/free model support
OpenAI	Optional hosted LLM provider
Gemini	Optional hosted LLM provider
Rule-based fallback	Safe response templates when AI is unavailable

The assistant can still work without any AI API key by using fallback Mongolian templates.

Security: API Keys

LLM and store secrets must live only in:

backend/.env

or in the host secret manager.

The browser must never receive OpenAI, Gemini, Ollama, or store provider secrets.

The widget may expose:

window.AI_STORE_ASSISTANT_API

but this should only be the public backend base URL, not a secret key.

Example Use Cases

User asks	Assistant should do
“Prius 30 асахгүй байна”	Detect car/symptom intent and search matching products
“Энэ хэд вэ?”	Answer using real catalog price if available
“Байгаа юу?”	Use stock information from product data
“Хаана байгаа вэ?”	Use verified shelf/location data only
“Өөр төстэй юм байна уу?”	Suggest relevant alternatives from catalog
“Хямдруулж болох уу?”	Avoid inventing unsupported discount policies

Project Structure

ai-store-assistant-chatbot/
├─ backend/
│  ├─ app/
│  │  ├─ main.py
│  │  ├─ response_builder.py
│  │  └─ ...
│  ├─ data/
│  │  └─ products.json
│  ├─ tests/
│  ├─ Dockerfile
│  ├─ requirements.txt
│  └─ .env.example
├─ frontend/
│  └─ widget files
├─ docs/
│  ├─ architecture.md
│  ├─ api.md
│  └─ store-api-integration.md
├─ README.md
└─ docker-compose.yml

How to Run

Windows PowerShell

cd ai-store-assistant-chatbot\backend
Copy-Item .env.example .env
python -m pip install -r requirements.txt
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Open:

http://127.0.0.1:8000/widget/index.html

macOS / Linux

cd ai-store-assistant-chatbot/backend
cp .env.example .env
python3 -m pip install -r requirements.txt
python3 -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Open:

http://127.0.0.1:8000/widget/index.html

Backend Setup

cd backend
cp .env.example .env
python -m pip install -r requirements.txt
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Useful local URLs:

URL	Purpose
`http://127.0.0.1:8000`	API root
`http://127.0.0.1:8000/docs`	Swagger docs
`http://127.0.0.1:8000/widget/index.html`	Widget demo

Frontend Widget

The widget can be served from the backend using FastAPI’s /widget mount.

If opening the frontend from disk using file://, set the backend API before widget.js loads:

<script>
  window.AI_STORE_ASSISTANT_API = "http://127.0.0.1:8000";
</script>

Docker

From project root:

docker compose up --build

The compose file mounts:

./frontend → /frontend

and sets:

FRONTEND_STATIC_PATH=/frontend

so /widget works inside the container.

Environment Variables

See:

backend/.env.example

Important variables:

Variable	Purpose
`CORS_ORIGINS`	Comma-separated browser origins allowed to call the API
`STORE_PROVIDER`	`mock` by default, `rest` later
`OLLAMA_BASE_URL`	Local Ollama base URL
`OLLAMA_MODEL`	Ollama model name
`OPENAI_API_KEY`	OpenAI API key
`OPENAI_MODEL`	OpenAI model name
`GEMINI_API_KEY`	Gemini API key
`GEMINI_MODEL`	Gemini model name
`FRONTEND_STATIC_PATH`	Optional absolute path for widget files

Never put provider keys in the frontend.

Run Without Any AI Provider

Leave these empty in .env:

OLLAMA_BASE_URL=
OPENAI_API_KEY=
GEMINI_API_KEY=

Then /api/chat uses Mongolian rule-based templates from:

app/response_builder.py

Example API Calls

Health check:

curl -s http://127.0.0.1:8000/health

Chat request:

curl -s -X POST http://127.0.0.1:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"Prius 30 асахгүй байна","lang":"mn"}'

More examples:

docs/api.md

Connecting a Real Store API

Right now, the project uses mock catalog data from:

backend/data/products.json

To connect a real store API:

Implement RestStoreClient.
Replace or extend MockStoreClient.
Set:

STORE_PROVIDER=rest

Keep the same orchestration flow.

More details:

docs/store-api-integration.md

Ollama Setup

Install Ollama.
Pull a model:

ollama pull llama3.2

Add this to backend/.env:

OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=llama3.2

Restart the backend.

If Ollama is unreachable, the service falls back to templates.

OpenAI / Gemini Setup

Set either:

OPENAI_API_KEY=your_key_here

or:

GEMINI_API_KEY=your_key_here

Only the backend reads these keys.

Provider order:

Ollama → OpenAI → Gemini → Fallback

Tests

cd backend
python -m pytest -q

Demo Flow for Reviewers

Recommended 45–60 second demo:

Time	What to show
0–10 sec	Explain the problem: small stores need fast support
10–20 sec	Show the embeddable widget
20–35 sec	Ask a product/car-related question
35–45 sec	Show catalog-grounded answer with product info
45–55 sec	Ask unsupported/fake info question
55–60 sec	Show validation or safe fallback behavior

What I Learned

While building this project, I learned that useful AI applications are not only about sending prompts to a model.

The hardest parts were:

grounding answers in real product data
preventing fake price, stock, and location claims
designing fallback behavior
connecting frontend widget logic with backend APIs
thinking about API key security
making AI responses safer and more useful
designing a system that can later connect to a real store API

This project helped me understand that AI products need system design, not just model output.

Current Limitations

Limitation	Future Fix
Mock catalog only	Connect real inventory/POS/PIM API
Keyword search	Add embeddings + vector database
Basic validation	Add stronger validation rules and tests
No admin dashboard	Add product upload and store management UI
Limited rate limiting	Add Redis/API gateway rate limiting
No streaming yet	Add streaming responses or WebSockets

Future Improvements

Replace keyword search with embeddings + vector DB
Connect real inventory, POS, or PIM through RestStoreClient
Add strong rate limiting with Redis or API gateway
Add auth for production widgets
Add streaming responses
Add WebSocket support for lower latency
Add admin dashboard
Add product upload UI
Add richer Mongolian language support
Add analytics for store owners
Add hosted live demo

Documentation

File	Description
`docs/architecture.md`	Full system and runtime diagrams
`docs/api.md`	Endpoints and payloads
`docs/store-api-integration.md`	Moving from JSON mock to REST store API

Portfolio Summary

AI Store Assistant Chatbot is a practical AI product prototype for small online stores.

It demonstrates:

FastAPI backend development
embeddable widget architecture
product search and catalog grounding
LLM provider orchestration
validation and fallback design
API key security boundaries
real-world AI product thinking

This project represents my interest in building AI systems that are useful, safer, and connected to real user problems.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
backend		backend
docs		docs
frontend		frontend
.gitignore		.gitignore
README.md		README.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation