> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minestorecms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Anomaly Detection

> Automatically detect unusual patterns in revenue, transactions, geography, products and timing — and email the right admins when something stands out.

## **Introduction**

The **Anomaly Detection** module watches your store and flags **unusual patterns** in real time. It runs **every hour** on a schedule and writes any findings to a dedicated log that admins can review and resolve.

When an anomaly is detected, the platform automatically **emails every admin** who has opted in to notifications, and surfaces the same finding in the in-app notification bell.

<Check>
  No configuration is required — anomaly detection runs out of the box on every install. You only need to **opt admins in to email notifications** if you want alerts in your inbox.
</Check>

## **What Gets Detected**

| **Anomaly Type**         | **Trigger**                                                                                                                                                                   |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Revenue Drop**         | Today's revenue is **30% or more below** the average of the previous 7 days.                                                                                                  |
| **Revenue Surge**        | Today's revenue is **200% or more above** the average of the previous 7 days.                                                                                                 |
| **Transaction Velocity** | The number of transactions in the last hour is **5× or more** the hourly average over the past 7 days.                                                                        |
| **Geographic Anomaly**   | A country with no recent activity suddenly shows ≥3 transactions, or a known country shows **3× or more** its daily average.                                                  |
| **Product Anomaly**      | A new product gets ≥5 sales in a day with no historical sales, an existing product sees **3× or more** its daily average, or a top-seller (avg ≥3/day) gets zero sales today. |
| **Time Anomaly**         | 10 or more transactions occur between **02:00 and 06:00** — outside normal buying hours.                                                                                      |

### Severity Levels

Each finding is automatically classified by how far it deviates from the baseline:

| **Severity** | **Used for**                                                                              |
| ------------ | ----------------------------------------------------------------------------------------- |
| **Critical** | Revenue drops of 70% or more.                                                             |
| **High**     | Revenue drops of 50–70%, large product/geographic surges, transaction velocity spikes.    |
| **Medium**   | Smaller-but-meaningful deviations, late-night activity, new countries with modest volume. |
| **Low**      | Reserved for future detectors.                                                            |

## **Enabling Email Notifications for an Admin**

To receive email alerts when an anomaly is detected:

<Steps>
  <Step title={'Open the Admin Panel'}>
    Click on the **Admin Panel**.
  </Step>

  <Step title={'Open Staff / Users Management'}>
    Navigate to the staff list where admin accounts are managed.
  </Step>

  <Step title={'Edit an Admin'}>
    Open the admin's profile and make sure their **email address** is set.
  </Step>

  <Step title={'Enable Email Notifications'}>
    Toggle **Enable Email Notifications** on for that admin.
  </Step>

  <Step title={'Save Changes'}>
    Click **Save**.
  </Step>
</Steps>

<Info>
  Only admins with **both** an email address and the **Enable Email Notifications** flag receive anomaly emails. The in-app notification bell receives the same alerts regardless of the email flag.
</Info>

## **Reviewing Anomalies**

To review detected anomalies:

<Steps>
  <Step title={'Open Statistics'}>
    Click on the **Statistics** tab in the sidebar.
  </Step>

  <Step title={'Open Anomalies'}>
    Open the **Anomalies** sub-section.
  </Step>

  <Step title={'Investigate Findings'}>
    Each anomaly shows its **type**, **severity**, a **description** comparing today's value against the historical baseline, and the **raw numbers** that triggered it.
  </Step>

  <Step title={'Resolve or Mark False Positive'}>
    Use the actions on the anomaly's detail page to move it to **Resolved** or **False Positive**, or leave it in **Investigating** while you dig in.
  </Step>
</Steps>

### Anomaly Statuses

| **Status**         | **Meaning**                                                           |
| ------------------ | --------------------------------------------------------------------- |
| **Open**           | Newly detected; nobody has reviewed it yet.                           |
| **Investigating**  | An admin is actively looking at the finding.                          |
| **Resolved**       | Cause was identified and the issue is closed.                         |
| **False Positive** | The pattern is benign (e.g. a planned promotion explained the surge). |

## **Running the Detection Manually**

The scheduler runs anomaly detection **every hour** automatically. To trigger a run manually (e.g. while testing), execute the artisan command:

```bash theme={null}
php artisan analytics:detect-anomalies
```

<Warning>
  Manually running the detector creates **real** anomaly records (and may send real emails) — it is not a dry run. Use it only when you intend to flag findings for the current state of the store.
</Warning>

## **Quiet Periods**

The detectors are designed to fail quiet:

* A revenue drop is **not** flagged on a fresh store with no historical baseline.
* A product surge requires at least **5 sales** to be flagged.
* A geographic surge requires at least **3 sales** from a new country (or 5 from an existing one).
* A transaction velocity spike requires at least one transaction in the past 7 days as a baseline.

This avoids spamming admins during low-traffic launch periods.