Reporting & Analytics

Flow ID: AD-10 Module(s): eshop Complexity: High Last Updated: 2026-04-04

Business Context

The reporting system provides 20+ reports across orders, vendors, products, categories, customers, geography, shipping, and payments. Reports support date-range filtering with 7 timespan options (day/week/15-day/month/quarter/semester/year) and Chart.js visualizations. A live dashboard provides real-time KPIs with optional Matomo visitor data and AI recommendation tracking.

Entry Points

Type	Path / Trigger	Controller	Method
Admin	Reports	ecommercen/eshop/controllers/Adv_reporting.php	Various (20+ methods)
Admin	Dashboard API	same	dashboardLive() (JSON)
Roles	Required	—	AUTH_ROLE_ADVISABLE, AUTH_ROLE_ADMIN, or AUTH_ROLE_REPORTING

Report Categories

Timeseries Reports (date-ranged, with charts):

Report	Method	Data Source	Export
Orders	orders()	getOrderDataGroupedDay/Month/Year()	Chart
Order Bundles	orders_bundles()	getOrderBundleDataGroupedByTimespanSelector()	Chart
Vendor Sales	vendors_timespans()	getVendorDataGroupedDay/Month/Year()	Chart
Vendor Products	vendor_products_timespans()	Vendor + product breakdown	Chart
Products	products_timespans()	getProductDataGroupedDay/Month/Year()	Chart
Categories	categories_timespans()	Category breakdown	Chart
Payment Methods	payways()	getPaywaysDataGroupedDay/Month/Year()	Chart
Online/Offline	onoffline()	By webignore flag	Chart

Customer Reports: New customers, top spenders, top ranking (cached), new vs returning ratio.

Geographic Reports: By referrer source, country, county, marketplace.

Logistics: By shipping method, free shipping orders.

Special: Product search with CSV export, MVPs (most valuable products — first-added-to-cart analysis).

Dashboard Widgets

Live JSON endpoint dashboardLive() provides:

• Hour/day/month order metrics (total VAT, count, items, avg cart)
• Guest vs registered customer breakdown
• New vs returning customer ratio
• Vendor/category/product performance tables
• Shipping method breakdown
• Payment method breakdown
• Cart value range distribution
• Weight-based order analysis
• Optional: Matomo live visitors/visits/CVR
• Optional: AI recommendation revenue tracking

Reporting Engine Details

Adv_reporting.php contains 30+ reporting methods, making it one of the largest controllers in the application.

7 timespan granularities: 1 day, 7 days, 15 days, 1 month, 3 months, 6 months, 1 year. All timeseries reports support all granularities via a shared timespan selector.

Dashboard live metrics (dashboardLive()): 20+ real-time KPIs refreshed on each admin dashboard load, including hourly/daily/monthly order totals, guest vs registered breakdown, new vs returning ratio, vendor/category/product performance, shipping/payment method distribution, cart value ranges, and weight-based analysis.

Databox Integration

15 Databox metrics are pushed every 30 minutes via a scheduled job:

#	Metric	Description
1	Revenue	Total order revenue (VAT-inclusive)
2	Orders	Order count
3	Quantity	Total items sold
4	AOV	Average order value
5	Registrations	New customer registrations
6	Customers	Unique purchasing customers
7	Order Method	Breakdown by online/offline/phone
8	Payment Method	Breakdown by payment gateway
9	Shipping Cost	Total shipping revenue
10	Transporters	Orders per shipping provider
11	Stores	Orders per pickup store
12	Referrer Cost	Revenue attributed by referrer source
13	Marketplaces	Orders from marketplace channels
14	Country	Orders by country
15	County	Orders by county/region

Analytics Tracking

Matomo server-side tracking: Matomo integration includes a circuit breaker to prevent cascading failures when the Matomo server is unavailable. Visitor data and conversion rates are conditionally displayed on the admin dashboard.

GA4 tracking: Google Analytics 4 event tracking functions are provided by tracking_helper.php, used for e-commerce event dispatch (purchase, add_to_cart, view_item, etc.) on the storefront.

Business Rules

Rule	Description
Excluded statuses	All order reports exclude CANCELED, PENDING, RETURN
7 timespan options	day, week, 15-day, month, quarter, semester, year
CSV export	Special products and MVPs support semicolon-delimited UTF-8 BOM CSV
Matomo integration	Conditional on MATOMO::ENABLED + MATOMO::SHOW_ADMIN_DASHBOARD registry
Matomo circuit breaker	Server-side Matomo calls are protected by circuit breaker to avoid dashboard slowdowns
AI tracking	Conditional on ADVISABLE_AI::ENABLED + ADVISABLE_AI::SHOW_ADMIN_DASHBOARD
Top ranking cached	getTopRankingCustomers() uses PSCache
Databox push interval	Every 30 minutes via scheduled job

