# ateeb09/shopmind architecture

> Architecture diagram of the GitHub repository ateeb09/shopmind, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ateeb09/shopmind
- Repository: https://github.com/ateeb09/shopmind

## Overview

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.

Main entry points: [`shopmind_main.py`](https://github.com/ateeb09/shopmind/blob/main/shopmind_main.py) (Main orchestrator), [`layer1_ingestion.py`](https://github.com/ateeb09/shopmind/blob/main/layer1_ingestion.py) (Ingestion), [`app.js`](https://github.com/ateeb09/shopmind/blob/main/app.js) (UI logic), [`shopmind_results.json`](https://github.com/ateeb09/shopmind/blob/main/shopmind_results.json) (Results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs & artifacts"]
  node_products_json["Products<br/>catalog input<br/>[products.json]"]
  node_store_context_json["Store context<br/>store input<br/>[store_context.json]"]
  node_competitor_shadow_json["Competitor data<br/>comparison input"]
  node_applied_fixes_json["Applied fixes<br/>action state<br/>[applied_fixes.json]"]
  node_shopmind_results_json["Results<br/>derived output"]
end

subgraph group_backend["Python pipeline"]
  node_shopmind_main_py["Main orchestrator<br/>pipeline entry<br/>[shopmind_main.py]"]
  node_layer1_ingestion_py["Ingestion<br/>normalization layer"]
  node_layer2_llm_py["LLM analysis<br/>Gemini reasoning<br/>[layer2_llm.py]"]
  node_layer2_deterministic_py["Deterministic checks<br/>rule validation"]
  node_layer3_scorer_py["Scorer<br/>prioritization<br/>[layer3_scorer.py]"]
  node_layer5_store_summary_py["Store summary<br/>rollup"]
  node_mock_shopify_sync_py["Mock sync<br/>simulated external sync"]
end

subgraph group_frontend["Browser UI"]
  node_server_py["Server<br/>static serving<br/>[server.py]"]
  node_index_html["Dashboard shell<br/>ui entry<br/>[index.html]"]
  node_app_js["UI logic<br/>client runtime<br/>[app.js]"]
  node_style_css["Styles<br/>presentation<br/>[style.css]"]
end

node_products_json -->|"raw catalog"| node_layer1_ingestion_py
node_store_context_json -->|"store metadata"| node_layer1_ingestion_py
node_competitor_shadow_json -->|"competitor data"| node_layer1_ingestion_py
node_layer1_ingestion_py -->|"prepared records"| node_layer2_llm_py
node_layer1_ingestion_py -->|"prepared records"| node_layer2_deterministic_py
node_layer2_llm_py -->|"qualitative findings"| node_layer3_scorer_py
node_layer2_deterministic_py -->|"rule findings"| node_layer3_scorer_py
node_layer3_scorer_py -->|"ranked products"| node_layer5_store_summary_py
node_layer5_store_summary_py -->|"summary output"| node_shopmind_results_json
node_shopmind_main_py -->|"orchestrates"| node_layer1_ingestion_py
node_shopmind_main_py -->|"orchestrates"| node_layer2_llm_py
node_shopmind_main_py -->|"orchestrates"| node_layer2_deterministic_py
node_shopmind_main_py -->|"orchestrates"| node_layer3_scorer_py
node_shopmind_main_py -->|"orchestrates"| node_layer5_store_summary_py
node_shopmind_main_py -->|"writes"| node_shopmind_results_json
node_applied_fixes_json -->|"fix state"| node_mock_shopify_sync_py
node_mock_shopify_sync_py -.->|"feedback loop"| node_shopmind_results_json
node_shopmind_results_json -->|"served data"| node_server_py
node_index_html -->|"loads"| node_app_js
node_app_js -->|"uses"| node_style_css
node_server_py -->|"serves"| node_index_html
node_server_py -->|"serves"| node_app_js
node_server_py -->|"serves"| node_style_css
node_app_js -->|"reads"| node_shopmind_results_json
node_app_js -->|"writes"| node_applied_fixes_json

click node_products_json "https://github.com/ateeb09/shopmind/blob/main/products.json"
click node_store_context_json "https://github.com/ateeb09/shopmind/blob/main/store_context.json"
click node_competitor_shadow_json "https://github.com/ateeb09/shopmind/blob/main/competitor_shadow.json"
click node_applied_fixes_json "https://github.com/ateeb09/shopmind/blob/main/applied_fixes.json"
click node_shopmind_results_json "https://github.com/ateeb09/shopmind/blob/main/shopmind_results.json"
click node_shopmind_main_py "https://github.com/ateeb09/shopmind/blob/main/shopmind_main.py"
click node_layer1_ingestion_py "https://github.com/ateeb09/shopmind/blob/main/layer1_ingestion.py"
click node_layer2_llm_py "https://github.com/ateeb09/shopmind/blob/main/layer2_llm.py"
click node_layer2_deterministic_py "https://github.com/ateeb09/shopmind/blob/main/layer2_deterministic.py"
click node_layer3_scorer_py "https://github.com/ateeb09/shopmind/blob/main/layer3_scorer.py"
click node_layer5_store_summary_py "https://github.com/ateeb09/shopmind/blob/main/layer5_store_summary.py"
click node_mock_shopify_sync_py "https://github.com/ateeb09/shopmind/blob/main/mock_shopify_sync.py"
click node_server_py "https://github.com/ateeb09/shopmind/blob/main/server.py"
click node_index_html "https://github.com/ateeb09/shopmind/blob/main/index.html"
click node_app_js "https://github.com/ateeb09/shopmind/blob/main/app.js"
click node_style_css "https://github.com/ateeb09/shopmind/blob/main/style.css"

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_products_json,node_store_context_json,node_competitor_shadow_json,node_applied_fixes_json,node_shopmind_results_json toneBlue
class node_shopmind_main_py,node_layer1_ingestion_py,node_layer2_llm_py,node_layer2_deterministic_py,node_layer3_scorer_py,node_layer5_store_summary_py,node_mock_shopify_sync_py toneAmber
class node_server_py,node_index_html,node_app_js,node_style_css toneMint
```

## Components

### Inputs & artifacts

Source JSON files, derived results, and fix state used by the analysis and UI.

- [Products](https://github.com/ateeb09/shopmind/blob/main/products.json): catalog input · Primary product catalog source of truth. · `products.json`
- [Store context](https://github.com/ateeb09/shopmind/blob/main/store_context.json): store input · Merchant and store metadata used during analysis. · `store_context.json`
- [Competitor data](https://github.com/ateeb09/shopmind/blob/main/competitor_shadow.json): comparison input · Competitor comparison dataset for relative analysis. · `competitor_shadow.json`
- [Applied fixes](https://github.com/ateeb09/shopmind/blob/main/applied_fixes.json): action state · Local record of user-selected fixes from the dashboard. · `applied_fixes.json`
- [Results](https://github.com/ateeb09/shopmind/blob/main/shopmind_results.json): derived output · Main analysis artifact consumed by the UI. · `shopmind_results.json`

### Python pipeline

Normalization, analysis, scoring, aggregation, orchestration, and mocked sync.

- [Main orchestrator](https://github.com/ateeb09/shopmind/blob/main/shopmind_main.py): pipeline entry · Coordinates ingestion, analysis, scoring, aggregation, and output writing. · `shopmind_main.py`
- [Ingestion](https://github.com/ateeb09/shopmind/blob/main/layer1_ingestion.py): normalization layer · Normalizes raw store, product, and competitor records. · `layer1_ingestion.py`
- [LLM analysis](https://github.com/ateeb09/shopmind/blob/main/layer2_llm.py): Gemini reasoning · Qualitative AI-simulation path for assistant-style judgments. · `layer2_llm.py`
- [Deterministic checks](https://github.com/ateeb09/shopmind/blob/main/layer2_deterministic.py): rule validation · Hard validation for missing fields, policy, and data-quality issues. · `layer2_deterministic.py`
- [Scorer](https://github.com/ateeb09/shopmind/blob/main/layer3_scorer.py): prioritization · Merges analysis outputs into product risk and priority scores. · `layer3_scorer.py`
- [Store summary](https://github.com/ateeb09/shopmind/blob/main/layer5_store_summary.py): rollup · Aggregates product outcomes into store-level readiness signals. · `layer5_store_summary.py`
- [Mock sync](https://github.com/ateeb09/shopmind/blob/main/mock_shopify_sync.py): simulated external sync · Simulates sending applied fixes back to an ecommerce platform. · `mock_shopify_sync.py`

### Browser UI

Static presentation layer served to the browser.

- [Server](https://github.com/ateeb09/shopmind/blob/main/server.py): static serving · Serves results and UI assets to the browser. · `server.py`
- [Dashboard shell](https://github.com/ateeb09/shopmind/blob/main/index.html): ui entry · Root HTML for the merchant dashboard. · `index.html`
- [UI logic](https://github.com/ateeb09/shopmind/blob/main/app.js): client runtime · Browser-side interaction and rendering logic. · `app.js`
- [Styles](https://github.com/ateeb09/shopmind/blob/main/style.css): presentation · Visual styling for the dashboard. · `style.css`

## Connections

- Products → Ingestion: raw catalog · Product records are normalized before analysis.
- Store context → Ingestion: store metadata · Merchant context is ingested with the catalog.
- Competitor data → Ingestion: competitor data · Comparison inputs are normalized for downstream use.
- Ingestion → LLM analysis: prepared records · Normalized records feed the LLM-based evaluation path.
- Ingestion → Deterministic checks: prepared records · Normalized records feed deterministic validation.
- LLM analysis → Scorer: qualitative findings · LLM judgments contribute to prioritization.
- Deterministic checks → Scorer: rule findings · Objective issues contribute to scoring and priority.
- Scorer → Store summary: ranked products · Product scores roll up into store readiness.
- Store summary → Results: summary output · Store and product results are written to the main artifact.
- Main orchestrator → Ingestion: orchestrates · Main pipeline entry coordinates ingestion.
- Main orchestrator → LLM analysis: orchestrates · Main pipeline entry coordinates LLM analysis.
- Main orchestrator → Deterministic checks: orchestrates · Main pipeline entry coordinates deterministic checks.
- Main orchestrator → Scorer: orchestrates · Main pipeline entry coordinates scoring.
- Main orchestrator → Store summary: orchestrates · Main pipeline entry coordinates aggregation.
- Main orchestrator → Results: writes · Pipeline emits the derived analysis artifact.
- Applied fixes → Mock sync: fix state · User-selected fixes are used by the mock sync loop.
- Mock sync → Results: feedback loop · Simulated sync updates the local result flow.
- Results → Server: served data · Server exposes generated results to the browser.
- Dashboard shell → UI logic: loads · Dashboard shell bootstraps client logic.
- UI logic → Styles: uses · Client UI relies on shared styling.
- Server → Dashboard shell: serves · Server delivers the dashboard shell.
- Server → UI logic: serves · Server delivers client-side application logic.
- Server → Styles: serves · Server delivers presentation assets.
- UI logic → Results: reads · Browser UI consumes analysis results.
- UI logic → Applied fixes: writes · Dashboard actions persist fix choices locally.