# basil23l034ec-ux/dummy architecture

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

- Interactive diagram: https://gitdiagram.com/basil23l034ec-ux/dummy
- Repository: https://github.com/basil23l034ec-ux/dummy

## Overview

1. **System shape**
   - This repo is a **multi-client smart trolley platform** centered on a single **Flask backend**.
   - The backend is the hub for cart state, product/inventory data, checkout, analytics, and chatbot requests.

2. **Core backend service**
   - `backend/app.py` is the main runtime entry point.
   - `backend/config.py` and `backend/db.py` define environment/configuration and data access/persistence boundaries.
   - The backend exposes the API surface used by all clients: products, RFID ingestion, cart, checkout, inventory, sales analytics, and chat.

3. **Client-facing UIs are split by role**
   - `customer-frontend/` is the shopper experience: product browsing, search, live cart, RFID simulation, and checkout.
   - `admin-frontend/` is the shopkeeper dashboard: KPI tiles, sales reports, inventory, settings, alerts, customers, trolleys, and logistics views.
   - `worker-frontend/` is a third operational UI with its own login and worker console, likely for staff tasks distinct from admin and shopper flows.

4. **Frontend architecture**
   - Each frontend is organized as **templates + static assets**.
   - JavaScript is the main integration layer to the backend:
     - customer: `main.js`, `connect.js`, `api.js`, `i18n.js`
     - admin: `admin.js`, `api.js`
     - worker: `worker.js`
   - CSS and images are isolated per frontend, so the visual layers are decoupled even though they share the same backend API.

5. **Main real-time data flow**
   - The key loop is: **RFID tag scanned → backend `/rfid` endpoint → cart state updated → frontend refreshes cart totals and product state**.
   - This is the central transaction path of the whole system and the most important boundary in an architecture diagram.
   - The customer UI includes a simulation path for testing RFID scans without hardware.

6. **Checkout and inventory flow**
   - Checkout is handled centrally by the backend via `/checkout`.
   - Inventory is updated from the backend side, so stock changes are not managed inside the frontends.
   - The admin UI reads inventory status and sales outputs from backend endpoints rather than maintaining its own copy.

7. **Analytics and admin reporting**
   - `/admin/data`, `/sales/daily`, and `/sales/monthly` power the admin dashboard and reporting views.
   - This implies a read-optimized analytics layer in the backend that aggregates operational data into KPIs and time-series summaries.
   - The admin frontend is therefore a consumer of derived data, not just raw product/cart records.

8. **Hardware integration**
   - `hardware/esp8266_rfid.ino` is the device-side component.
   - The ESP8266 reads RFID tags and sends HTTP requests to the Flask server, making the hardware an external event source rather than a peer service.
   - The README positions the Raspberry Pi as the backend host and the ESP8266 as the edge client.

9. **Operational and support tooling**
   - The backend contains multiple `debug_*.py` and `verify_*.py` scripts, which act as diagnostics and regression checks around API behavior, auth, layout/theme changes, deletion, search, image editing, worker flows, and crash/debug scenarios.
   - These are not part of the end-user runtime path, but they are important for understanding how the system is validated and maintained.

10. **Documentation and feature modules**
   - The top-level markdown files (`SYSTEM_DOCUMENTATION.md`, `SETUP_AND_DEPLOYMENT.md`, and feature-specific docs like `PROMOTION_SYSTEM.md`, `LANGUAGE_FEATURE.md`) suggest the system is modular and has several optional product features.
   - `add-spin-wheel.sh` and the feature docs indicate some UI/behavior extensions are managed as add-ons rather than embedded in the core backend.

11. **Primary architectural boundaries**
   - **Hardware boundary:** RFID reader devices only talk to the backend over HTTP.
   - **Service boundary:** the Flask backend owns business logic and state transitions.
   - **Presentation boundary:** each frontend renders its own role-specific experience and calls backend APIs for data.
   - **Data boundary:** persistence/aggregation is centralized in the backend layer, not duplicated across clients.

12. **What to draw in the diagram**
   - Place the **Flask backend** in the center.
   - Connect **ESP8266 RFID hardware** into `/rfid`.
   - Connect **customer, admin, and worker frontends** to the backend via API calls.
   - Show **cart/checkout/inventory/analytics/chat** as backend domains, with admin analytics and customer cart flow as the two most important data paths.