Domain Layer

Controller: Adv_reporting.php (3,439 lines)

The reporting controller is one of the largest in the application. It extends Admin_c and requires AUTH_ROLE_ADVISABLE, AUTH_ROLE_ADMIN, or AUTH_ROLE_REPORTING.

Models loaded: order_model, vendors_model, product_category_model, customer_model, reporting_model.

Complete Method Reference

Timeseries Reports (date-ranged, chart-rendered):

Method	Lines	Description	Granularity
orders()	71-147	Order revenue/count by timespan	Day/Month/Year
orders_bundles()	149-191	Bundle order data by timespan	Day/Month/Year
vendors_timespans()	327-426	Vendor revenue/count breakdown	Day/Month/Year
vendor_products_timespans()	427-512	Vendor + product cross-breakdown	Day/Month/Year
products_timespans()	513-595	Product-level revenue/count	Day/Month/Year
categories_timespans()	596-672	Category breakdown	Day/Month/Year
categories_products_timespans()	673-748	Category + product cross-breakdown	Day/Month/Year
payways()	749-811	Payment method breakdown	Day/Month/Year
onoffline()	812-874	Online vs offline (phone) orders	Day/Month/Year

AJAX Chart Data Reports (loaded via admin JS scripts):

Method	Description
vendors()	Vendor report page (AJAX-loaded chart)
products()	Product report page (AJAX-loaded chart)
vendor_products()	Vendor-product report page
categories()	Category report page
categories_products()	Category-product report page
productInOrders()	Product-in-orders lookup

Customer Reports:

Method	Description
new_customers()	New customer registrations in date range
top_customers()	Top customers by spend in date range
topRankingCustomers()	All-time top customers (PSCache-cached)
newCustomersRatio()	New vs returning customer ratio

Geographic Reports:

Method	Description
referrer()	Orders by referrer source (Skroutz, Google, direct, etc.)
marketplace()	Orders by marketplace provider
countries()	Orders by country
counties()	Orders by county/region

Logistics Reports:

Method	Description
shipping()	Orders by shipping method/transporter
freeShipping()	Free shipping order analysis

Special Reports:

Method	Description	Export
specialProducts()	Product search with advanced filters	CSV (semicolon, UTF-8 BOM)
mvps()	Most Valuable Products -- first-added-to-cart analysis	CSV

Dashboard:

Method	Description
dashboardLive()	JSON API for real-time admin dashboard

Dashboard Live JSON Structure

The dashboardLive() method returns a structured JSON response consumed by the Vue.js admin dashboard. It assembles data from 11 sub-report generators:

dashboardLive() JSON response
├── general
│   ├── statsHeader (localized label)
│   └── customHeader (localized label)
├── tabs[] (hour/day/month data sets)
├── quickViews[] (summary KPIs per timeframe)
│   ├── totalVat, ordersCount, itemsCount, avgCartValue
│   ├── guestCustomers, registeredCustomers
│   ├── newCustomers, oldCustomers
│   ├── Smart recommendation revenue (if SMART_RECOMMENDATIONS enabled)
│   └── AI recommendation revenue (if ADVISABLE_AI enabled)
├── nodes[] (detailed breakdowns)
│   ├── cartOrders (cart value distribution)
│   ├── weightOrders (weight-based distribution)
│   ├── deliveryOrders (delivery time distribution)
│   ├── onlineOfflineOrders (channel breakdown)
│   ├── brandOrders (vendor performance: totalVat/items/orders)
│   ├── categoriesOrders (category performance)
│   ├── productsOrders (product performance)
│   ├── shippingReport (transporter + store breakdown)
│   └── paymentReport (payment method breakdown)
├── customViews[]
│   └── inProcess (orders in process count)

Three timeframes computed: Last hour, today (day), and current month. Each generates a separate quickView entry with trend calculations via calculateTrend().

Conditional features in dashboard:

• SMART_RECOMMENDATIONS.IS_ENABLED_BASED_ON_CART -- adds smart recommendation revenue tracking
• ADVISABLE_AI.ENABLED -- adds AI recommendation revenue tracking
• Matomo visitor data (handled separately by admin Vue dashboard, not in this JSON)

Databox Integration (Deep)

Library: ecommercen/libraries/AdvDatabox.php (964 lines)

Job: ecommercen/job/libraries/AdvReportingToDatabox.php -- implements JobCommand, triggered via CLI:

php cli.php job/ReportingToDatabox/all        # Push all 15 metrics (3-month window)
php cli.php job/ReportingToDatabox/all/1      # Push all 15 metrics (full 3-year history)
php cli.php job/ReportingToDatabox/sentRevenue # Push single metric

