# Database

## Engine and conventions

- MySQL with InnoDB. All schema changes via Laravel migrations only — no raw DDL.
- All models use Eloquent. No raw DB:: queries except for complex aggregations.
- Table names: plural snake_case. Column names: snake_case.
- Always define `$fillable` or `$guarded` on models — never leave both empty.
- Use `->comment()` on migration columns for non-obvious fields.

## Core tables

### users
Standard Laravel users table + additions:
- `postcode` VARCHAR(8) — user's home postcode, used for nearby station lookup
- `lat` / `lng` DECIMAL(10,7) — resolved from postcode via postcodes.io on registration
- `whatsapp_number` VARCHAR(20) NULLABLE — verified mobile, set after OTP flow
- `whatsapp_verified_at` TIMESTAMP NULLABLE
- `push_token` VARCHAR(255) NULLABLE — OneSignal player ID

### subscriptions
Managed by Laravel Cashier — do not hand-edit this table.
Tier is read via `$user->subscribed('basic')`, `->subscribed('plus')`, `->subscribed('pro')`.

### station_prices (HIGH VOLUME — partitioned)
```
id              BIGINT UNSIGNED AUTO_INCREMENT
station_id      VARCHAR(64)     — Fuel Finder API station identifier
fuel_type       ENUM('e10','e5','b7_standard','b7_premium','b10','hvo')
price_pence     SMALLINT UNSIGNED  — e.g. 14523 = 145.23p (store as integer × 100)
is_supermarket  TINYINT(1) DEFAULT 0
brand           VARCHAR(64) NULLABLE
recorded_at     DATETIME

INDEX (station_id, fuel_type, recorded_at)
INDEX (recorded_at)
PARTITION BY RANGE (YEAR(recorded_at) * 100 + MONTH(recorded_at))
```
Partition monthly. Use `recorded_at` not `created_at` — it reflects actual price time.
Never store floats for prices — always pence as SMALLINT (price × 100).

### stations (reference/cache)
```
station_id      VARCHAR(64) PRIMARY KEY   — from Fuel Finder API
name            VARCHAR(128)
brand           VARCHAR(64) NULLABLE
lat             DECIMAL(10,7)
lng             DECIMAL(10,7)
postcode        VARCHAR(8)
is_supermarket  TINYINT(1) DEFAULT 0
amenities       JSON NULLABLE
last_seen_at    DATETIME
```
Refreshed on each Fuel Finder poll. `is_supermarket` set by StationTaggingService.

### alerts (sent notification log)
```
id              BIGINT UNSIGNED AUTO_INCREMENT
user_id         BIGINT UNSIGNED FK users.id
alert_type      ENUM('fill_up_now','wait','watchdog','price_drop')
channel         ENUM('email','whatsapp','sms','push')
signal_strength TINYINT    — 1=weak, 2=medium, 3=strong
payload         JSON       — recommendation data snapshot
sent_at         DATETIME
INDEX (user_id, sent_at)
```

### scoring_results (daily per-user cache)
```
user_id         BIGINT UNSIGNED FK users.id
scored_at       DATE
recommendation  ENUM('fill_up','wait','no_signal')
confidence      TINYINT    — 0–100
signals         JSON       — breakdown of each signal used
local_avg_pence SMALLINT UNSIGNED
trend_direction ENUM('falling','rising','flat')
expires_at      DATETIME
PRIMARY KEY (user_id, scored_at)
```

### otp_verifications
```
id              BIGINT UNSIGNED AUTO_INCREMENT
user_id         BIGINT UNSIGNED FK users.id
channel         ENUM('whatsapp','sms')
phone_number    VARCHAR(20)
code            CHAR(6)
expires_at      DATETIME
used_at         DATETIME NULLABLE
INDEX (user_id, expires_at)
```
OTP codes expire after 10 minutes. Mark `used_at` on success — never delete rows.

### brent_prices (daily Brent crude from FRED)
```
date            DATE PRIMARY KEY   — trading day (no weekends/holidays)
price_usd       DECIMAL(8,2)       — spot price USD per barrel
```
Populated daily by `OilPriceService::fetchBrentPrices()` via FRED API.
FRED returns `"."` for non-trading days — these are filtered out before insert.
Upserted on refetch so duplicate dates never occur.

### price_predictions (oil price direction forecast)
```
id              BIGINT UNSIGNED AUTO_INCREMENT
predicted_for   DATE               — the date this prediction covers
source          ENUM('llm','ewma') — which method generated it
direction       ENUM('rising','falling','flat')
confidence      TINYINT            — 0–100 (LLM max 85, EWMA max 65)
reasoning       TEXT NULLABLE      — plain-English explanation
generated_at    DATETIME

INDEX (predicted_for, source)
```
Generated daily by `OilPriceService::generatePrediction()`.
LLM (Anthropic) is tried first; EWMA is used as fallback if LLM fails or key not set.
Signal 4 in AlertScoringService reads from this table — never from brent_prices directly.

## Supermarket brands (StationTaggingService)

Match station `name` (case-insensitive) against:
`['tesco', 'asda', 'morrisons', 'sainsbury', 'aldi', 'lidl', 'costco']`
Set `is_supermarket = 1` and normalise `brand` on match.