# gopi0974/ai-smart-cart architecture

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

- Interactive diagram: https://gitdiagram.com/gopi0974/ai-smart-cart
- Repository: https://github.com/gopi0974/ai-smart-cart

## Overview

AuraCart is a smart-cart shopping system: a shopper pairs to a cart, scans products, and has basket placement checked by camera-based rules before checkout. Cart sessions coordinate verification, billing, and security alerts; camera feeds and cart events reach shopper and admin interfaces in real time. The README documents the major capabilities, while the edges below are limited to relationships visible in excerpts or explicitly described there; some frontend-to-backend wiring is therefore shown as unverified.

Main entry points: [`backend/services/cart_manager.py`](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/services/cart_manager.py) (Cart Manager), [`backend/main.py`](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/main.py) (REST and WebSocket API), [`backend/vision/ai_verifier.py`](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/ai_verifier.py) (AI Verifier), [`frontend/shopper/app.js`](https://github.com/gopi0974/ai-smart-cart/blob/main/frontend/shopper/app.js) (Shopper App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Shopping Interfaces"]
  node_shopper_ui["Shopper App<br/>[app.js]"]
  node_barcode_scanner["Barcode Scanner<br/>[scanner.js]"]
  node_cart_camera_ui["Camera Streamer<br/>[cam.js]"]
  node_admin_ui["Admin Dashboard<br/>[admin.js]"]
end

subgraph group_api["Cart Backend"]
  node_backend_api["REST and WebSocket API<br/>[main.py]"]
  node_cart_manager["Cart Manager<br/>[cart_manager.py]"]
end

subgraph group_vision["Vision Verification"]
  node_verifier["AI Verifier<br/>[ai_verifier.py]"]
  node_hand_detector["Hand Detector<br/>[hand_detector.py]"]
  node_vision_model["Vision Model Adapter<br/>[yolo_adapter.py]"]
  node_model_interface["Vision Model Interface<br/>[base_model.py]"]
  node_rule_base["Rule Interface<br/>[base_rule.py]"]
  node_timing_rule["Timing Rule<br/>[timing_rule.py]"]
  node_hand_rule["Hand Entry Rule<br/>[hand_rule.py]"]
  node_visual_rule["Visual Match Rule<br/>[visual_rule.py]"]
  node_rules_config["Rule Configuration<br/>[rules_config.json]"]
end

subgraph group_domain["Cart Domain"]
  node_catalog_data["Product Catalog<br/>[products.json]"]
  node_cart_session["Cart Session State<br/>[cart_state.py]"]
  node_product_model["Product Models<br/>[product.py]"]
  node_billing["Billing and Receipts<br/>[billing_service.py]"]
end

subgraph group_devices["Camera Devices"]
  node_camera_device["Cart Camera"]
end

node_shopper(("Shopper"))

node_shopper -->|"uses"| node_shopper_ui
node_shopper_ui -->|"uses scanner"| node_barcode_scanner
node_shopper_ui -.->|"pairs and shops"| node_backend_api
node_barcode_scanner -.->|"submits scans"| node_backend_api
node_cart_camera_ui -.->|"streams frames"| node_backend_api
node_camera_device -->|"uploads frames"| node_backend_api
node_backend_api -->|"routes cart actions"| node_cart_manager
node_backend_api -.->|"broadcasts events"| node_admin_ui
node_backend_api -.->|"broadcasts events"| node_shopper_ui
node_admin_ui -.->|"monitors carts"| node_backend_api
node_cart_manager -->|"loads catalog"| node_catalog_data
node_cart_manager -->|"updates sessions"| node_cart_session
node_cart_manager -->|"creates cart items"| node_product_model
node_cart_manager -->|"requests verification"| node_verifier
node_cart_manager -->|"calculates totals"| node_billing
node_verifier -->|"processes frames"| node_hand_detector
node_verifier -->|"detects objects"| node_vision_model
node_verifier -->|"evaluates timing"| node_timing_rule
node_verifier -->|"evaluates hand events"| node_hand_rule
node_verifier -->|"evaluates visual match"| node_visual_rule
node_verifier -->|"loads settings"| node_rules_config
node_vision_model -->|"implements interface"| node_model_interface
node_timing_rule -->|"implements rule"| node_rule_base
node_hand_rule -->|"implements rule"| node_rule_base
node_visual_rule -->|"implements rule"| node_rule_base
node_visual_rule -->|"compares product traits"| node_product_model
node_cart_manager -.->|"sends security countdown"| node_shopper_ui
node_cart_manager -.->|"escalates security alerts"| node_admin_ui

click node_shopper_ui "https://github.com/gopi0974/ai-smart-cart/blob/main/frontend/shopper/app.js"
click node_barcode_scanner "https://github.com/gopi0974/ai-smart-cart/blob/main/frontend/shopper/scanner.js"
click node_cart_camera_ui "https://github.com/gopi0974/ai-smart-cart/blob/main/frontend/cart_cam/cam.js"
click node_admin_ui "https://github.com/gopi0974/ai-smart-cart/blob/main/frontend/admin/admin.js"
click node_backend_api "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/main.py"
click node_cart_manager "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/services/cart_manager.py"
click node_catalog_data "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/data/products.json"
click node_cart_session "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/models/cart_state.py"
click node_product_model "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/models/product.py"
click node_billing "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/services/billing_service.py"
click node_verifier "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/ai_verifier.py"
click node_hand_detector "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/hand_detector.py"
click node_vision_model "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/models/yolo_adapter.py"
click node_model_interface "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/models/base_model.py"
click node_rule_base "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/rules/base_rule.py"
click node_timing_rule "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/rules/timing_rule.py"
click node_hand_rule "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/rules/hand_rule.py"
click node_visual_rule "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/rules/visual_rule.py"
click node_camera_device "https://github.com/gopi0974/ai-smart-cart/blob/main/esp32_cam/AuraCart_ESP32_CAM.ino"
click node_rules_config "https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/rules_config.json"

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_shopper_ui,node_barcode_scanner,node_cart_camera_ui,node_admin_ui toneBlue
class node_backend_api,node_cart_manager toneAmber
class node_verifier,node_hand_detector,node_vision_model,node_model_interface,node_rule_base,node_timing_rule,node_hand_rule,node_visual_rule,node_rules_config toneMint
class node_catalog_data,node_cart_session,node_product_model,node_billing toneRose
class node_camera_device,node_shopper toneIndigo
```

## Components

### Shopping Interfaces

- [Shopper App](https://github.com/gopi0974/ai-smart-cart/blob/main/frontend/shopper/app.js): `frontend/shopper/app.js`
- [Barcode Scanner](https://github.com/gopi0974/ai-smart-cart/blob/main/frontend/shopper/scanner.js): `frontend/shopper/scanner.js`
- [Camera Streamer](https://github.com/gopi0974/ai-smart-cart/blob/main/frontend/cart_cam/cam.js): `frontend/cart_cam/cam.js`
- [Admin Dashboard](https://github.com/gopi0974/ai-smart-cart/blob/main/frontend/admin/admin.js): `frontend/admin/admin.js`

### Cart Backend

- [REST and WebSocket API](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/main.py): `backend/main.py`
- [Cart Manager](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/services/cart_manager.py): `backend/services/cart_manager.py`

### Vision Verification

- [AI Verifier](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/ai_verifier.py): `backend/vision/ai_verifier.py`
- [Hand Detector](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/hand_detector.py): `backend/vision/hand_detector.py`
- [Vision Model Adapter](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/models/yolo_adapter.py): `backend/vision/models/yolo_adapter.py`
- [Vision Model Interface](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/models/base_model.py): `backend/vision/models/base_model.py`
- [Rule Interface](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/rules/base_rule.py): `backend/vision/rules/base_rule.py`
- [Timing Rule](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/rules/timing_rule.py): `backend/vision/rules/timing_rule.py`
- [Hand Entry Rule](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/rules/hand_rule.py): `backend/vision/rules/hand_rule.py`
- [Visual Match Rule](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/rules/visual_rule.py): `backend/vision/rules/visual_rule.py`
- [Rule Configuration](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/vision/rules_config.json): `backend/vision/rules_config.json`

### Cart Domain

- [Product Catalog](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/data/products.json): `backend/data/products.json`
- [Cart Session State](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/models/cart_state.py): `backend/models/cart_state.py`
- [Product Models](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/models/product.py): `backend/models/product.py`
- [Billing and Receipts](https://github.com/gopi0974/ai-smart-cart/blob/main/backend/services/billing_service.py): `backend/services/billing_service.py`

### Camera Devices

- [Cart Camera](https://github.com/gopi0974/ai-smart-cart/blob/main/esp32_cam/AuraCart_ESP32_CAM.ino): `esp32_cam/AuraCart_ESP32_CAM.ino`

### Other components

- **Shopper**

## Connections

- Shopper → Shopper App: uses (evidence: `README.md`)
- Shopper App → Barcode Scanner: uses scanner (evidence: `README.md`)
- Shopper App → REST and WebSocket API: pairs and shops
- Barcode Scanner → REST and WebSocket API: submits scans
- Camera Streamer → REST and WebSocket API: streams frames (evidence: `README.md`)
- Cart Camera → REST and WebSocket API: uploads frames (evidence: `backend/main.py`)
- REST and WebSocket API → Cart Manager: routes cart actions (evidence: `backend/main.py`)
- REST and WebSocket API → Admin Dashboard: broadcasts events (evidence: `README.md`)
- REST and WebSocket API → Shopper App: broadcasts events (evidence: `README.md`)
- Admin Dashboard → REST and WebSocket API: monitors carts (evidence: `README.md`)
- Cart Manager → Product Catalog: loads catalog (evidence: `backend/services/cart_manager.py`)
- Cart Manager → Cart Session State: updates sessions (evidence: `backend/services/cart_manager.py`)
- Cart Manager → Product Models: creates cart items (evidence: `backend/services/cart_manager.py`)
- Cart Manager → AI Verifier: requests verification (evidence: `backend/services/cart_manager.py`)
- Cart Manager → Billing and Receipts: calculates totals (evidence: `backend/services/cart_manager.py`)
- AI Verifier → Hand Detector: processes frames (evidence: `backend/vision/ai_verifier.py`)
- AI Verifier → Vision Model Adapter: detects objects (evidence: `backend/vision/ai_verifier.py`)
- AI Verifier → Timing Rule: evaluates timing (evidence: `backend/vision/ai_verifier.py`)
- AI Verifier → Hand Entry Rule: evaluates hand events (evidence: `backend/vision/ai_verifier.py`)
- AI Verifier → Visual Match Rule: evaluates visual match (evidence: `backend/vision/ai_verifier.py`)
- AI Verifier → Rule Configuration: loads settings (evidence: `README.md`)
- Vision Model Adapter → Vision Model Interface: implements interface (evidence: `backend/vision/models/yolo_adapter.py`)
- Timing Rule → Rule Interface: implements rule (evidence: `backend/vision/rules/timing_rule.py`)
- Hand Entry Rule → Rule Interface: implements rule (evidence: `backend/vision/rules/hand_rule.py`)
- Visual Match Rule → Rule Interface: implements rule (evidence: `backend/vision/rules/visual_rule.py`)
- Visual Match Rule → Product Models: compares product traits (evidence: `backend/vision/rules/visual_rule.py`)
- Cart Manager → Shopper App: sends security countdown (evidence: `README.md`)
- Cart Manager → Admin Dashboard: escalates security alerts (evidence: `README.md`)
