How camiguarnieri/mercanova-ai-assistant works
MercaNova is an e-commerce application with a conversational shopping assistant. Users browse and filter the real product catalog or describe a need in chat; the assistant uses model tool-calling to ground product claims in catalog data. Users can manage a session cart and explicitly confirm a fictitious purchase, then view order history. The graph preserves catalog, chat, cart, and order stages; several chat and checkout implementation links are inferred from documented behavior because their source was not excerpted.
Main entry points: App.jsx App shell · client.js Catalog and chat client · api.py HTTP API · assistant.py Assistant orchestration
Components 23
Storefront
- App shell
frontend/src/App.jsx - Catalog views
frontend/src/pages/ProductList.jsx - Product detail
frontend/src/pages/ProductDetail.jsx - Chat view
frontend/src/pages/Chat.jsx - Cart and checkout view
frontend/src/pages/Cart.jsx - Shared cart state
frontend/src/CartContext.jsx - Catalog and chat client
frontend/src/api/client.js - Cart API client
frontend/src/api/cart.js
API and orchestration
- HTTP API
backend/api.py - Chat endpoint
backend/chat_api.py - Assistant orchestration
backend/assistant.py - Model client
backend/llm.py
Catalog and assistant tools
- Tool validation and routing
backend/tool_router.py - Catalog tools
backend/tools.py - Search filters
backend/search_filters.py - Catalog queries
backend/catalog.py
Cart and orders
- Cart and order endpoints
backend/cart_api.py - Cart rules
backend/cart.py - Order management
backend/orders.py
State and model services
- Ollama model
- In-memory carts
backend/carts.py - SQLite database
backend/db.py
Other components
- Shopper
Connections 27
- Shopper → App shell: uses
- App shell → Catalog views: shows
frontend/src/App.jsx - App shell → Product detail: shows
frontend/src/App.jsx - App shell → Chat view: shows
frontend/src/App.jsx - App shell → Cart and checkout view: shows
frontend/src/App.jsx - Catalog views → Catalog and chat client: requests products
frontend/src/pages/ProductList.jsx - Product detail → Catalog and chat client: requests detail
frontend/src/pages/ProductDetail.jsx - Chat view → Catalog and chat client: sends messages
frontend/src/pages/Chat.jsx - Cart and checkout view → Cart API client: checks out
frontend/src/pages/Cart.jsx - App shell → Shared cart state: provides shared state
frontend/src/App.jsx - Shared cart state → Cart API client: updates cart
frontend/src/CartContext.jsx - Catalog and chat client → HTTP API: calls HTTP API
- Cart API client → Cart and order endpoints: calls cart endpoints
- HTTP API → Catalog queries: delegates catalog queries
backend/api.py - HTTP API → Chat endpoint: includes chat routes
backend/api.py - Chat endpoint → Assistant orchestration: dispatches chat
- Assistant orchestration → Model client: requests completion
- Model client → Ollama model: calls model
- Assistant orchestration → Tool validation and routing: dispatches tools
- Tool validation and routing → Catalog tools: runs validated tool
backend/tool_router.py - Catalog tools → Catalog queries: queries products
backend/tools.py - Catalog tools → Search filters: applies filters
backend/tools.py - Cart and order endpoints → Cart rules: applies cart rules
backend/cart_api.py - Cart rules → In-memory carts: reads and updates
backend/cart.py - Cart and order endpoints → Order management: handles checkout
backend/cart_api.py - Order management → SQLite database: persists orders
backend/orders.py - Catalog queries → SQLite database: queries catalog