# camiguarnieri/mercanova-ai-assistant architecture

> Architecture diagram of the GitHub repository camiguarnieri/mercanova-ai-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/camiguarnieri/mercanova-ai-assistant
- Repository: https://github.com/camiguarnieri/mercanova-ai-assistant

## Overview

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: [`frontend/src/App.jsx`](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/App.jsx) (App shell), [`frontend/src/api/client.js`](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/api/client.js) (Catalog and chat client), [`backend/api.py`](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/api.py) (HTTP API), [`backend/assistant.py`](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/assistant.py) (Assistant orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Storefront"]
  node_app["App shell<br/>[App.jsx]"]
  node_catalog_views["Catalog views<br/>[ProductList.jsx]"]
  node_product_detail["Product detail<br/>[ProductDetail.jsx]"]
  node_chat_view["Chat view<br/>[Chat.jsx]"]
  node_cart_view["Cart and checkout view<br/>[Cart.jsx]"]
  node_cart_context["Shared cart state<br/>[CartContext.jsx]"]
  node_api_client["Catalog and chat client<br/>[client.js]"]
  node_cart_client["Cart API client<br/>[cart.js]"]
end

subgraph group_api["API and orchestration"]
  node_backend_api["HTTP API<br/>[api.py]"]
  node_chat_api["Chat endpoint<br/>[chat_api.py]"]
  node_assistant["Assistant orchestration<br/>[assistant.py]"]
  node_llm["Model client<br/>[llm.py]"]
end

subgraph group_catalog["Catalog and assistant tools"]
  node_tool_router["Tool validation and routing<br/>[tool_router.py]"]
  node_tools["Catalog tools<br/>[tools.py]"]
  node_search_filters["Search filters<br/>[search_filters.py]"]
  node_catalog_service["Catalog queries<br/>[catalog.py]"]
end

subgraph group_commerce["Cart and orders"]
  node_cart_api["Cart and order endpoints<br/>[cart_api.py]"]
  node_cart_rules["Cart rules<br/>[cart.py]"]
  node_orders["Order management<br/>[orders.py]"]
end

subgraph group_services["State and model services"]
  node_ollama["Ollama model"]
  node_cart_store[("In-memory carts<br/>[carts.py]")]
  node_database[("SQLite database<br/>[db.py]")]
end

node_user(("Shopper"))

node_user -->|"uses"| node_app
node_app -->|"shows"| node_catalog_views
node_app -->|"shows"| node_product_detail
node_app -->|"shows"| node_chat_view
node_app -->|"shows"| node_cart_view
node_catalog_views -->|"requests products"| node_api_client
node_product_detail -->|"requests detail"| node_api_client
node_chat_view -->|"sends messages"| node_api_client
node_cart_view -->|"checks out"| node_cart_client
node_app -->|"provides shared state"| node_cart_context
node_cart_context -->|"updates cart"| node_cart_client
node_api_client -->|"calls HTTP API"| node_backend_api
node_cart_client -.->|"calls cart endpoints"| node_cart_api
node_backend_api -->|"delegates catalog queries"| node_catalog_service
node_backend_api -->|"includes chat routes"| node_chat_api
node_chat_api -.->|"dispatches chat"| node_assistant
node_assistant -.->|"requests completion"| node_llm
node_llm -->|"calls model"| node_ollama
node_assistant -.->|"dispatches tools"| node_tool_router
node_tool_router -->|"runs validated tool"| node_tools
node_tools -->|"queries products"| node_catalog_service
node_tools -->|"applies filters"| node_search_filters
node_cart_api -->|"applies cart rules"| node_cart_rules
node_cart_rules -->|"reads and updates"| node_cart_store
node_cart_api -->|"handles checkout"| node_orders
node_orders -->|"persists orders"| node_database
node_catalog_service -.->|"queries catalog"| node_database

click node_app "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/App.jsx"
click node_catalog_views "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/pages/ProductList.jsx"
click node_product_detail "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/pages/ProductDetail.jsx"
click node_chat_view "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/pages/Chat.jsx"
click node_cart_view "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/pages/Cart.jsx"
click node_cart_context "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/CartContext.jsx"
click node_api_client "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/api/client.js"
click node_cart_client "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/api/cart.js"
click node_backend_api "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/api.py"
click node_chat_api "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/chat_api.py"
click node_assistant "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/assistant.py"
click node_llm "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/llm.py"
click node_tool_router "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/tool_router.py"
click node_tools "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/tools.py"
click node_search_filters "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/search_filters.py"
click node_catalog_service "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/catalog.py"
click node_cart_api "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/cart_api.py"
click node_cart_rules "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/cart.py"
click node_cart_store "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/carts.py"
click node_orders "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/orders.py"
click node_database "https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/db.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_catalog_views,node_product_detail,node_chat_view,node_cart_view,node_cart_context,node_api_client,node_cart_client toneBlue
class node_backend_api,node_chat_api,node_assistant,node_llm toneAmber
class node_tool_router,node_tools,node_search_filters,node_catalog_service toneMint
class node_cart_api,node_cart_rules,node_orders toneRose
class node_ollama,node_cart_store,node_database,node_user toneIndigo
```

## Components

### Storefront

- [App shell](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Catalog views](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/pages/ProductList.jsx): `frontend/src/pages/ProductList.jsx`
- [Product detail](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/pages/ProductDetail.jsx): `frontend/src/pages/ProductDetail.jsx`
- [Chat view](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/pages/Chat.jsx): `frontend/src/pages/Chat.jsx`
- [Cart and checkout view](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/pages/Cart.jsx): `frontend/src/pages/Cart.jsx`
- [Shared cart state](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/CartContext.jsx): `frontend/src/CartContext.jsx`
- [Catalog and chat client](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Cart API client](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/frontend/src/api/cart.js): `frontend/src/api/cart.js`

### API and orchestration

- [HTTP API](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/api.py): `backend/api.py`
- [Chat endpoint](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/chat_api.py): `backend/chat_api.py`
- [Assistant orchestration](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/assistant.py): `backend/assistant.py`
- [Model client](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/llm.py): `backend/llm.py`

### Catalog and assistant tools

- [Tool validation and routing](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/tool_router.py): `backend/tool_router.py`
- [Catalog tools](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/tools.py): `backend/tools.py`
- [Search filters](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/search_filters.py): `backend/search_filters.py`
- [Catalog queries](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/catalog.py): `backend/catalog.py`

### Cart and orders

- [Cart and order endpoints](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/cart_api.py): `backend/cart_api.py`
- [Cart rules](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/cart.py): `backend/cart.py`
- [Order management](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/orders.py): `backend/orders.py`

### State and model services

- **Ollama model**
- [In-memory carts](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/carts.py): `backend/carts.py`
- [SQLite database](https://github.com/camiguarnieri/mercanova-ai-assistant/blob/main/backend/db.py): `backend/db.py`

### Other components

- **Shopper**

## Connections

- Shopper → App shell: uses
- App shell → Catalog views: shows (evidence: `frontend/src/App.jsx`)
- App shell → Product detail: shows (evidence: `frontend/src/App.jsx`)
- App shell → Chat view: shows (evidence: `frontend/src/App.jsx`)
- App shell → Cart and checkout view: shows (evidence: `frontend/src/App.jsx`)
- Catalog views → Catalog and chat client: requests products (evidence: `frontend/src/pages/ProductList.jsx`)
- Product detail → Catalog and chat client: requests detail (evidence: `frontend/src/pages/ProductDetail.jsx`)
- Chat view → Catalog and chat client: sends messages (evidence: `frontend/src/pages/Chat.jsx`)
- Cart and checkout view → Cart API client: checks out (evidence: `frontend/src/pages/Cart.jsx`)
- App shell → Shared cart state: provides shared state (evidence: `frontend/src/App.jsx`)
- Shared cart state → Cart API client: updates cart (evidence: `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 (evidence: `backend/api.py`)
- HTTP API → Chat endpoint: includes chat routes (evidence: `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 (evidence: `backend/tool_router.py`)
- Catalog tools → Catalog queries: queries products (evidence: `backend/tools.py`)
- Catalog tools → Search filters: applies filters (evidence: `backend/tools.py`)
- Cart and order endpoints → Cart rules: applies cart rules (evidence: `backend/cart_api.py`)
- Cart rules → In-memory carts: reads and updates (evidence: `backend/cart.py`)
- Cart and order endpoints → Order management: handles checkout (evidence: `backend/cart_api.py`)
- Order management → SQLite database: persists orders (evidence: `backend/orders.py`)
- Catalog queries → SQLite database: queries catalog
