How basil23l034ec-ux/dummy works
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: app.py Flask app · js/api.js Admin API · main.js Shop UI · js/api.js Client API
Components 19
Backend
Flask service and operational scripts
- Flask app · Main backend process and API hub
backend/app.py - Config · Runtime settings and feature flags
backend/config.py - Data layer · Database and storage access boundary
backend/db.py - RFID ingest · Receives tag scans and updates cart state
- Cart state · Maintains live trolley contents and totals
- Checkout · Handles purchase finalization and stock changes
- Inventory · Owns product and stock updates
- Analytics · Produces sales summaries and KPI data
- Chatbot · Backend chat and assistant requests
Customer UI
Shopper-facing frontend
- Shop UI · Customer browsing and cart experience
customer-frontend/static/js/main.js - Client API · Customer-side backend requests
customer-frontend/static/js/api.js - RFID sim · Customer-side device connection and simulation
customer-frontend/static/js/connect.js - Languages · Customer UI localization support
customer-frontend/static/js/i18n.js
Admin UI
Shopkeeper dashboard frontend
- Admin dashboard · Shopkeeper reporting and control console
admin-frontend/static/js/admin.js - Admin API · Admin-side backend requests
admin-frontend/static/js/api.js
Worker UI
Staff console frontend
- Worker console · Staff login and operational console
worker-frontend/static/worker.js
Hardware
RFID edge device
- ESP8266 RFID · Scans RFID tags and sends HTTP events
hardware/esp8266_rfid.ino
Support
Docs and validation tooling
- Diagnostics · Debug and verification scripts for backend behavior
backend/debug_api.py - Docs · System and deployment documentation
README.md
Connections 20
- 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