Configuration: Enabled via DATABOX.ENABLED registry. Token stored encrypted in DATABOX.TOKEN.

Push mechanism: HTTP POST to https://push.databox.com/data with Basic Auth (token as username). Data is chunked into batches of 500 rows. Rate-limited: every 10th API call triggers a 1-second sleep to avoid rate limiting.

SQL query pattern: All 15 metrics use the same query structure:

• Filter: status NOT IN ('CANCELED', 'RETURN', 'PENDING')
• Granularity: Hourly (DATE_FORMAT(entry_datetime, '%Y-%m-%d %H:00:00'))
• Time window: Last 3 months (recurring) or last 3 years (initialization)
• Each row maps to a Databox data point with key, value, date, optional unit, and attributes

Detailed metric SQL sources:

#	Metric Key	SQL Source	Attributes
1	Revenue	SUM(total_vat) + SUM(total) from shop_order	vat: With Vat / No Vat, unit: EUR
2	Orders	COUNT(shop_order.id)	--
3	Quantity	SUM(shop_order_basket.qty) excluding gifts	--
4	Average Order Value	ROUND(AVG(total_vat), 2)	unit: EUR
5	Registrations	COUNT(shop_customer.id) where is_guest=0	--
6	Customers	COUNT(shop_customer.id) joined via shop_order	registration: Registered / No registered
7	Order Method	COUNT grouped by webignore	method: By phone / On line
8	Payment Method	COUNT grouped by payway	method: {payway value}
9	Shipping Cost	COUNT grouped by transportation_cost > 0	cost: Paid / Free
10	Shipping type	COUNT grouped by transport_id	transporter: {name from transporters_mui}
11	Picking point	COUNT grouped by store_id	store: {address from store_mui}
12	Referrer	COUNT grouped by skroutz_referer	channel: {from referrerChannels config}
13	Marketplaces	COUNT grouped by provider	chanel: {from marketPlaces config}
14	Country	COUNT grouped by pricing_country	country: {from country table}
15	County	COUNT grouped by pricing_county	county: {from county table}, unit: count

GA4 / Tracking Helper

File: ecommercen/helpers/tracking_helper.php

Provides server-side GA4 event functions for storefront e-commerce tracking. These are NOT part of the admin reporting controller but generate the data layer that GA4 uses. Events include: purchase, add_to_cart, remove_from_cart, view_item, view_item_list, begin_checkout, etc.

Matomo Admin Dashboard Integration

Matomo visitor data is conditionally displayed on the admin dashboard when:

• MATOMO.ENABLED registry value is truthy
• MATOMO.SHOW_ADMIN_DASHBOARD registry value is truthy

The integration uses a circuit breaker pattern (see SY-26 Circuit Breaker) to prevent cascading failures when the Matomo server is unavailable. Matomo data includes:

• Live visitor count
• Visit count for the day
• Conversion rate (CVR)

Configuration stored encrypted in registry: MATOMO.TOKEN, MATOMO.SITE_ID, with MATOMO.SITE_URL, MATOMO.TIMEOUT, MATOMO.CONNECT_TIMEOUT for HTTP client tuning.

Chart Rendering Architecture

All timeseries reports use a shared graph-setting infrastructure. Each report type has dedicated graph methods:

Graph Category	Set Methods	Rendering
General (orders)	setGeneralHourReportGraph, setGeneralDaysReportGraph, setGeneralMonthsReportGraph	Line/bar charts
Customers	setCustomersGraphs	Pie/bar for guest/registered/new/returning
Shipping	setShippingGraphs	Bar for transporter + store distribution
Payment	setPaymentGraphs	Pie for payment method split
Cart value	setCartGraphs	Histogram for cart value ranges
Weight	setWeightGraphs	Histogram for order weight distribution
Delivery	setDeliveryGraphs	Delivery time distribution
Online/Offline	setOnlineOfflineGraphs	Pie/bar for channel
Brand (vendor)	setBrandTotalVatGraphs, setBrandItemsGraphs, setBrandOrdersGraphs	Three metrics per vendor
Category	setCategoriesTotalVatGraphs, setCategoriesItemsGraphs, setCategoriesOrdersGraphs	Three metrics per category
Product	setProductsTotalVatGraphs, setProductsItemsGraphs, setProductsOrdersGraphs	Three metrics per product

Colors are pre-defined as RGBA values in the constructor and cycled through datasets.

Related Flows

• AD-03 Order Management -- orders data source
• AD-04 Customer Management -- customer reports (new customers, top spenders)
• AD-19 Vendor Management -- vendor sales and product performance reports
• AD-18 Store Management -- store-based order grouping in reports
• IN-12 Analytics -- Matomo, Databox
• SY-26 Circuit Breaker -- Matomo circuit breaker pattern