CartCompass — Say What You Want. We’ll Find the Way.

## Inspiration

Online shopping offers endless choice, but finding the right product often feels like work. Shoppers must translate a simple intention—such as “I need comfortable running shoes around $100”—into filters, categories, keywords, and repeated searches.

Merchants face a different problem. Many still manage their catalogues in spreadsheets, and almost every spreadsheet uses a different structure. One merchant might label a column price, another might use unit cost, while another might call it retail value. Before these products can become searchable, their data must be cleaned and standardized.

CartCompass was inspired by the idea that neither side should have to adapt to rigid software:

Merchants should be able to upload the catalogue format they already use.
Customers should be able to shop using ordinary language.
AI should help interpret intent without becoming the source of truth for prices, inventory, or payments.

Our goal was to build one deliberate path from messy merchant data to grounded product discovery and a safe test checkout.

## What It Does

CartCompass is a multi-merchant conversational commerce platform.

Merchants can create a verified account, upload catalogues in formats such as CSV, Excel, Google Sheets, PDF, or an image, and publish the valid products to their own storefront. The platform maps different column names into a common product model while preserving unmapped information and reporting invalid rows.

Customers can then:

Browse an individual merchant or the combined All Products catalogue.
Describe what they want in natural language.
Receive recommendations grounded in published product data.
Compare products and ask follow-up questions.
Add or remove products through chat or direct controls.
Review a server-calculated order total.
Explicitly confirm a clearly labelled Visa test payment.

Each catalogue, conversation, cart, order, and payment attempt remains associated with the correct merchant.

## How We Built It

CartCompass uses a dependency-light JavaScript stack:

Vanilla HTML, CSS, and JavaScript for the interface
Node.js 20 for the server and REST API
Vercel for static hosting and serverless execution
OpenAI’s Responses API with strict tools for conversational shopping
Upstash Redis for optional durable production state
Visa Acceptance Solutions for the optional sandbox payment path
@e965/xlsx and pdfjs-dist for catalogue ingestion
Node’s native crypto APIs for password hashing, sessions, and sensitive merchant data
Node’s built-in test runner for automated tests and conversational evaluations

### Catalogue normalization

Every imported catalogue is converted into a canonical product structure containing fields such as name, price, currency, brand, category, inventory, and availability.

Common column names are mapped deterministically. When an unusual merchant-specific schema cannot be recognized locally, an optional OpenAI-backed inference step can suggest header mappings. Those suggestions are restricted to the uploaded headers and known destination fields; the model cannot invent product values.

Valid rows are published automatically, while invalid rows are returned with their source data and an explanation. If an import contains no valid products, the existing storefront remains unchanged.

### Grounded conversational shopping

We designed the assistant as an interface to backend tools—not as an authority over store data.

The model can request actions such as searching, comparing products, updating the cart, or preparing checkout. The server validates every tool argument and product ID against the current merchant and live catalogue.

Conceptually, product ranking combines textual relevance, preference matches, brand and category matches, and distance from the shopper’s approximate budget:

$$ S(p,q) = R_{\text{text}}(p,q)

R_{\text{brand}}(p,q)
R_{\text{category}}(p,q)
R_{\text{preferences}}(p,q)
R_{\text{budget}}(p,q) $$

The budget component is a ranking preference rather than a hard filter. A simplified representation is:

$$ R_{\text{budget}}(p,q) \propto -\frac{|\operatorname{price}(p)-b|}{\max(b,1)} $$

where (b) is the shopper’s approximate budget. This lets CartCompass show a highly relevant product slightly above budget instead of hiding it completely.

The model receives only validated results and then explains them conversationally. Prices, inventory, quantities, and totals always come from server state.

### Safe checkout

Checkout is intentionally separated from ordinary conversation.

The server calculates the total as:

$$ T=\sum_{i=1}^{n} q_i p_i $$

where (q_i) is the validated quantity and (p_i) is the current catalogue price.

Before invoking a payment adapter, CartCompass verifies that the customer’s confirmation matches the most recently reviewed products, quantities, prices, currency, and total. The default demonstration uses deterministic approved and declined Visa test outcomes and never performs a real charge.

## Challenges We Faced

### Normalizing inconsistent merchant data

Real catalogues contain unpredictable headers, delimiters, currencies, missing fields, European decimal formats, and extra columns. The difficult part was accepting useful variation without silently corrupting product data.

We addressed this with layered processing: deterministic parsing first, constrained inference when configured, schema validation afterward, and row-level diagnostics throughout.

### Keeping AI grounded

A fluent assistant can easily sound confident about information that is missing. It can also misunderstand a comparison as a request to purchase something.

We created strict shopping tools, validated product IDs against the active storefront, bounded conversation memory, and explicitly prohibited comparison or explanation requests from mutating the cart. Configured AI failures are reported clearly instead of being hidden behind fabricated results.

### Maintaining merchant isolation

A multi-merchant experience creates subtle risks. Search results, carts, orders, and payment records must never leak from one storefront into another.

We treated the merchant identifier as part of the complete server-side data flow and tested cross-merchant product selection, protected portal access, and catalogue publication boundaries.

### Drawing a safe payment boundary

Conversational checkout must not let a vague message trigger a payment. It was challenging to make the experience feel smooth while still demanding deliberate confirmation.

Our solution was to separate discovery, cart management, checkout review, confirmation, and payment into distinct states. We also reject card-like data from chat and catalogue inputs and retain only non-sensitive payment references.

### Supporting serverless persistence

In-memory state is convenient locally but unreliable across serverless instances. We introduced an optional Upstash persistence adapter with a distributed write lock so catalogues, sessions, carts, and orders can survive instance changes without changing the local development experience.

## What We Learned

The biggest lesson was that trustworthy AI commerce depends less on generating persuasive text and more on controlling authority.

The model is excellent at understanding language and explaining choices. The backend must remain responsible for identity, merchant scope, product validity, inventory, prices, totals, and payment readiness.

We also learned that graceful handling of imperfect data is more valuable than demanding perfect input. Merchants should see exactly which rows were accepted, which were rejected, and why.

Finally, we learned to make demo boundaries visible. CartCompass clearly reports whether it is using OpenAI or the deterministic fallback, and whether checkout is a local test simulation or a configured sandbox integration. Transparency makes the experience easier to trust and evaluate.

CartCompass demonstrates a practical foundation for conversational commerce: different catalogues become one consistent shopping language, while every important commercial decision remains validated by the server.