ateeb09/shopmind

1. What this repo is

ShopMind is a local prototype for “AI representation optimization” in ecommerce. It is built as a pipeline that analyzes product data, scores how likely an AI shopping agent would reject or prefer items, then presents the results in a dashboard with a mocked “apply fix” loop.

2. Core runtime split

There are two main runtimes: a Python analysis/backend side and a browser UI side. The Python side generates and stores derived results in JSON files; the frontend reads those results and lets the merchant inspect products and apply fixes.

3. Input/state layer

The repository’s primary data inputs are JSON files: products.json for catalog items, store_context.json for merchant/store metadata, and competitor_shadow.json for competitor comparison data. These files represent the source of truth for the analysis run.

4. Pipeline orchestration

shopmind_main.py is the main orchestrator. It ties together ingestion, LLM analysis, deterministic checks, scoring, and store-level aggregation, then writes the final analysis artifacts such as shopmind_results.json.

5. Ingestion boundary

layer1_ingestion.py is the normalization boundary between raw JSON inputs and the rest of the system. Its job is to prepare product/store/competitor records into a consistent shape for downstream evaluation.

6. Dual analysis engine

The analysis core is intentionally split into two parts:

- layer2_llm.py handles the qualitative AI-simulation path, intended to use the Gemini API for reasoning like an AI shopping assistant.

- layer2_deterministic.py handles strict rule-based validation for objective issues such as missing fields or policy/data-quality problems.

This is the repo’s key architectural boundary: flexible LLM judgment plus hard deterministic validation.

7. Scoring and prioritization

layer3_scorer.py merges the LLM and deterministic outputs into actionable product-level scores, including rejection risk / conversion loss style metrics and priority levels. This is where raw findings become ranked merchant actions.

8. Store-level aggregation

layer5_store_summary.py rolls product scores up into a store-wide readiness summary. This produces the top-level “store health” view used by the dashboard, so the UI can show both aggregate readiness and item-level problems.

9. Presentation layer

server.py serves the built results and UI assets to the browser. The client is a static frontend composed of index.html, app.js, and style.css, with assets/ containing screenshots and presentation media. The UI is primarily a dashboard for browsing store summary, product details, and “before vs after” fixes.

10. Closed action loop

User actions in the dashboard write to applied_fixes.json, and mock_shopify_sync.py simulates pushing those fixes back to an ecommerce platform. This keeps the repo’s “apply fix” flow local and demonstrable without live Shopify integration.

11. Derived artifacts and audit trail

shopmind_results.json is the main derived output consumed by the UI. generate_decision_log.py, DECISION_LOG.md, IMPLEMENTATION_DECISIONS.md, FAILURE_HANDLING.md, and LIMITATIONS.md document why the system behaves the way it does, how failures are handled, and what is intentionally mocked or constrained.

12. Important external dependency

The only materially significant external service called out by the repo is the Google Gemini API for the LLM simulation path. Everything else is local and file-based, so the architecture is best understood as an offline analysis engine with a thin local serving layer and a mocked sync boundary.