VM

Vending Mind

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:

1️⃣

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
2️⃣

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
3️⃣

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/admin

Login Credentials

Login
demo@foodture.net
Password
7455c77c8f

File 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.

ValueDescription
MachineMachines list from Cantaloupe
LocationLocations list from Cantaloupe
itemItems (SKU) list from Cantaloupe
customerCustomers list from Cantaloupe
planogramMachine planogram
salesSales by Visit export (main sales file)
sales with timeSales export with date & time

Field: project

For demo data, always select:

foodture

4. Recommended Upload Order (Important)

Upload files in this order:

  1. 1. Machine
  2. 2. Location
  3. 3. item
  4. 4. customer
  5. 5. planogram
  6. 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

Login
mainadmin@foodture.net
Password
Admin0Mega0Pass

What 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_id

2. 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)