Concepts

This page explains the mental model behind Advanced Analytics Dashboard — what the key terms mean, how the pieces fit together, and why some design decisions were made the way they were. Read this before diving into the configuration reference if you want to understand the "why" rather than just the "what".

The core idea: a chart builder, not pre-built reports

Most analytics plugins ship a fixed set of pre-built reports. Advanced Analytics Dashboard takes the opposite approach: it gives you a chart builder with a visual filter system. You pick a data source, configure the metric and filters, and the chart renders immediately. This means you can answer questions the plugin developer never anticipated — "How many orders used payment method X in sales channel Y last quarter?" — without waiting for a plugin update.

The tradeoff is that you invest a few minutes in configuration upfront. The seeded demo charts are there to make that investment as small as possible on day one.

Charts

A chart is the fundamental unit. It encapsulates:

• Data source — which Shopware entity is queried (orders, customers, products, line items).
• Metric — what is being measured (count, sum of a field, average of a field).
• Filters — conditions that narrow the query (e.g. only orders in a specific sales channel).
• Date range — the time window the query covers.
• Time granularity — how time is bucketed (day, week, month, quarter, year).
• Breakdown (optional) — a property to split the result into multiple series.
• Visual type — how the result is rendered (line, bar, pie, donut, number, table).

Charts are stored independently of reports. A single chart can appear in multiple reports at the same time.

Chart translations

Chart titles and descriptions are translatable. If your shop runs multiple languages, you can enter a German title and an English title for the same chart. The admin UI shows the title in the currently active language.

Reports

A report is a named collection of charts displayed in a grid. It is the unit you share, view, and export. Reports are also translatable — the report name can differ per language.

Reports have two configuration concerns:

• Which charts they include, and in what order.
• How wide each chart is — the column span per chart, stored in the report's layout field as chartSpans.

Removing a chart from a report does not delete the chart from the library.

The overview report

One report can be designated as the overview report in plugin settings. This report opens automatically when you navigate to the Analytics module. It is also excluded from the regular report list so it does not appear twice. This is the right place for your most important daily-monitoring charts.

Data sources

Each data source maps to a Shopware entity:

Data source	Entity	What it counts/sums/averages
Orders	order	Order records and their monetary fields
Customers	customer	Customer records
Products	product	Product records and their stock/price fields
Line items	order_line_item	Individual items within orders

Data is always read from the live Shopware database via the DAL. There is no data sync or cache — charts reflect the current state of your shop data. Query results are not pre-aggregated or stored.

The filter system

Filters are the most powerful part of the plugin. They use the same AND logic as Shopware's own rule system: every condition in a filter list must match for a record to be included.

Each filter row has three parts:

1. Property — which field to filter on (e.g. sales_channel_id, state_id, affiliate_code).
2. Operator — how to compare (equals, not equals, contains, greater than, etc.).
3. Value — the comparison target (entity select, boolean toggle, or free text/number, depending on the property type).

The operators available for a property are determined by its type. Entity properties (like sales channels or currencies) use equals/not equals/is set/is not set backed by Shopware's entity-select components. Boolean properties use true/false selects. Text and number fields use string/comparison operators.

Initial filters

Some data sources expose initial filters — admin-level scope controls that appear as badges above the chart, separate from the chart's stored filter configuration. The current implementation includes a sales channel picker on the dashboard and report views. Initial filters are merged with the chart's stored filters at query time; they do not overwrite the stored configuration.

Column spans and the resize handle

Each chart in a report or on the dashboard has a column span — how many grid columns it occupies. The span is independent per chart and persisted separately from the chart configuration itself:

• In reports: spans are stored in ssd_analytic.layout.chartSpans (a JSON map of chartId → span).
• On the dashboard: spans are stored per admin user in their browser user settings, so each admin has their own layout.

The drag handle on the right edge of chart cards in the edit view snaps to column boundaries. A FLIP animation smoothly reflows neighboring cards during the drag.

Default spans when none is set: Number cards → 1 column; Tables → full width; all other types → 2 columns.

Date range presets and custom ranges

Presets like "Last 30 days" and "This month" are resolved to concrete {start, end} timestamps at query time on the server. Custom ranges use the explicit date_range_start / date_range_end values stored on the chart entity.

When Compare to previous period is enabled, the backend automatically calculates the matching prior period: "Last 30 days" compares to the 30 days before that; "This month" compares to last month; custom ranges shift back by the same duration.

Previous-period comparison and the delta badge

On Number cards, the previous-period value drives a delta badge showing the change from one period to the next:

• A green upward badge for positive change (or negative change on metrics where lower is better — this is not automatically detected; the sign convention follows the raw delta).
• A red downward badge for negative change.
• The badge shows a percentage (e.g. +12.3%) when the previous period value is non-zero. When the previous value is zero, only the absolute delta is shown (percentage division by zero is suppressed).

On line and bar charts, the previous period renders as a second dashed series overlaid on the current period.

Breakdown

A breakdown splits a chart's data by a dimension, turning a single-series line chart into one line per segment. For example, a revenue chart broken down by sales_channel_id shows one line per sales channel.

Only one breakdown is supported per chart in this version. Available breakdown properties differ by data source.

Segments with a null value for the breakdown property are grouped under a configured null label (for example, "Direct / Organic" for campaign_code), keeping them visible rather than silently dropping them.

ACL and access control

The plugin uses Shopware's built-in ACL system. Access is controlled by four roles on the ssd_analytic resource:

• Viewer — required to see the Analytics menu and read data. Any user without this role will not see the Analytics entry.
• Editor — required to update (save) existing charts and reports.
• Creator — required to create new charts and reports.
• Deleter — required to delete charts and reports.

Roles stack: a Creator needs Viewer + Editor, and a Deleter needs Viewer. See the Configuration reference for the exact role keys to assign in Shopware's permissions system.

Extension points

The plugin exposes a set of Symfony events for third-party plugins or custom code to extend the query pipeline:

Event	When it fires	Use it to
BeforeAnalyticsQueryEvent	Before SQL is built	Inject extra filters based on tenant, role, or context
BeforeAnalyticsQueryExecuteEvent	After SQL is built, before DB execution	Mutate the raw SQL/params as a last resort
AnalyticsQueryResultEvent	After the query returns	Post-process result data, mask values, append computed series
AnalyticsDataSourcesEvent	When the data-sources metadata is fetched	Add, remove, or modify available data sources in the chart builder UI
RegisterAnalyticsOperatorsEvent	Once on first use (cached)	Register custom filter operators (e.g. between)
RegisterAnalyticsDateRangesEvent	Once on first use (cached)	Register custom date range presets (e.g. fiscal_year)

These events follow the standard Symfony EventSubscriberInterface pattern. See planning/06-developer-notes.md in the plugin source for code examples.

What is not in scope

The plugin queries the Shopware database directly via the DAL. It does not:

• Track storefront visitors, page views, or sessions (use Shopware Analytics or Google Analytics for that).
• Connect to external data warehouses or sync data to external services.
• Provide multi-shop aggregation across instances.
• Offer AI-powered insights or anomaly detection.
• Cover line-item-level storefront events (add to cart, wishlist, etc.).