Vending Mind
Data Upload, Processing & Analytics Guide
(Current implementation — Admin Panel + PostgreSQL + Redash)
0. Introduction — What the System Is Today
This document describes the current, actually implemented version of the Vending Mind system.
The goal of the current version is to provide a reliable and transparent data pipeline: from raw Cantaloupe exports → validated data → SQL analytics.
A more user-friendly business interface is in development.
Today, the system is operated through two core tools:
- • Admin Panel — for data upload, processing, and control
- • Analytics system (Redash) — for SQL queries, reports, and dashboards
Redash is used as a typical analytics system. In the future, any other BI or analytics tool (Tableau, Power BI, Metabase, custom internal tools) can be connected instead of or in addition to Redash.
1. High-Level System Logic
The system consists of three logical layers:
Data Upload & Cleaning (Admin Panel + ETL)
- • Users upload Excel / CSV files exported from Cantaloupe
- • The system automatically performs:
- — Parsing — reading file structure
- — Mapping — matching machines, items, locations, customers
- — Validation — checking data correctness
- • Rows with problems are sent to Quarantine
- • Correct rows are written into clean dataset tables
Storage (PostgreSQL)
In the current implementation, PostgreSQL is the only database used and acts as the single source of truth.
PostgreSQL stores:
- • clean sales datasets
- • reference tables (customers, items, machines, locations)
- • quarantine records
- • processing metadata
Analytics & SQL (Redash)
- • All analytics is done using SQL
- • SQL queries are executed via Redash
- • Redash is connected directly to PostgreSQL
- • Other analytics systems can be connected later without changing the data model
2. Admin Panel — Data Upload & Monitoring
Admin Panel Access
https://vending-mind.foodture.net/adminLogin Credentials
demo@foodture.net7455c77c8fFile Upload Page
https://vending-mind.foodture.net/admin/upload/uploadedfile/This page is used to upload all source files and monitor their processing status.
3. Uploading Files (Step-by-Step)
Step 1 — Open the Upload Page
Create a new upload entry.
Step 2 — Select a File
Choose an Excel or CSV file exported from Cantaloupe.
Step 3 — Fill Required Fields
Field: kind (file type)
This field tells the system what kind of data is being uploaded.
| Value | Description |
|---|---|
| Machine | Machines list from Cantaloupe |
| Location | Locations list from Cantaloupe |
| item | Items (SKU) list from Cantaloupe |
| customer | Customers list from Cantaloupe |
| planogram | Machine planogram |
| sales | Sales by Visit export (main sales file) |
| sales with time | Sales export with date & time |
Field: project
For demo data, always select:
foodture4. Recommended Upload Order (Important)
Upload files in this order:
- 1. Machine
- 2. Location
- 3. item
- 4. customer
- 5. planogram
- 6. sales / sales with time
Reason (plain language): Sales reference machines, items, locations, and customers. If these are not loaded first, more rows may end up in quarantine.
5. File Processing Status
After upload, files are processed automatically.
Process
Processing is running
Processed
Processing finished
Sales files usually take longer than reference files.
6. Quarantine — Data Quality Control
Rows that fail validation are placed into Quarantine.
Quarantine Page
https://vending-mind.foodture.net/admin/upload/quarantine/Each record includes:
- • data from the original row
- • a message / reason explaining why it was rejected
Important:
- • Quarantine does not stop processing
- • All valid rows are still loaded into clean datasets
7. Analytics System — Redash
Redash Access
https://redash.foodture.net/Credentials
mainadmin@foodture.netAdmin0Mega0PassWhat Redash Is Used For
Redash is used to:
- • run SQL queries
- • answer business questions
- • build tables and charts
- • create dashboards
- • export data to CSV / Excel
Redash is a reference analytics tool, not a system limitation.
8. Main PostgreSQL Tables
🔹 Main Analytical Tables
These are the three most important tables for analytics:
1. dataset_itemsale
Main dataset with item-level sales and machine context.
Used for:
- • revenue and margin analysis
- • item performance
- • machine performance
- • operational flags
Contains (examples):
machine_idlocation_nameroute_namebranchcustomervisit_idvisit_timedriveritem_iditem_namepackpack_countpricesold_qtyquantitytotal_revenuepretax_revenueproduct_costgross_marginnet_marginsales_taxbottle_depositcommissionsspoiled_costhas_price_mismatchhas_pending_planogram_changeproject_id2. dataset_sales
Sales dataset focused on sales events and visits (used when time / visit-level analysis is required).
Typical use cases:
- • sales over time
- • visit-based analysis
- • daily / hourly trends
3. upload_quarantine
Contains all rows that failed validation.
Used for:
- • data quality analysis
- • operational debugging
- • understanding why data was excluded
🔹 Reference Tables (Dimensions)
Used to enrich analytics via joins:
customersitemsmachineslocations(Exact table names may vary, but conceptually these are stable reference datasets.)
9. SQL Examples (PostgreSQL — Ready for Redash)
Replace project_id = 1 with the correct project ID.
9.1 Revenue & Net Margin by Machine
SELECT
machine_id,
SUM(total_revenue) AS total_revenue,
SUM(net_margin) AS total_net_margin,
SUM(sold_qty) AS total_units
FROM dataset_itemsale
WHERE project_id = 1
GROUP BY machine_id
ORDER BY total_revenue DESC;9.2 Revenue by Location
SELECT
location_name,
SUM(total_revenue) AS total_revenue,
SUM(net_margin) AS total_net_margin
FROM dataset_itemsale
WHERE project_id = 1
GROUP BY location_name
ORDER BY total_revenue DESC;9.3 Top Items by Revenue
SELECT
item_id,
item_name,
SUM(total_revenue) AS total_revenue,
SUM(sold_qty) AS qty_sold
FROM dataset_itemsale
WHERE project_id = 1
GROUP BY item_id, item_name
ORDER BY total_revenue DESC
LIMIT 20;9.4 Revenue by Route and Driver
SELECT
route_name,
driver,
COUNT(DISTINCT visit_id) AS visits,
SUM(total_revenue) AS total_revenue,
SUM(net_margin) AS total_net_margin
FROM dataset_itemsale
WHERE project_id = 1
GROUP BY route_name, driver
ORDER BY total_revenue DESC;9.5 Machines with Operational Issues
SELECT
machine_id,
COUNT(*) FILTER (WHERE has_price_mismatch) AS price_mismatch,
COUNT(*) FILTER (WHERE has_pending_planogram_change) AS planogram_issues
FROM dataset_itemsale
WHERE project_id = 1
GROUP BY machine_id
HAVING
COUNT(*) FILTER (WHERE has_price_mismatch) > 0
OR COUNT(*) FILTER (WHERE has_pending_planogram_change) > 0;9.6 Quarantine Analysis (Data Quality)
SELECT
reason,
COUNT(*) AS rows_count
FROM upload_quarantine
GROUP BY reason
ORDER BY rows_count DESC;10. Universal GPT Prompt (for Current Schema)
Use this prompt to generate correct SQL queries for this system:
You are a senior data analyst.
Write PostgreSQL SQL queries for Redash.
Current system:
- Database: PostgreSQL
- Analytics tool: Redash
- Main tables:
1) dataset_itemsale (main analytics table)
2) dataset_sales (sales / visit-level analysis)
3) upload_quarantine (data quality issues)
- Reference tables: customers, items, machines, locations
Rules:
- Always filter by project_id when applicable
- Prefer dataset_itemsale for revenue and margin analytics
- Use dataset_sales for time / visit analysis
- Use upload_quarantine only for data quality analysis
- Return:
1) SQL query
2) Short explanation in plain English
Task:
<<Describe the business question, date range, grouping level, project_id>>11. Final Summary
Admin Panel
Upload and control data
ETL
Automatic cleaning and validation
upload_quarantine
All problematic rows
PostgreSQL
Single source of truth
Redash
SQL analytics (replaceable in future)