Main entry points: [`backend/app.py`](https://github.com/basil23l034ec-ux/dummy/blob/main/backend/app.py) (Flask app), [`admin-frontend/static/js/api.js`](https://github.com/basil23l034ec-ux/dummy/blob/main/admin-frontend/static/js/api.js) (Admin API), [`customer-frontend/static/js/main.js`](https://github.com/basil23l034ec-ux/dummy/blob/main/customer-frontend/static/js/main.js) (Shop UI), [`customer-frontend/static/js/api.js`](https://github.com/basil23l034ec-ux/dummy/blob/main/customer-frontend/static/js/api.js) (Client API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_app["Flask app<br/>runtime entry<br/>[app.py]"]
  node_backend_config["Config<br/>[config.py]"]
  node_backend_db[("Data layer<br/>persistence<br/>[db.py]")]
  node_backend_rfid{{"RFID ingest<br/>API domain"}}
  node_backend_cart["Cart state<br/>API domain"]
  node_backend_checkout["Checkout<br/>API domain"]
  node_backend_inventory["Inventory<br/>API domain"]
  node_backend_analytics["Analytics<br/>aggregations"]
  node_backend_chat(("Chatbot<br/>API domain"))
end

subgraph group_customer["Customer UI"]
  node_customer_main["Shop UI<br/>frontend entry<br/>[main.js]"]
  node_customer_api["Client API<br/>frontend integration<br/>[api.js]"]
  node_customer_connect["RFID sim<br/>frontend integration<br/>[connect.js]"]
  node_customer_i18n["Languages<br/>frontend integration<br/>[i18n.js]"]
end

subgraph group_admin["Admin UI"]
  node_admin_main["Admin dashboard<br/>frontend entry<br/>[admin.js]"]
  node_admin_api["Admin API<br/>frontend integration<br/>[api.js]"]
end

subgraph group_worker["Worker UI"]
  node_worker_main["Worker console<br/>frontend entry<br/>[worker.js]"]
end

subgraph group_hardware["Hardware"]
  node_hardware_rfid{{"ESP8266 RFID<br/>edge device<br/>[esp8266_rfid.ino]"}}
end

subgraph group_support["Support"]
  node_backend_ops["Diagnostics<br/>tooling<br/>[debug_api.py]"]
  node_docs["Docs<br/>documentation<br/>[README.md]"]
end

node_hardware_rfid -->|"HTTP scan"| node_backend_rfid
node_backend_app -->|"loads"| node_backend_config
node_backend_app -->|"uses"| node_backend_db
node_backend_app -->|"routes"| node_backend_rfid
node_backend_app -->|"routes"| node_backend_cart
node_backend_app -->|"routes"| node_backend_checkout
node_backend_app -->|"routes"| node_backend_inventory
node_backend_app -->|"routes"| node_backend_analytics
node_backend_app -->|"routes"| node_backend_chat
node_customer_main -->|"calls"| node_customer_api
node_customer_main -->|"uses"| node_customer_connect
node_customer_main -->|"uses"| node_customer_i18n
node_customer_api -->|"API"| node_backend_app
node_admin_main -->|"calls"| node_admin_api
node_admin_api -->|"reads"| node_backend_analytics
node_admin_api -->|"reads"| node_backend_inventory
node_admin_api -->|"API"| node_backend_app
node_worker_main -->|"API"| node_backend_app
node_backend_ops -.->|"checks"| node_backend_app
node_docs -.->|"describes"| node_backend_app

click node_backend_app "https://github.com/basil23l034ec-ux/dummy/blob/main/backend/app.py"
click node_backend_config "https://github.com/basil23l034ec-ux/dummy/blob/main/backend/config.py"
click node_backend_db "https://github.com/basil23l034ec-ux/dummy/blob/main/backend/db.py"
click node_backend_ops "https://github.com/basil23l034ec-ux/dummy/blob/main/backend/debug_api.py"
click node_customer_main "https://github.com/basil23l034ec-ux/dummy/blob/main/customer-frontend/static/js/main.js"
click node_customer_api "https://github.com/basil23l034ec-ux/dummy/blob/main/customer-frontend/static/js/api.js"
click node_customer_connect "https://github.com/basil23l034ec-ux/dummy/blob/main/customer-frontend/static/js/connect.js"
click node_customer_i18n "https://github.com/basil23l034ec-ux/dummy/blob/main/customer-frontend/static/js/i18n.js"
click node_admin_main "https://github.com/basil23l034ec-ux/dummy/blob/main/admin-frontend/static/js/admin.js"
click node_admin_api "https://github.com/basil23l034ec-ux/dummy/blob/main/admin-frontend/static/js/api.js"
click node_worker_main "https://github.com/basil23l034ec-ux/dummy/blob/main/worker-frontend/static/worker.js"
click node_hardware_rfid "https://github.com/basil23l034ec-ux/dummy/blob/main/hardware/esp8266_rfid.ino"
click node_docs "https://github.com/basil23l034ec-ux/dummy/blob/main/README.md"

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_backend_app,node_backend_config,node_backend_db,node_backend_rfid,node_backend_cart,node_backend_checkout,node_backend_inventory,node_backend_analytics,node_backend_chat toneBlue
class node_customer_main,node_customer_api,node_customer_connect,node_customer_i18n toneAmber
class node_admin_main,node_admin_api toneMint
class node_worker_main toneRose
class node_hardware_rfid toneIndigo
class node_backend_ops,node_docs toneTeal
```

## Components

### Backend

Flask service and operational scripts

- [Flask app](https://github.com/basil23l034ec-ux/dummy/blob/main/backend/app.py): runtime entry · Main backend process and API hub · `backend/app.py`
- [Config](https://github.com/basil23l034ec-ux/dummy/blob/main/backend/config.py): environment config · Runtime settings and feature flags · `backend/config.py`
- [Data layer](https://github.com/basil23l034ec-ux/dummy/blob/main/backend/db.py): persistence · Database and storage access boundary · `backend/db.py`
- **RFID ingest**: API domain · Receives tag scans and updates cart state
- **Cart state**: API domain · Maintains live trolley contents and totals
- **Checkout**: API domain · Handles purchase finalization and stock changes
- **Inventory**: API domain · Owns product and stock updates
- **Analytics**: aggregations · Produces sales summaries and KPI data
- **Chatbot**: API domain · Backend chat and assistant requests

### Customer UI

Shopper-facing frontend

- [Shop UI](https://github.com/basil23l034ec-ux/dummy/blob/main/customer-frontend/static/js/main.js): frontend entry · Customer browsing and cart experience · `customer-frontend/static/js/main.js`
- [Client API](https://github.com/basil23l034ec-ux/dummy/blob/main/customer-frontend/static/js/api.js): frontend integration · Customer-side backend requests · `customer-frontend/static/js/api.js`
- [RFID sim](https://github.com/basil23l034ec-ux/dummy/blob/main/customer-frontend/static/js/connect.js): frontend integration · Customer-side device connection and simulation · `customer-frontend/static/js/connect.js`
- [Languages](https://github.com/basil23l034ec-ux/dummy/blob/main/customer-frontend/static/js/i18n.js): frontend integration · Customer UI localization support · `customer-frontend/static/js/i18n.js`

### Admin UI

Shopkeeper dashboard frontend

- [Admin dashboard](https://github.com/basil23l034ec-ux/dummy/blob/main/admin-frontend/static/js/admin.js): frontend entry · Shopkeeper reporting and control console · `admin-frontend/static/js/admin.js`
- [Admin API](https://github.com/basil23l034ec-ux/dummy/blob/main/admin-frontend/static/js/api.js): frontend integration · Admin-side backend requests · `admin-frontend/static/js/api.js`

### Worker UI

Staff console frontend

- [Worker console](https://github.com/basil23l034ec-ux/dummy/blob/main/worker-frontend/static/worker.js): frontend entry · Staff login and operational console · `worker-frontend/static/worker.js`

### Hardware

RFID edge device

- [ESP8266 RFID](https://github.com/basil23l034ec-ux/dummy/blob/main/hardware/esp8266_rfid.ino): edge device · Scans RFID tags and sends HTTP events · `hardware/esp8266_rfid.ino`

### Support

Docs and validation tooling

- [Diagnostics](https://github.com/basil23l034ec-ux/dummy/blob/main/backend/debug_api.py): tooling · Debug and verification scripts for backend behavior · `backend/debug_api.py`
- [Docs](https://github.com/basil23l034ec-ux/dummy/blob/main/README.md): documentation · System and deployment documentation · `README.md`

## Connections

- ESP8266 RFID → RFID ingest: HTTP scan · RFID reads are posted to the backend
- Flask app → Config: loads · App bootstraps configuration
- Flask app → Data layer: uses · App reads and writes persistent state
- Flask app → RFID ingest: routes · API endpoint for tag ingestion
- Flask app → Cart state: routes · Cart state is updated through the backend
- Flask app → Checkout: routes · Checkout is executed centrally
- Flask app → Inventory: routes · Inventory updates are owned by the backend
- Flask app → Analytics: routes · Derived sales and KPI data are served by the backend
- Flask app → Chatbot: routes · Chat requests are handled by the backend
- Shop UI → Client API: calls · Customer UI talks to backend APIs
- Shop UI → RFID sim: uses · Customer UI supports RFID simulation and connection
- Shop UI → Languages: uses · Customer UI localization
- Client API → Flask app: API · Customer frontend consumes backend endpoints
- Admin dashboard → Admin API: calls · Admin dashboard talks to backend APIs
- Admin API → Analytics: reads · Admin views use aggregated analytics data
- Admin API → Inventory: reads · Admin inventory views consume backend stock data
- Admin API → Flask app: API · Admin frontend consumes backend endpoints
- Worker console → Flask app: API · Worker console consumes backend endpoints
- Diagnostics → Flask app: checks · Diagnostics and verification exercise the backend
- Docs → Flask app: describes · Documentation explains system behavior and deployment
