# Quick Start Guide

Get the dashboard running in under 5 minutes.

## Step 1: Open the Dashboard

Double-click `dashboard.html` or open it in your browser. The sample data loads automatically, so you can explore every feature straight away.

Click through all 4 tabs: Overview, Items & Categories, Health & NOVA, and Shopping List.

## Step 2: Try the Time Toggle

Use the **All Time / Last 12 Months** toggle above the tabs. The Overview and Items & Categories tabs update to show either the full date range or just recent data.

## Step 3: Export Your Own Tesco Data

Follow `EXPORT-GUIDE.md` for step-by-step instructions on downloading your Tesco order history. You need your order confirmation emails or Tesco account data in markdown format.

## Step 4: Process Your Data

You need [Node.js](https://nodejs.org/) installed (any recent version, no npm packages needed).

1. Save your Tesco transaction data as `tesco_transactions.md` in the same folder as `build_data.js`
2. Open a terminal in that folder
3. Run:

```bash
node build_data.js
```

This reads your transaction file and outputs `data.json` with all the aggregated analytics.

## Step 5: Convert to JS and View Your Dashboard

Wrap your data file so the dashboard can load it locally:

```bash
echo "const DASHBOARD_DATA = $(cat data.json);" > data.js
```

Copy `data.js` into the same folder as `dashboard.html`, then open (or refresh) the dashboard in your browser.

That's it. Your data stays on your machine.

## Data Format Reference

### Transaction Markdown Format

The `build_data.js` script expects a markdown file with transaction blocks in this format:

```markdown
## Order: 2024-03-15

**Type:** GHS
**Gross:** £85.42
**Savings:** £4.20
**Net:** £81.22
**Payment:** Visa ending 1234

### Items
- Tesco Blueberries 250G × 2 @ £2.50
- Tesco Finest Free Range Chicken Fillets 500G × 1 @ £5.50
- Warburtons Toastie White 800g × 1 @ £1.45
- Tesco Whole Milk 2.27L × 1 @ £1.55
```

**Key fields:**
- `Type`: Either `GHS` (Grocery Home Shopping / delivery) or `IN_STORE`
- `Gross`: Total before Clubcard savings
- `Savings`: Clubcard discount amount
- `Net`: Amount actually paid
- Items: Product name, quantity, unit price

### Output: data.json

The build script generates a single JSON file containing:

| Section | What it contains |
|---------|-----------------|
| `summary` | Total spend, transaction count, savings, date range, average basket |
| `spending.monthly` | Month-by-month spend totals |
| `spending.yearly` | Year-by-year spend totals |
| `spending.dow` | Day-of-week average baskets |
| `spending.typeSplit` | GHS vs In-Store breakdown |
| `items.all` | Every product with spend, quantity, category, and NOVA level |
| `categories` | Category totals and top items per category |
| `nova` | NOVA split, yearly trend, UPF subcategories, top UPF items |
| `insights` | Auto-generated insights (spending, health, habits) |
| `last12Months` | Separate aggregates for the most recent 12 months |
| `replenishment` | Shopping list grouped by purchase frequency |

## Troubleshooting

**Dashboard shows "No data file found"**: Make sure `data.js` (or `sample-data.js`) is in the same folder as `dashboard.html`. The dashboard loads data via a script tag, not fetch, so JSON files won't work directly. Wrap your JSON: `echo "const DASHBOARD_DATA = $(cat data.json);" > data.js`

**Build script fails**: Check that your `tesco_transactions.md` file is in the same folder as `build_data.js` and follows the expected format above.

**Charts not rendering**: The dashboard loads Chart.js from a CDN, so you need an internet connection the first time. After that, your browser cache will keep it available.

**NOVA classifications seem wrong**: The build script uses keyword-based matching, which is approximate. See `CUSTOMIZATION-GUIDE.md` for how to adjust the NOVA rules.