CONTRACTS.md · Drophawk

2032 lines · markdown
# DropHawk - Binding Contracts (Addendum to SPEC.md)
 
> **Status:** BINDING. Where this file and SPEC.md disagree, **this file wins**.
> **Purpose:** Close every ambiguity in SPEC.md. Pin every version. Specify every schema byte. No settling.
> **Reading order:** Read SPEC.md sections 1-6 for context, then read this entire file before writing any code. Every section here overrides any soft language in SPEC.md.
 
This document corrects the original spec to current upstream versions (verified June 2026):
- **Next.js 16.2.9** (not 14) - App Router, Server Components, React 19
- **Tailwind CSS 4.3.1** (not v3) - CSS-first config via `@theme`, **no `tailwind.config.ts`**
- **React 19.2** - Server Actions, `use()` hook, `useFormState`
- **Grafana 13.0.2**, **NATS 2.14.2**, **Caddy 2.11.4**, **Axum 0.8.9**, **Meilisearch 1.47.0**
 
---
 
## §A. Pinned Versions (exact - do not bump without re-running CI matrix)
 
### A.1 Backend (Rust) - `backend/Cargo.toml`
```toml
[package]
name = "drophawk-backend"
version = "0.1.0"
edition = "2021"
rust-version = "1.96"
 
[dependencies]
tokio = { version = "=1.45.1", features = ["full", "parking_lot", "tracing"] }
axum = { version = "=0.8.4", features = ["macros", "tokio", "ws"] }
tower = "=0.5.2"
tower-http = { version = "=0.6.6", features = ["cors", "trace", "compression-br", "compression-gzip", "timeout", "request-id"] }
hyper = { version = "=1.6.0", features = ["full"] }
reqwest = { version = "=0.12.22", default-features = false, features = ["json", "gzip", "brotli", "rustls-tls", "http2", "stream"] }
rquest = { version = "=5.0.0", features = ["impersonate", "json"] }   # TLS fingerprinting, Phase 3+
sqlx = { version = "=0.8.6", features = ["runtime-tokio-rustls", "postgres", "macros", "migrate", "chrono", "json", "ipnetwork"] }
async-nats = "=0.41.0"
redis = { version = "=0.32.3", features = ["tokio-rustls-comp", "connection-manager"] }
serde = { version = "=1.0.219", features = ["derive"] }
serde_json = { version = "=1.0.140", features = ["preserve_key_order", "raw_value"] }
chrono = { version = "=0.4.41", features = ["serde", "clock"], default-features = false }
uuid = { version = "=1.17.0", features = ["v7", "serde"] }
sha2 = "=0.10.9"
hex = "=0.4.3"
tracing = "=0.1.41"
tracing-subscriber = { version = "=0.3.19", features = ["env-filter", "json", "registry"] }
opentelemetry = "=0.29.0"
opentelemetry-otlp = "=0.29.0"
opentelemetry_sdk = { version = "=0.29.0", features = ["rt-tokio"] }
thiserror = "=2.0.12"
async-trait = "=0.1.88"
validator = { version = "=0.20.0", features = ["derive"] }
figment = { version = "=0.10.19", features = ["env", "toml"] }
anyhow = "=1.0.98"        # binary entry only
prometheus = "=0.14.0"
once_cell = "=1.21.3"
parking_lot = "=0.12.3"
futures = "=0.3.31"
bytes = "=1.10.1"
mime = "=0.3.17"
url = { version = "=2.5.4", features = ["serde"] }
 
[dev-dependencies]
wiremock = "=0.6.3"
tokio-test = "=0.4.4"
pretty_assertions = "=1.4.1"
insta = "=1.43.1"
```
 
**Build profile:**
```toml
[profile.release]
lto = "fat"
codegen-units = 1
strip = "symbols"
panic = "abort"
opt-level = 3
```
 
### A.2 Python scrapers - `scrapers/pyproject.toml`
```toml
[project]
name = "drophawk-scrapers"
version = "0.1.0"
requires-python = "==3.11.*"
 
[tool.uv]
dev-dependencies = [
    "pytest==8.4.1",
    "pytest-asyncio==0.26.0",
    "pytest-cov==6.2.1",
    "vcrpy==7.0.0",
    "respx==0.22.0",
    "ruff==0.12.0",
    "mypy==1.16.0",
]
 
dependencies = [
    "httpx==0.28.1",
    "curl-cffi==0.11.1",
    "selectolax==0.3.29",
    "beautifulsoup4==4.13.4",
    "playwright==1.61.0",
    "playwright-stealth==1.0.6",
    "async-nats==0.41.0",
    "pydantic==2.11.7",
    "tenacity==9.1.2",
    "python-dotenv==1.1.0",
    "orjson==3.11.0",
    "structlog==25.4.0",
    "fake-useragent==2.2.0",
    "cssselect==1.3.0",
]
```
 
**Lockfile:** Commit `uv.lock`. CI runs `uv sync --frozen`.
 
### A.3 Frontend - `frontend/package.json`
```json
{
  "name": "drophawk-frontend",
  "private": true,
  "type": "module",
  "engines": { "node": ">=20.9.0", "pnpm": ">=9.0.0" },
  "packageManager": "pnpm@9.18.2",
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "next start -H 0.0.0.0 -p 3000",
    "lint": "next lint",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "test:e2e": "playwright test",
    "format": "prettier --write ."
  },
  "dependencies": {
    "next": "16.2.9",
    "react": "19.2.0",
    "react-dom": "19.2.0",
    "@tanstack/react-query": "5.101.0",
    "@tanstack/react-virtual": "3.13.12",
    "zustand": "5.0.8",
    "react-hook-form": "7.62.0",
    "@hookform/resolvers": "3.10.0",
    "zod": "3.25.76",
    "framer-motion": "12.40.0",
    "lucide-react": "0.475.0",
    "cmdk": "1.1.1",
    "sonner": "1.7.4",
    "date-fns": "4.1.0",
    "clsx": "2.1.1",
    "tailwind-merge": "3.3.1",
    "class-variance-authority": "0.7.1",
    "@radix-ui/react-dialog": "1.1.17",
    "@radix-ui/react-dropdown-menu": "2.1.16",
    "@radix-ui/react-popover": "1.1.16",
    "@radix-ui/react-select": "2.1.16",
    "@radix-ui/react-switch": "1.1.16",
    "@radix-ui/react-tabs": "1.1.16",
    "@radix-ui/react-tooltip": "1.1.17",
    "@radix-ui/react-toast": "1.2.16",
    "@radix-ui/react-label": "2.1.14",
    "@radix-ui/react-slot": "1.3.0",
    "recharts": "3.2.1"
  },
  "devDependencies": {
    "@types/node": "22.19.0",
    "@types/react": "19.2.0",
    "@types/react-dom": "19.2.0",
    "typescript": "5.9.2",
    "tailwindcss": "4.3.1",
    "@tailwindcss/postcss": "4.3.1",
    "postcss": "8.5.6",
    "autoprefixer": "10.4.21",
    "prettier": "3.6.2",
    "prettier-plugin-tailwindcss": "0.7.1",
    "eslint": "9.32.0",
    "eslint-config-next": "16.2.9",
    "@eslint/js": "9.32.0",
    "typescript-eslint": "8.38.0",
    "vitest": "3.2.4",
    "@vitejs/plugin-react": "5.0.0",
    "@testing-library/react": "16.3.0",
    "@testing-library/jest-dom": "6.6.3",
    "@playwright/test": "1.61.0"
  }
}
```
 
> **Note on Tremor:** Original spec mentioned `@tremor/react` but it's stale (last release Jan 2025). Use **Recharts 3.2.1 + custom shadcn-style chart wrappers** instead. This is the upgraded choice.
 
### A.4 Infrastructure - `docker-compose.yml` image tags
```yaml
postgres:        postgres:16.10-bookworm       # with timescaledb-tsl via build
redis:           redis:7.4.3-alpine3.21
nats:            nats:2.14.2-alpine3.21        # with -js flag for JetStream
meilisearch:     getmeili/meilisearch:v1.47.0
ntfy:            binwiederhier/ntfy:v2.14.0
minio:           minio/minio:RELEASE.2026-01-15T01-00-00Z
prometheus:      prom/prometheus:v3.4.1
grafana:         grafana/grafana-oss:13.0.2
loki:            grafana/loki:3.5.5
caddy:           caddy:2.11.4-alpine
```
 
### A.5 Tools
- Rust: `1.96.0` via `rustup toolchain install 1.96.0`
- Node: `20.20.2` (LTS Iron, already installed) - frontend requires `>=20.9.0` ✓
- pnpm: `9.18.2` (install via `corepack enable && corepack prepare pnpm@9.18.2 --activate`)
- Python: `3.11.2` (already installed)
- uv: `0.7.0` (install via `curl -LsSf https://astral.sh/uv/0.7.0/install.sh | sh`)
- Docker: `>=24.0` on homelab host
- Docker Compose: `v2.30+` (plugin form)
 
---
 
## §B. Exact API Contracts
 
All paths under `/api`. All request bodies `application/json; charset=utf-8`. All responses `application/json; charset=utf-8` (except SSE). Timestamps RFC3339 UTC with `Z` suffix. Money fields in **minor units** (cents) as integer. Money formatting for display happens client-side.
 
### B.1 Response envelope
 
**Success (single resource):**
```json
{ "data": { /* resource */ }, "meta": { "request_id": "uuid-v7", "version": "v1" } }
```
 
**Success (collection):**
```json
{
  "data": [ /* resources */ ],
  "meta": {
    "request_id": "01HXY...",
    "version": "v1",
    "page": 1,
    "per_page": 50,
    "total": 1234,
    "total_pages": 25
  }
}
```
 
**Error:**
```json
{
  "error": {
    "code": "SOURCE_NOT_FOUND",
    "message": "No source with id 'stubhub'",
    "request_id": "01HXY...",
    "details": { /* optional, schema-specific */ }
  }
}
```
 
### B.2 Error code → HTTP status table (complete)
 
| Code | HTTP | When |
|---|---|---|
| `BAD_REQUEST` | 400 | Malformed JSON, missing required field |
| `VALIDATION_FAILED` | 422 | Zod-equivalent schema fail; `details.fields[]` lists errors |
| `UNAUTHORIZED` | 401 | Missing/invalid session token (Phase 7+ auth) |
| `FORBIDDEN` | 403 | Authenticated but not allowed |
| `NOT_FOUND` | 404 | Resource id does not exist |
| `CONFLICT` | 409 | Watchlist rule duplicate |
| `RATE_LIMITED` | 429 | Client rate limited (per IP, 100 req/min) |
| `INTERNAL` | 500 | Unhandled; full trace in logs only, never response |
| `UPSTREAM_UNAVAILABLE` | 503 | DB/NATS/Redis unreachable |
| `NOT_IMPLEMENTED` | 501 | v2+ endpoint called in v1 build |
 
### B.3 Endpoints - full contracts
 
#### `GET /api/events`
Query params (all optional):
| Param | Type | Default | Notes |
|---|---|---|---|
| `page` | int ≥1 | 1 | |
| `per_page` | int 1-100 | 50 | |
| `category` | enum | - | `concert,sports,festival,theater,other` (comma list) |
| `sport` | enum | - | `nfl,nba,nhl,mlb,tennis,f1,soccer,other` |
| `source_id` | enum | - | comma list |
| `status` | enum | - | `announced,presale,onsale,soldout,cancelled` |
| `price_min_usd_cents` | int | - | filters `price_min >=` |
| `price_max_usd_cents` | int | - | filters `price_max <=` |
| `starts_after` | RFC3339 | - | `starts_at >=` |
| `starts_before` | RFC3339 | - | `starts_at <=` |
| `on_sale_after` | RFC3339 | - | `on_sale_at >=` |
| `q` | string | - | trigram search on title |
| `sort` | enum | `on_sale` | `on_sale,-starts_at,price_min,-first_seen_at` |
 
Response `data[]` element:
```json
{
  "id": 12345,
  "source_id": "ticketmaster",
  "source_event_id": "Z1p2q3r4s5t6",
  "title": "Taylor Swift | The Eras Tour",
  "subtitle": "with Paramore",
  "category": "concert",
  "sport": null,
  "starts_at": "2026-08-12T23:59:00Z",
  "venue_name": "Hard Rock Stadium",
  "city": "Miami Gardens",
  "country": "US",
  "latitude": 25.958,
  "longitude": -80.239,
  "image_url": "https://.../eras.jpg",
  "on_sale_at": "2026-06-22T15:00:00Z",
  "presale_on_sale_at": "2026-06-19T15:00:00Z",
  "status": "onsale",
  "price_min": 4950,
  "price_max": 89900,
  "currency": "USD",
  "inventory_remaining": 15234,
  "buy_url": "https://www.ticketmaster.com/event/Z1p2q3r4s5t6",
  "first_seen_at": "2026-06-15T10:00:00Z",
  "updated_at": "2026-06-22T15:00:03Z"
}
```
 
#### `GET /api/events/:id`
Single event + `price_history[]` (last 30 days, max 1000 points) + `cross_source_links[]` (see §Q).
 
#### `GET /api/drops`
Query params: `page`, `per_page`, `drop_type` (`new,status,price,inventory,announcement`), `category`, `source_id`, `since` (RFC3339), `until`. Sort fixed `detected_at DESC`.
 
Response `data[]` element:
```json
{
  "id": 987654,
  "event_id": 12345,
  "drop_type": "status",
  "from_state": { "status": "announced" },
  "to_state":   { "status": "onsale" },
  "detected_at": "2026-06-22T15:00:01.234Z",
  "notified": true,
  "notified_at": "2026-06-22T15:00:02.891Z",
  "event": { /* embedded Event, same shape as B.3 */ }
}
```
 
#### `GET /api/drops/stream` (SSE)
Response headers:
```
Content-Type: text/event-stream; charset=utf-8
Cache-Control: no-cache, no-transform
Connection: keep-alive
X-Accel-Buffering: no        # disable proxy buffering
```
 
Wire protocol - each event:
```
event: drop.status
id: 987654
data: {"id":987654,"event_id":12345,"drop_type":"status","detected_at":"2026-06-22T15:00:01.234Z","event":{...}}
 
```
 
(trailing blank line mandatory)
 
Heartbeat every 15s:
```
: heartbeat 1719064800
 
```
 
Reconnect: client reads `Last-Event-ID` header → server replays from that drop id forward on reconnect (query `drops WHERE id > $last_event_id ORDER BY id ASC LIMIT 500`), then switches to live tail.
 
Event types (complete enum): `drop.new`, `drop.status`, `drop.price`, `drop.inventory`, `drop.announcement`, `source.health` (status changes), `system.info`.
 
#### `GET /api/watchlist`
Response `data[]`:
```json
{
  "id": 12,
  "kind": "artist",
  "pattern": "(?i)\\btaylor\\s+swift\\b",
  "label": "Taylor Swift",
  "active": true,
  "priority": "critical",
  "matches_30d": 47,
  "created_at": "2026-06-01T00:00:00Z"
}
```
 
#### `POST /api/watchlist`
Request:
```json
{
  "kind": "artist",
  "pattern": "(?i)\\btaylor\\s+swift\\b",
  "label": "Taylor Swift",
  "priority": "critical"
}
```
- `kind` ∈ {`artist`, `team`, `venue`, `sport`, `category`, `keyword`, `twitter_account`}
- `pattern` is a Rust regex (`regex` crate syntax). Server validates by compiling it; 422 on failure.
- `priority` ∈ {`low`, `normal`, `high`, `critical`}, default `normal`.
- 409 if `(kind, pattern)` already exists.
 
#### `PATCH /api/watchlist/:id`
Partial update: `active`, `priority`, `label`. Cannot change `kind` or `pattern` (delete and recreate).
 
#### `DELETE /api/watchlist/:id` → 204 No Content
 
#### `POST /api/watchlist/bulk`
Request: `{ "rules": [{ "kind":"keyword","label":"Coldplay" }, ...] }`
For each rule, server auto-generates pattern as `(?i)\b<escaped_label>\b`. Returns `{ "data": { "created": N, "skipped_duplicates": M } }`.
 
#### `GET /api/sources`
Response `data[]`:
```json
{
  "id": "ticketmaster",
  "name": "Ticketmaster Discovery API",
  "category": "primary",
  "enabled": true,
  "status": "healthy",
  "last_poll_at": "2026-06-22T15:05:01Z",
  "last_success_at": "2026-06-22T15:05:01Z",
  "last_error": null,
  "consecutive_failures": 0,
  "poll_interval_s": 300,
  "tight_interval_s": 10,
  "latency_ms_p50": 142,
  "latency_ms_p95": 380,
  "events_seen_24h": 1842
}
```
`status` ∈ {`healthy`, `degraded`, `down`, `disabled`}.
 
#### `GET /api/sources/:id`
One source + timeseries `health[]` (last 24h, 5-min buckets) for sparkline.
 
#### `PATCH /api/sources/:id`
Body: `{ "enabled": true }`. Toggles polling.
 
#### `GET /api/stats`
Response:
```json
{
  "drops_24h": 87,
  "drops_7d": 612,
  "sources_healthy": 14,
  "sources_total": 18,
  "sources_down": 1,
  "watchlist_matches_24h": 23,
  "detection_latency_ms_p50": 412,
  "detection_latency_ms_p99": 8200,
  "events_tracked": 28471,
  "events_onsale_now": 318
}
```
 
#### `GET /api/explore?q=`
Proxy to Meilisearch `POST /indexes/events/search` with `{ "q": "<q>", "limit": 25 }`. Return matches with highlight.
 
#### `GET /api/health` → `200 {"status":"ok"}`
#### `GET /api/ready` → 200 only if Postgres + NATS + Redis all reachable; else 503.
 
#### `POST /api/notifications/test`
Triggers a test push to ntfy. Returns `{ "data": { "sent": true, "topic": "drophawk-drops" } }`.
 
---
 
## §C. Exact Polling Algorithm
 
Per-source task pseudocode (Rust). This is the canonical scheduler loop. Implement exactly.
 
```rust
// pseudo-Rust, every detail matters
async fn run_source_loop(adapter: Arc<dyn SourceAdapter>, state: Arc<AppState>) {
    let mut backoff = ExponentialBackoff::new(Duration::from_secs(2), Duration::from_secs(600));
    let mut last_known_drops_within_window: Vec<DateTime<Utc>> = vec![];
 
    loop {
        // 1. Compute next interval using adapter hint
        let now = Utc::now();
        let ctx = PollContext { now, /* ... */ };
        let base_interval = adapter.next_poll_hint(&ctx);
        let interval = backoff.next_or(base_interval);
 
        // 2. Acquire rate-limit token from Redis (block until available)
        state.cache.acquire_token(&format!("rl:{}", adapter.id())).await;
 
        // 3. Poll
        let t0 = Instant::now();
        let result = adapter.poll(&ctx).await;
        let latency = t0.elapsed();
 
        match result {
            Ok(candidates) => {
                backoff.reset();
 
                // 4. Persist source_health row (TimescaleDB)
                state.store.record_source_health(SourceHealth {
                    source_id: adapter.id().into(),
                    observed_at: now,
                    ok: true,
                    latency_ms: latency.as_millis() as i32,
                    events_returned: candidates.len() as i32,
                    error: None,
                }).await;
 
                // 5. Detect + emit (see §D, §E)
                for candidate in candidates {
                    detect::ingest_candidate(&state, &candidate).await;
                }
 
                // 6. Update sources table
                state.store.mark_source_success(adapter.id(), now).await;
 
                // 7. Reset circuit breaker
                state.metrics.source_poll_total
                    .with_label_values(&[adapter.id(), "ok"]).inc();
            }
            Err(SourceError::RateLimited { retry_after }) => {
                // Honor Retry-After, even if it overrides base interval
                backoff.force_retry_after(retry_after.unwrap_or(Duration::from_secs(60)));
                state.store.mark_source_failure(adapter.id(), "rate_limited").await;
                state.metrics.source_poll_total
                    .with_label_values(&[adapter.id(), "rate_limited"]).inc();
            }
            Err(e) => {
                let failures = state.store.mark_source_failure(adapter.id(), &e.to_string()).await;
                state.metrics.source_poll_total
                    .with_label_values(&[adapter.id(), "error"]).inc();
                // Circuit breaker: 3 → degraded, 10 → down + alert
                if failures == 3 {
                    state.store.set_source_status(adapter.id(), "degraded").await;
                    state.bus.publish("source.health", SourceHealthEvent::degraded(adapter.id()));
                } else if failures == 10 {
                    state.store.set_source_status(adapter.id(), "down").await;
                    state.bus.publish("source.health", SourceHealthEvent::down(adapter.id()));
                    notify::push_critical(&state, format!("Source {} is DOWN", adapter.name())).await;
                }
                tokio::time::sleep(backoff.next()).await;
                continue;
            }
        }
 
        tokio::time::sleep(interval).await;
    }
}
```
 
`ExponentialBackoff`:
- start: 2s, factor: 2, max: 600s, jitter: ±15% (use `rand` crate `SmallRng` seeded from `Instant::now()`)
- `force_retry_after(d)` overrides next sleep to exactly `d` (no jitter).
 
### C.1 Adaptive interval rule (`next_poll_hint` default impl)
 
```rust
fn next_poll_hint(&self, ctx: &PollContext) -> Duration {
    // Find nearest known on_sale_at for this source within ±24h
    let nearest = ctx.upcoming_drops_for(self.id())
        .min_by_key(|d| (d - ctx.now()).abs());
 
    match nearest {
        Some(t) if (t - ctx.now()).num_seconds().abs() <= 900 => Duration::from_secs(10),
        Some(t) if (t - ctx.now()).num_seconds().abs() <= 3600 => Duration::from_secs(30),
        Some(t) if (t - ctx.now()).num_seconds().abs() <= 14400 => Duration::from_secs(60),
        _ => Duration::from_secs(300),
    }
}
```
 
Distance-to-drop → interval:
| Distance | Interval |
|---|---|
| ≤ 15 min | **10 s** |
| ≤ 1 h | 30 s |
| ≤ 4 h | 60 s |
| else | 5 min |
 
### C.2 Fast-path shock drop detection (Phase 6+)
For sources where shock drops are likely (FIFA last-minute, Twitter monitor), the source adapter may publish a "wake" signal on NATS subject `wake.{source_id}`. Any Rust poll loop subscribed to its own wake channel short-circuits its sleep. This gives **sub-10-second** detection when a shock drop is detected by a different signal (e.g. tweet lands).
 
---
 
## §D. Hash Canonicalization (exact bytes)
 
The `content_hash` is SHA-256 over the canonical JSON of a **fixed field set** in **alphabetical key order** with **specific normalizations**. Implement exactly.
 
### D.1 Field set (these and ONLY these participate in hash)
1. `source_event_id` (string, trimmed)
2. `status` (lowercase enum string)
3. `on_sale_at` (RFC3339 UTC, millisecond precision, `null` if None)
4. `presale_on_sale_at` (same format)
5. `price_min` (int cents, `null` if None)
6. `price_max` (int cents, `null` if None)
7. `inventory_remaining` (int, `null` if None)
 
### D.2 Normalization rules
- Datetime → format as `YYYY-MM-DDTHH:MM:SS.sssZ` (always 3 ms digits, always `Z`). Strip sub-millisecond precision.
- Integers stay as integers, never scientific notation.
- None → JSON `null`.
- Strings → UTF-8, trimmed of leading/trailing whitespace.
- All keys sorted lexicographically (use `BTreeMap<&str, Value>`).
- No whitespace between tokens: `serde_json::to_string` with compact formatter.
- Output hex lowercase.
 
### D.3 Reference implementation
```rust
use serde_json::{json, Value};
use sha2::{Digest, Sha256};
 
pub fn content_hash(c: &EventCandidate) -> String {
    let canonical = json!({
        "inventory_remaining": c.inventory_remaining.map(|v| v as i64),
        "on_sale_at": c.on_sale_at.map(|dt| dt.to_rfc3339_opts(SecondsFormat::Millis, true)),
        "presale_on_sale_at": c.presale_on_sale_at.map(|dt| dt.to_rfc3339_opts(SecondsFormat::Millis, true)),
        "price_max": c.price_max,
        "price_min": c.price_min,
        "source_event_id": c.source_event_id.trim(),
        "status": c.status.as_str().to_lowercase(),
    });
    // serde_json::Map preserves insertion order with preserve_key_order feature.
    // We built it in alphabetical order above to guarantee.
    let bytes = serde_json::to_vec(&canonical).expect("canonical serializable");
    let mut hasher = Sha256::new();
    hasher.update(&bytes);
    hex::encode(hasher.finalize())
}
```
 
### D.4 Golden test (must pass)
Add `backend/tests/hash_golden.rs` with vectors:
```json
{"inventory_remaining":15234,"on_sale_at":"2026-06-22T15:00:00.000Z","presale_on_sale_at":null,"price_max":89900,"price_min":4950,"source_event_id":"Z1p2q3r4s5t6","status":"onsale"}
```
→ expected hash: `a3f1e8...` (commit the exact hash once the impl is verified; this is the regression gate).
 
---
 
## §E. Drop Detection & Classification
 
On every `EventCandidate` ingest:
 
```rust
async fn ingest_candidate(state: &AppState, c: &EventCandidate) {
    let new_hash = content_hash(c);
 
    // 1. Lookup existing event by (source_id, source_event_id)
    let existing = state.store.find_event(c.source_id, &c.source_event_id).await?;
 
    match existing {
        None => {
            // NEW EVENT
            let event_id = state.store.insert_event(c, &new_hash).await?;
            emit_drop(state, DropEvent {
                event_id,
                drop_type: "new",
                from_state: json!(null),
                to_state: json!({"status": c.status, "on_sale_at": c.on_sale_at}),
            }).await;
        }
        Some(prev) if prev.content_hash == new_hash => {
            // UNCHANGED - no-op, just touch updated_at? No, don't even touch.
            return Ok(());
        }
        Some(prev) => {
            // CHANGED - diff fields, emit one or more drops
            state.store.update_event(prev.id, c, &new_hash).await?;
 
            if prev.status != c.status {
                emit_drop(state, DropEvent {
                    event_id: prev.id,
                    drop_type: "status",
                    from_state: json!({"status": prev.status}),
                    to_state:   json!({"status": c.status}),
                }).await;
            }
            if let (Some(prev_min), Some(new_min)) = (prev.price_min, c.price_min) {
                if new_min < prev_min && (prev_min - new_min) * 100 / prev_min.max(1) >= 10 {
                    emit_drop(state, DropEvent {
                        event_id: prev.id,
                        drop_type: "price",
                        from_state: json!({"price_min": prev_min}),
                        to_state:   json!({"price_min": new_min}),
                    }).await;
                }
            }
            if let (Some(prev_inv), Some(new_inv)) = (prev.inventory_remaining, c.inventory_remaining) {
                if new_inv < prev_inv && (prev_inv - new_inv) * 100 / prev_inv.max(1) >= 25 {
                    emit_drop(state, DropEvent {
                        event_id: prev.id,
                        drop_type: "inventory",
                        from_state: json!({"inventory_remaining": prev_inv}),
                        to_state:   json!({"inventory_remaining": new_inv}),
                    }).await;
                }
            }
        }
    }
}
```
 
`emit_drop` writes to `drops` table, publishes to NATS `drop.{type}`, broadcasts via SSE channel, and triggers `notify::on_drop`.
 
A single candidate change can emit multiple drops (e.g. status + price). That's intentional.
 
---
 
## §F. TLS Fingerprint & Header Coherence
 
### F.1 Sources requiring browser impersonation (use `rquest`)
- FIFA portal, AXS, StubHub, Vivid Seats, Twitter/X scrape, festival portals, all per-club soccer adapters.
 
### F.2 Impersonation target rotation
Use `rquest::Impersonate`:
- `Chrome131` (default)
- `Chrome130`
- `Safari18`
- `Safari17`
- `Firefox133`
 
**Rotation rule:** Each scraper process picks ONE impersonation per session at startup (process-wide). Rotate at restart, not per request - fingerprint stability per IP is what looks human.
 
### F.3 Header coherence (CRITICAL)
The following must always come from the SAME impersonation set - never mix:
- TLS JA3/JA4 (controlled by rquest)
- User-Agent
- `sec-ch-ua`, `sec-ch-ua-mobile`, `sec-ch-ua-platform`
- `accept-language`
- `accept-encoding`
- HTTP/2 settings (controlled by rquest)
 
Source `scrapers/anti_bot/fingerprints.py` defines named bundles. Each bundle is one tuple. Bundles are checked into the repo as `fingerprints.json`. Update bundles **monthly** by running `scripts/refresh-fingerprints.py` (pulls latest from `wrappers.json` or hand-curated).
 
### F.4 Proxy rotation (Phase 6+)
- Interface: `ProxyPool.pick() -> ProxySpec`.
- Default impl: single proxy from env (`PROXY_POOL_URL`), or `Direct` if unset.
- Future impls: BrightData, Smartproxy, self-hosted rotating.
- Per-source proxy affinity: hash `source_id` → fixed proxy within a 24h window. This gives IP stability per source (looks human) while distributing load across sources.
 
### F.5 robots.txt enforcement
On first poll of any source, fetch and parse `/robots.txt`. Cache in Redis for 24h. If the requested path is disallowed for our UA, **mark source `disabled` and alert operator**. Do not bypass.
 
---
 
## §G. Complete Database DDL
 
Replace §8 of SPEC.md with this complete, runnable SQL.
 
### G.1 `backend/migrations/20260101000000_extensions.sql`
```sql
CREATE EXTENSION IF NOT EXISTS "pg_trgm";
CREATE EXTENSION IF NOT EXISTS timescaledb;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
```
 
### G.2 `20260101000001_sources.sql`
```sql
CREATE TABLE sources (
    id                   TEXT PRIMARY KEY,
    name                 TEXT NOT NULL,
    category             TEXT NOT NULL CHECK (category IN ('primary','resale','sports','festival','social')),
    enabled              BOOLEAN NOT NULL DEFAULT TRUE,
    status               TEXT NOT NULL DEFAULT 'healthy'
                         CHECK (status IN ('healthy','degraded','down','disabled')),
    poll_interval_s      INTEGER NOT NULL DEFAULT 300 CHECK (poll_interval_s BETWEEN 1 AND 86400),
    tight_interval_s     INTEGER NOT NULL DEFAULT 10  CHECK (tight_interval_s BETWEEN 1 AND 3600),
    last_poll_at         TIMESTAMPTZ,
    last_success_at      TIMESTAMPTZ,
    last_error           TEXT,
    consecutive_failures INTEGER NOT NULL DEFAULT 0 CHECK (consecutive_failures >= 0),
    created_at           TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at           TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
 
CREATE TRIGGER sources_set_updated_at
    BEFORE UPDATE ON sources
    FOR EACH ROW EXECUTE FUNCTION set_updated_at();
```
 
### G.3 `20260101000002_set_updated_at_fn.sql`
```sql
CREATE OR REPLACE FUNCTION set_updated_at() RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at := NOW();
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;
```
 
### G.4 `20260101000003_events.sql`
```sql
CREATE TABLE events (
    id                   BIGSERIAL PRIMARY KEY,
    source_id            TEXT NOT NULL REFERENCES sources(id) ON DELETE RESTRICT,
    source_event_id      TEXT NOT NULL,
    title                TEXT NOT NULL CHECK (length(title) BETWEEN 1 AND 512),
    subtitle             TEXT,
    category             TEXT NOT NULL CHECK (category IN ('concert','sports','festival','theater','other')),
    sport                TEXT CHECK (sport IS NULL OR sport IN ('nfl','nba','nhl','mlb','tennis','f1','soccer','golf','boxing','other')),
    starts_at            TIMESTAMPTZ,
    venue_name           TEXT,
    city                 TEXT,
    country              CHAR(2),                -- ISO 3166-1 alpha-2
    latitude             DOUBLE PRECISION CHECK (latitude IS NULL OR (latitude BETWEEN -90 AND 90)),
    longitude            DOUBLE PRECISION CHECK (longitude IS NULL OR (longitude BETWEEN -180 AND 180)),
    image_url            TEXT,
    on_sale_at           TIMESTAMPTZ,
    presale_on_sale_at   TIMESTAMPTZ,
    status               TEXT NOT NULL CHECK (status IN ('announced','presale','onsale','soldout','cancelled')),
    price_min            INTEGER CHECK (price_min IS NULL OR price_min >= 0),
    price_max            INTEGER CHECK (price_max IS NULL OR price_max >= 0),
    currency             CHAR(3),                -- ISO 4217
    inventory_remaining  INTEGER CHECK (inventory_remaining IS NULL OR inventory_remaining >= 0),
    buy_url              TEXT NOT NULL,
    raw                  JSONB,
    content_hash         CHAR(64) NOT NULL,
    first_seen_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at           TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    UNIQUE (source_id, source_event_id),
    CONSTRAINT price_range CHECK (price_min IS NULL OR price_max IS NULL OR price_min <= price_max)
);
 
CREATE INDEX idx_events_status           ON events(status);
CREATE INDEX idx_events_on_sale          ON events(on_sale_at) WHERE on_sale_at IS NOT NULL;
CREATE INDEX idx_events_category         ON events(category);
CREATE INDEX idx_events_sport            ON events(sport) WHERE sport IS NOT NULL;
CREATE INDEX idx_events_starts_at        ON events(starts_at) WHERE starts_at IS NOT NULL;
CREATE INDEX idx_events_source_status    ON events(source_id, status);
CREATE INDEX idx_events_updated_at       ON events(updated_at DESC);
CREATE INDEX idx_events_title_trgm       ON events USING gin (title gin_trgm_ops);
CREATE INDEX idx_events_starts_at_source ON events(starts_at, source_id);
 
CREATE TRIGGER events_set_updated_at
    BEFORE UPDATE ON events
    FOR EACH ROW EXECUTE FUNCTION set_updated_at();
```
 
### G.5 `20260101000004_drops.sql`
```sql
CREATE TABLE drops (
    id              BIGSERIAL PRIMARY KEY,
    event_id        BIGINT NOT NULL REFERENCES events(id) ON DELETE CASCADE,
    drop_type       TEXT NOT NULL CHECK (drop_type IN ('new','status','price','inventory','announcement')),
    from_state      JSONB,
    to_state        JSONB NOT NULL,
    detected_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    detected_at_ms  BIGINT GENERATED ALWAYS AS (EXTRACT(EPOCH FROM detected_at) * 1000) STORED,
    notified        BOOLEAN NOT NULL DEFAULT FALSE,
    notified_at     TIMESTAMPTZ
);
 
CREATE INDEX idx_drops_detected_desc  ON drops(detected_at DESC);
CREATE INDEX idx_drops_event          ON drops(event_id);
CREATE INDEX idx_drops_type           ON drops(drop_type);
CREATE INDEX idx_drops_type_detected  ON drops(drop_type, detected_at DESC);
 
-- TimescaleDB hypertable (drops grow fast; partition by time)
SELECT create_hypertable('drops', 'detected_at', chunk_time_interval => INTERVAL '1 day');
```
 
### G.6 `20260101000005_watchlist.sql`
```sql
CREATE TABLE watchlist (
    id          BIGSERIAL PRIMARY KEY,
    kind        TEXT NOT NULL CHECK (kind IN ('artist','team','venue','sport','category','keyword','twitter_account')),
    pattern     TEXT NOT NULL,                          -- Rust regex syntax
    label       TEXT NOT NULL CHECK (length(label) BETWEEN 1 AND 128),
    active      BOOLEAN NOT NULL DEFAULT TRUE,
    priority    TEXT NOT NULL DEFAULT 'normal' CHECK (priority IN ('low','normal','high','critical')),
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    UNIQUE (kind, pattern)
);
 
CREATE INDEX idx_watchlist_active_kind ON watchlist(active, kind);
CREATE TRIGGER watchlist_set_updated_at
    BEFORE UPDATE ON watchlist
    FOR EACH ROW EXECUTE FUNCTION set_updated_at();
```
 
### G.7 `20260101000006_notifications.sql`
```sql
CREATE TABLE notifications_log (
    id          BIGSERIAL PRIMARY KEY,
    drop_id     BIGINT REFERENCES drops(id) ON DELETE SET NULL,
    channel     TEXT NOT NULL CHECK (channel IN ('ntfy','telegram','email','browser')),
    title       TEXT NOT NULL,
    body        TEXT NOT NULL,
    priority    TEXT NOT NULL CHECK (priority IN ('min','low','default','high','urgent')),
    sent_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    success     BOOLEAN NOT NULL,
    response    TEXT,
    topic       TEXT
);
 
CREATE INDEX idx_notif_sent_desc ON notifications_log(sent_at DESC);
CREATE INDEX idx_notif_drop      ON notifications_log(drop_id);
SELECT create_hypertable('notifications_log', 'sent_at', chunk_time_interval => INTERVAL '7 days');
```
 
### G.8 `20260101000007_timeseries.sql`
```sql
CREATE TABLE price_history (
    event_id    BIGINT NOT NULL REFERENCES events(id) ON DELETE CASCADE,
    source      TEXT NOT NULL,
    observed_at TIMESTAMPTZ NOT NULL,
    price_min   INTEGER,
    price_max   INTEGER,
    currency    CHAR(3)
);
SELECT create_hypertable('price_history', 'observed_at', chunk_time_interval => INTERVAL '7 days');
CREATE INDEX idx_price_event_time ON price_history(event_id, observed_at DESC);
 
CREATE TABLE source_health (
    source_id       TEXT NOT NULL,
    observed_at     TIMESTAMPTZ NOT NULL,
    ok              BOOLEAN NOT NULL,
    latency_ms      INTEGER NOT NULL CHECK (latency_ms >= 0),
    events_returned INTEGER NOT NULL DEFAULT 0,
    error           TEXT
);
SELECT create_hypertable('source_health', 'observed_at', chunk_time_interval => INTERVAL '1 day');
CREATE INDEX idx_health_source_time ON source_health(source_id, observed_at DESC);
 
-- Continuous aggregates for UI sparklines
CREATE MATERIALIZED VIEW source_health_5min
WITH (timescaledb.continuous) AS
SELECT
    source_id,
    time_bucket('5 minutes', observed_at) AS bucket,
    AVG(latency_ms)    AS latency_ms_p50,
    MAX(latency_ms)    AS latency_ms_p95,
    COUNT(*) FILTER (WHERE ok)       AS ok_count,
    COUNT(*) FILTER (WHERE NOT ok)   AS err_count
FROM source_health
GROUP BY source_id, bucket
WITH NO DATA;
 
SELECT add_continuous_aggregate_policy('source_health_5min',
    start_offset => INTERVAL '1 hour',
    end_offset   => INTERVAL '5 minutes',
    schedule_interval => INTERVAL '1 minute');
```
 
### G.9 `20260101000008_detection_latency.sql`
```sql
-- Histogram for the detection_latency_ms metric (SLO §O.3)
CREATE TABLE detection_latency (
    drop_id    BIGINT PRIMARY KEY REFERENCES drops(id) ON DELETE CASCADE,
    latency_ms INTEGER NOT NULL CHECK (latency_ms >= 0)
);
CREATE INDEX idx_latency ON detection_latency(latency_ms);
```
 
### G.10 `20260101000009_cross_source_links.sql` (see §Q)
```sql
CREATE TABLE cross_source_links (
    cluster_id    BIGSERIAL PRIMARY KEY,
    event_id      BIGINT NOT NULL REFERENCES events(id) ON DELETE CASCADE,
    confidence    REAL NOT NULL CHECK (confidence BETWEEN 0 AND 1),
    match_basis   TEXT NOT NULL,   -- 'date+venue' | 'performer_id' | 'title+date'
    created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    UNIQUE (cluster_id, event_id)
);
CREATE INDEX idx_xsrc_event     ON cross_source_links(event_id);
CREATE INDEX idx_xsrc_cluster   ON cross_source_links(cluster_id);
```
 
### G.11 `20260101000010_seed_sources.sql`
```sql
INSERT INTO sources (id, name, category, enabled, poll_interval_s, tight_interval_s) VALUES
    ('ticketmaster', 'Ticketmaster Discovery API', 'primary', TRUE, 300, 10),
    ('seatgeek',     'SeatGeek',                   'primary', TRUE, 300, 10),
    ('fifa',         'FIFA World Cup Portal',      'sports',  TRUE,  60, 30),
    ('axs',          'AXS',                        'primary', FALSE, 300, 10),
    ('seetickets',   'See Tickets',                'primary', FALSE, 300, 10),
    ('stubhub',      'StubHub (resale)',           'resale',  FALSE, 600, 30),
    ('vividseats',   'Vivid Seats (resale)',       'resale',  FALSE, 600, 30),
    ('twitter',      'Twitter/X Shock Drop',       'social',  FALSE, 120, 15),
    ('nfl',          'NFL (Ticketmaster Sports)',  'sports',  FALSE, 300, 10),
    ('nba',          'NBA',                        'sports',  FALSE, 300, 10),
    ('nhl',          'NHL',                        'sports',  FALSE, 300, 10),
    ('mlb',          'MLB',                        'sports',  FALSE, 300, 10),
    ('atp_wta',      'ATP / WTA Tennis',           'sports',  FALSE, 600, 30),
    ('f1',           'Formula 1',                  'sports',  FALSE, 600, 30),
    ('uefa',         'UEFA',                       'sports',  FALSE, 600, 30),
    ('epl',          'Premier League (Big 6)',     'sports',  FALSE, 600, 30),
    ('coachella',    'Coachella',                  'festival',FALSE, 600, 30),
    ('glastonbury',  'Glastonbury',                'festival',FALSE, 600, 30),
    ('tomorrowland', 'Tomorrowland',               'festival',FALSE, 600, 30),
    ('edc',          'EDC',                        'festival',FALSE, 600, 30),
    ('lollapalooza', 'Lollapalooza',               'festival',FALSE, 600, 30)
ON CONFLICT (id) DO NOTHING;
 
INSERT INTO watchlist (kind, pattern, label, priority) VALUES
    ('keyword', '(?i)\btaylor\s+swift\b',     'Taylor Swift',   'critical'),
    ('keyword', '(?i)\bworld\s+cup\b',        'World Cup',      'critical'),
    ('keyword', '(?i)\bsuper\s+bowl\b',       'Super Bowl',     'critical'),
    ('keyword', '(?i)\bwimbledon\b',          'Wimbledon',      'high'),
    ('keyword', '(?i)\bchampions\s+league\s+final\b', 'UCL Final', 'high')
ON CONFLICT (kind, pattern) DO NOTHING;
```
 
### G.12 Retention policy
```sql
-- Drop old data automatically (TimescaleDB)
SELECT add_retention_policy('drops',              INTERVAL '90 days');
SELECT add_retention_policy('price_history',      INTERVAL '1 year');
SELECT add_retention_policy('source_health',      INTERVAL '30 days');
SELECT add_retention_policy('notifications_log',  INTERVAL '90 days');
```
 
### G.13 Migration runner
- sqlx migrate run on startup, before Axum binds.
- Migrations are immutable. Never edit. Always forward-only.
 
---
 
## §H. Design Tokens (exact, OKLCH)
 
### H.1 Tailwind 4 setup - `frontend/app/globals.css`
**Tailwind v4 is CSS-first. There is no `tailwind.config.ts`.** Configuration lives in `@theme` blocks. This is the full theme file.
 
```css
@import "tailwindcss";
 
@theme {
  /* === Color system (OKLCH, dark-first) === */
  /* Backgrounds */
  --color-bg-base:        oklch(0.16 0.012 264);   /* page bg, deep navy-black */
  --color-bg-elevated:    oklch(0.20 0.014 264);   /* card bg */
  --color-bg-overlay:     oklch(0.23 0.014 264);   /* modal/sheet */
  --color-bg-inset:       oklch(0.14 0.012 264);   /* recessed area */
 
  /* Foregrounds */
  --color-fg-primary:     oklch(0.96 0.005 264);
  --color-fg-secondary:   oklch(0.78 0.008 264);
  --color-fg-tertiary:    oklch(0.60 0.010 264);
  --color-fg-disabled:    oklch(0.42 0.008 264);
 
  /* Borders */
  --color-border-subtle:  oklch(0.28 0.014 264 / 0.6);
  --color-border-default: oklch(0.34 0.014 264);
  --color-border-strong:  oklch(0.46 0.014 264);
 
  /* Accents (semantic) */
  --color-accent-teal:    oklch(0.78 0.16 184);    /* primary action */
  --color-accent-teal-hover: oklch(0.72 0.18 184);
  --color-accent-teal-soft:  oklch(0.78 0.16 184 / 0.12);
  --color-accent-amber:   oklch(0.82 0.16 75);     /* warnings */
  --color-accent-red:     oklch(0.66 0.22 25);     /* sold out / error */
  --color-accent-violet:  oklch(0.70 0.18 300);    /* presale */
  --color-accent-green:   oklch(0.74 0.18 145);    /* healthy / on-sale */
  --color-accent-blue:    oklch(0.70 0.16 240);    /* informational */
 
  /* Status pills map */
  --color-status-announced: var(--color-accent-blue);
  --color-status-presale:   var(--color-accent-violet);
  --color-status-onsale:    var(--color-accent-green);
  --color-status-soldout:   var(--color-accent-red);
  --color-status-cancelled: var(--color-fg-tertiary);
 
  /* === Typography === */
  --font-sans: "Inter", "Inter Placeholder", ui-sans-serif, system-ui, sans-serif;
  --font-mono: "JetBrains Mono", ui-monospace, "SF Mono", monospace;
 
  /* Type scale (1.250 major third) */
  --text-xs:   0.64rem;  --text-xs--line-height:   1rem;
  --text-sm:   0.80rem;  --text-sm--line-height:   1.25rem;
  --text-base: 1.00rem;  --text-base--line-height: 1.5rem;
  --text-lg:   1.25rem;  --text-lg--line-height:   1.75rem;
  --text-xl:   1.56rem;  --text-xl--line-height:   2rem;
  --text-2xl:  1.95rem;  --text-2xl--line-height:  2.25rem;
  --text-3xl:  2.44rem;  --text-3xl--line-height:  2.75rem;
  --text-4xl:  3.05rem;  --text-4xl--line-height:  3.25rem;
 
  /* Letter spacing for headings */
  --tracking-tight: -0.02em;
  --tracking-display: -0.04em;
 
  /* === Spacing scale (4px base) === */
  --spacing: 0.25rem; /* 4px - Tailwind v4 default, do not change */
 
  /* === Radii === */
  --radius-sm: 0.375rem;
  --radius:    0.5rem;
  --radius-md: 0.625rem;
  --radius-lg: 0.875rem;
  --radius-xl: 1.25rem;
 
  /* === Shadows (use sparingly; prefer borders) === */
  --shadow-card: 0 1px 2px 0 oklch(0 0 0 / 0.06), 0 1px 3px 0 oklch(0 0 0 / 0.10);
  --shadow-pop:  0 8px 24px -8px oklch(0 0 0 / 0.40);
  --shadow-glow-teal: 0 0 0 1px var(--color-accent-teal-soft), 0 0 24px -4px var(--color-accent-teal-soft);
 
  /* === Motion === */
  /* Framer Motion springs (exported to TS) */
  --motion-spring-snappy:   cubic-bezier(0.22, 1, 0.36, 1);   /* ease-out-expo */
  --motion-spring-natural:  cubic-bezier(0.16, 1, 0.3, 1);
  --motion-spring-entrance: cubic-bezier(0.34, 1.56, 0.64, 1); /* slight overshoot */
 
  /* Durations */
  --duration-instant: 80ms;
  --duration-fast:    150ms;
  --duration-base:    240ms;
  --duration-slow:    400ms;
  --duration-cinematic: 800ms;
 
  /* === Z-index scale === */
  --z-base:    0;
  --z-sticky:  10;
  --z-dropdown:1000;
  --z-sheet:   2000;
  --z-modal:   3000;
  --z-toast:   4000;
  --z-tooltip: 5000;
}
 
/* === Base layer === */
@layer base {
  html { color-scheme: dark; }
  body {
    background-color: var(--color-bg-base);
    color: var(--color-fg-primary);
    font-family: var(--font-sans);
    font-feature-settings: "cv11", "ss01", "ss03";
    -webkit-font-smoothing: antialiased;
    text-rendering: optimizeLegibility;
  }
 
  /* Numeric data uses tabular figures */
  .tabular { font-variant-numeric: tabular-nums; }
 
  /* Selection */
  ::selection { background-color: var(--color-accent-teal-soft); }
 
  /* Scrollbar (WebKit) */
  ::-webkit-scrollbar { width: 10px; height: 10px; }
  ::-webkit-scrollbar-track { background: var(--color-bg-base); }
  ::-webkit-scrollbar-thumb {
    background: var(--color-border-default);
    border-radius: 999px;
    border: 2px solid var(--color-bg-base);
  }
  ::-webkit-scrollbar-thumb:hover { background: var(--color-border-strong); }
 
  /* Reduced motion */
  @media (prefers-reduced-motion: reduce) {
    *, *::before, *::after {
      animation-duration: 0.01ms !important;
      animation-iteration-count: 1 !important;
      transition-duration: 0.01ms !important;
    }
  }
}
 
/* === Utilities === */
@layer utilities {
  .animate-shimmer {
    background: linear-gradient(90deg,
      transparent 0%,
      var(--color-accent-teal-soft) 50%,
      transparent 100%);
    background-size: 200% 100%;
    animation: shimmer 1.2s ease-out;
  }
  @keyframes shimmer {
    0%   { background-position: 200% 0; }
    100% { background-position: -200% 0; }
  }
 
  .pulse-ring::after {
    content: "";
    position: absolute;
    inset: 0;
    border-radius: inherit;
    box-shadow: 0 0 0 0 var(--color-accent-green);
    animation: pulse-ring 2s var(--motion-spring-natural) infinite;
  }
  @keyframes pulse-ring {
    0%   { box-shadow: 0 0 0 0 oklch(0.74 0.18 145 / 0.6); }
    100% { box-shadow: 0 0 0 12px oklch(0.74 0.18 145 / 0); }
  }
}
```
 
### H.2 Type scale → Tailwind utility mapping
Use Tailwind v4's automatic theme→utility mapping: `text-xs`, `text-sm`, …, `text-4xl` are auto-generated from the `--text-*` vars above. No `tailwind.config.ts` needed.
 
### H.3 Framer Motion spring presets (`frontend/lib/motion.ts`)
```ts
export const springs = {
  snappy:    { type: "spring", stiffness: 580, damping: 32, mass: 0.8 },
  natural:   { type: "spring", stiffness: 320, damping: 28, mass: 1.0 },
  entrance:  { type: "spring", stiffness: 240, damping: 18, mass: 1.2 }, // slight overshoot
  sheet:     { type: "spring", stiffness: 280, damping: 34, mass: 1.0 },
  stagger:   { type: "spring", stiffness: 480, damping: 30, mass: 0.6 },
} as const;
 
export const dropCardVariants = {
  initial:   { opacity: 0, y: -16, scale: 0.96 },
  animate:   { opacity: 1, y: 0,   scale: 1, transition: springs.entrance },
  exit:      { opacity: 0, x: 24,  scale: 0.92, transition: { duration: 0.18 } },
} as const;
 
export const flashAccentKeyframes = {
  boxShadow: [
    "0 0 0 0 oklch(0.78 0.16 184 / 0)",
    "0 0 0 4px oklch(0.78 0.16 184 / 0.5)",
    "0 0 0 0 oklch(0.78 0.16 184 / 0)",
  ],
  transition: { duration: 1.6, ease: "easeOut", times: [0, 0.2, 1] },
};
```
 
### H.4 Status pill component (`components/ui/StatusPill.tsx`)
- Padding `px-2.5 py-0.5`, radius `--radius-sm`, font `text-xs font-medium`, tabular nums off.
- Bg = `color-status-{status}` at 12% alpha. Text = same color at 100%.
- Border = same color at 25% alpha.
- Includes leading 6px dot.
- All variants tested against contrast ratio ≥ 4.5:1 against `--color-bg-elevated` (WCAG §U).
 
### H.5 DropCard layout (canonical)
```
┌──────────────────────────────────────────────────────┐
│ [●] On Sale                              3s ago    │   ← status pill + relative time (mono)
├──────────────────────────────────────────────────────┤
│ [IMG 64×64]  Taylor Swift | The Eras Tour         │
│              with Paramore                          │
│              Hard Rock Stadium · Miami Gardens      │
├──────────────────────────────────────────────────────┤
│ $49.50 - $899.00        [TM]    [ Buy → ]          │   ← price + source chip + button
└──────────────────────────────────────────────────────┘
```
- Card padding `p-3.5`, gap between sections `gap-2`.
- New cards: animate in from top with `entrance` spring; flash teal ring for 1.6s.
- Source chip: 24×24 logo or initials; tooltip shows source name.
 
### H.6 Motion budget (do not exceed)
- Max simultaneous animations on dashboard: **40** (use `will-change: transform` sparingly).
- No animation longer than 1.6s except skeleton shimmer (3s loop max).
- Exit animations: ≤200ms.
 
---
 
## §I. ntfy Payload Templates (exact)
 
### I.1 Per drop type - full HTTP request
 
**Status flip (Announced → OnSale), watchlist match:**
```http
POST /drophawk-drops HTTP/1.1
Host: ntfy
Authorization: Bearer tk_xxxxxxxxxxxxxxxxxxxxxxxx
Title: 🎟️ ON SALE NOW: Taylor Swift - Miami
Priority: urgent
Tags: ticket,ticket,concert,ticketmaster
Click: https://www.ticketmaster.com/event/Z1p2q3r4s5t6?drophawk=1
Actions: [{"action":"view","label":"Buy","url":"https://www.ticketmaster.com/event/Z1p2q3r4s5t6?drophawk=1"}]
Cache: no
 
Floor seats from $49.50 · 15,234 remaining
Hard Rock Stadium · Aug 12 2026, 7:00 PM ET
Source: Ticketmaster · detected in 1.2s
```
 
**New event (matching watchlist):**
```
Title: 🆕 NEW: FIFA World Cup 2026 Final - NYC
Priority: high
Tags: soccer,fifa,world_cup
Click: https://tickets.fifa.com/...
```
 
**Price drop ≥25%:**
```
Title: 📉 -32%: Adele - Munich (StubHub)
Priority: high
Tags: arrow_down,concert,stubhub
```
 
**Shock drop (Twitter-triggered, on_sale_at within ±5min of now):**
```
Title: ⚡ SHOCK DROP: Beyoncé added second London show
Priority: urgent
Tags: zap,concert,twitter
```
 
**Test push (`POST /api/notifications/test`):**
```
Title: ✅ DropHawk ntfy test
Priority: default
Tags: white_check_mark
Body: If you can read this, your pipeline works. Detected at {RFC3339 now}.
```
 
### I.2 Priority mapping (LOCKED)
| Drop signal | Watchlist priority | ntfy Priority |
|---|---|---|
| status→onsale | critical | `urgent` |
| status→onsale | high | `high` |
| status→onsale | normal/low | `default` |
| new (watchlist match) | critical | `urgent` |
| new (watchlist match) | high | `high` |
| new (watchlist match) | normal | `default` |
| new (no match) | - | **not sent** (UI only) |
| price ≥25% drop | any | `high` |
| price 10-25% drop | any | `default` |
| inventory ≥25% drop | any | `default` |
| shock drop (Twitter) | any | `urgent` |
 
### I.3 Dedupe rules (anti-spam)
- One ntfy push per `(event_id, drop_type)` per **10 minutes** (Redis key `notif:dedupe:{event_id}:{drop_type}` with TTL 600s).
- Max 5 notifications per minute total (token bucket).
- Max 50 per hour.
- If exceeded: drop quietly, log to `notifications_log` with `success=false, response='rate_limited_self'`.
- Quiet hours (configurable in Settings): default OFF (operator wants to wake up). When on, only `urgent` priority breaks through.
 
### I.4 ntfy server config (`infra/ntfy.server.yml`)
```yaml
base_url: "http://ntfy"
listen: ":80"
cache_file: "/var/lib/ntfy/cache.db"
auth_file: "/var/lib/ntfy/user.db"
auth_default_access: "deny-all"
 
# Behind Caddy already terminates TLS, so internal is HTTP
behind_proxy: true
 
# Attachment limits (we don't use attachments for pushes)
attachment_total_size_limit: "1M"
attachment_file_size_limit: "512K"
 
# Rate limit (per-IP; we don't actually want to limit our own internal publisher,
# so set high)
global_topic_limit: 1000
visitor_request_limit_burst: 100
visitor_request_limit_replenish: "1s"
 
# Enable SMTP? No, not for v1.
```
 
Create admin + publisher tokens at deploy time via `ntfy user add` and `ntfy token create` (one-shot, persisted in MinIO backup bucket for restore).
 
---
 
## §J. Prometheus Metrics Catalog
 
Every metric prefixed `drophawk_`. All histograms use these standard buckets (ms): `[10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000, 60000]`.
 
### J.1 Counters
| Metric | Labels | When |
|---|---|---|
| `drophawk_source_poll_total` | `source`, `result`(ok/error/rate_limited) | end of every poll |
| `drophawk_drops_total` | `type`, `category`, `source` | every emit_drop |
| `drophawk_notifications_total` | `channel`, `priority`, `result`(ok/failed/skipped) | every notify attempt |
| `drophawk_sse_connections` | - | gauge (current count) |
| `drophawk_events_total` | - | gauge (current row count in events) |
 
### J.2 Histograms
| Metric | Labels | When |
|---|---|---|
| `drophawk_source_poll_duration_ms` | `source` | every poll |
| `drophawk_detection_latency_ms` | `type` | drop → notification |
| `drophawk_notify_latency_ms` | `channel` | notify send → ntfy ack |
| `drophawk_http_request_duration_ms` | `method`, `route`, `status` | every HTTP request |
| `drophawk_scraper_round_trip_ms` | `source` | every NATS RPC |
 
### J.3 Gauges
| Metric | Labels | When |
|---|---|---|
| `drophawk_source_up` | `source`, `status`(healthy/degraded/down) | on status change |
| `drophawk_watchlist_rules_active` | - | on rule change |
| `drophawk_db_connections_in_use` | - | every 5s |
| `drophawk_nats_unprocessed_messages` | `stream`, `consumer` | every 5s |
| `drophawk_redis_ops_per_sec` | - | every 5s |
 
### J.4 SLOs
- **Detection latency p99 ≤ 15s** (alert at p99 > 30s for 5m)
- **Source health: ≥ 90% of enabled sources `healthy`** (alert at <75%)
- **Notification success rate ≥ 99.5%** over 1h (alert at <98%)
- **SSE uptime 99.9%** (alert on 0 connected clients for 5m when backend is up)
 
### J.5 Alertmanager rules (`infra/alerts.yml`)
```yaml
groups:
  - name: drophawk
    rules:
      - alert: DropHawkHighDetectionLatency
        expr: histogram_quantile(0.99, sum(rate(drophawk_detection_latency_ms_bucket[5m])) by (le)) > 30000
        for: 5m
        annotations:
          summary: "p99 detection latency > 30s"
 
      - alert: DropHawkSourcesDown
        expr: count(drophawk_source_up{status="down"} == 1) > 0
        for: 10m
        annotations:
          summary: "{{ $value }} source(s) are DOWN"
 
      - alert: DropHawkNotifyFailures
        expr: rate(drophawk_notifications_total{result="failed"}[5m]) / rate(drophawk_notifications_total[5m]) > 0.02
        for: 10m
        annotations:
          summary: "Notification failure rate > 2%"
 
      - alert: DropHawkPostgresDown
        expr: pg_up == 0
        for: 1m
        labels: { severity: critical }
```
 
---
 
## §K. Error Taxonomy (Rust)
 
```rust
use thiserror::Error;
 
#[derive(Debug, Error)]
pub enum AppError {
    #[error("database error: {0}")]
    Db(#[from] sqlx::Error),
 
    #[error("nats publish error: {0}")]
    Bus(#[from] async_nats::PublishError),
 
    #[error("redis error: {0}")]
    Cache(#[from] redis::RedisError),
 
    #[error("http client error: {0}")]
    Http(#[from] reqwest::Error),
 
    #[error("json error: {0}")]
    Json(#[from] serde_json::Error),
 
    #[error("validation failed: {0}")]
    Validation(String),
 
    #[error("not found: {0}")]
    NotFound(String),
 
    #[error("conflict: {0}")]
    Conflict(String),
 
    #[error("rate limited")]
    RateLimited,
 
    #[error("upstream unavailable: {0}")]
    Upstream(String),
 
    #[error("internal error: {0}")]
    Internal(#[from] anyhow::Error),
}
 
impl AppError {
    pub fn status_code(&self) -> u16 {
        use AppError::*;
        match self {
            Validation(_) => 422,
            NotFound(_)   => 404,
            Conflict(_)   => 409,
            RateLimited   => 429,
            Upstream(_)   => 503,
            _             => 500,
        }
    }
    pub fn code(&self) -> &'static str {
        use AppError::*;
        match self {
            Db(_)        => "DB_ERROR",
            Bus(_)       => "BUS_ERROR",
            Cache(_)     => "CACHE_ERROR",
            Http(_)      => "HTTP_ERROR",
            Json(_)      => "JSON_ERROR",
            Validation(_) => "VALIDATION_FAILED",
            NotFound(_)   => "NOT_FOUND",
            Conflict(_)   => "CONFLICT",
            RateLimited   => "RATE_LIMITED",
            Upstream(_)   => "UPSTREAM_UNAVAILABLE",
            Internal(_)   => "INTERNAL",
        }
    }
}
 
// IntoResponse impl for Axum
impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let code = self.code();
        let status = StatusCode::from_u16(self.status_code()).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR);
        let body = Json(json!({ "error": { "code": code, "message": self.to_string() } }));
        (status, body).into_response()
    }
}
 
pub type AppResult<T> = Result<T, AppError>;
```
 
### K.1 Source errors (separate, internal)
```rust
#[derive(Debug, Error)]
pub enum SourceError {
    #[error("network error: {0}")]
    Network(String),
    #[error("parse error: {0}")]
    Parse(String),
    #[error("rate limited; retry after {retry_after:?}")]
    RateLimited { retry_after: Option<Duration> },
    #[error("blocked by source (403/429): {0}")]
    Blocked(String),
    #[error("source returned invalid auth")]
    Auth,
    #[error("upstream error {status}: {body}")]
    Upstream { status: u16, body: String },
}
```
 
---
 
## §L. Backup & Disaster Recovery
 
### L.1 What to back up
- **Postgres** (full dump + WAL archive) - single source of truth.
- **MinIO bucket** (scraped HTML screenshots for debug, can be regenerated).
- **ntfy user.db** (auth tokens - annoying to recreate, do back up).
- **Meilisearch index** - can be rebuilt from Postgres; skip from backups.
- **Configs**: `.env`, `infra/Caddyfile`, `infra/ntfy.server.yml`, dashboards.
 
### L.2 Schedule
- **Postgres nightly** `pg_dump` at 03:00 homelab TZ → `/backups/postgres/drophawk-YYYYMMDD.sql.gz`.
- **WAL archiving** via `pgBackRest` or `wal-g` continuous to MinIO bucket `pg-wal`.
- **MinIO lifecycle**: nightly dumps retained 30 days, weekly dumps 90 days, monthly 1 year.
- **Config bundle**: every git push triggers GitHub Action that tarballs `infra/` and `.env.example` to MinIO.
 
### L.3 Restore runbook
1. `docker compose down`
2. Wipe `pg-data` volume.
3. `docker compose up -d postgres` and wait for healthy.
4. `gunzip -c drophawk-YYYYMMDD.sql.gz | docker compose exec -T postgres psql -U drophawk`
5. Replay WAL since dump (if using continuous archive): `wal-g backup-fetch /var/lib/postgresql/data LATEST && wal-g wal-fetch …`
6. `docker compose up -d` (everything).
7. Verify `/api/ready` returns 200.
8. Verify latest `drops.detected_at` matches expected.
 
**RTO target: 30 minutes. RPO target: 15 minutes** (with WAL archiving) or 24 hours (nightly only).
 
### L.4 Backup verification
- Every Sunday 04:00, restore latest nightly dump into a temporary Postgres container, run smoke queries, alert if any fail. Cron job in `scripts/verify-backup.sh`.
 
---
 
## §M. Security Model
 
### M.1 Threat surface
- **Internal network only.** No public exposure. Operator accesses via Tailscale or LAN.
- If public exposure is ever needed, **Caddy must enforce basic auth + IP allowlist**. Not in v1 scope.
 
### M.2 Service-to-service auth
- All internal services on `drophawk-net` Docker network. No mTLS in v1 (trusted network).
- Postgres: single user `drophawk` with random password from `.env`. No app-level users.
- Redis: require `REDIS_PASSWORD`. No ACL subusers.
- NATS: require `NATS_USER` + `NATS_PASSWORD`. Enable JetStream.
- Meilisearch: require `MEILI_MASTER_KEY`. Frontend never talks to Meilisearch directly; always via backend.
- ntfy: ACL-protected. Publisher token has write-only on `drophawk-drops`. iOS subscribe uses read-only token.
 
### M.3 API auth (frontend → backend)
- v1: **no auth** (single user, LAN-only). Caddy IP allowlist optional.
- v7: optional bearer token via `DROPHAWK_API_TOKEN`. Frontend sends `Authorization: Bearer`.
 
### M.4 Secret management
- `.env` is the canonical secret store. **Never committed**. Mode 0600.
- `.env.example` documents every key with placeholder values.
- CI step: `gitleaks detect` runs on every PR. Pre-commit hook rejects if `.env` pattern is staged.
- Backups of `.env` stored in MinIO encrypted bucket, accessible only to operator.
 
### M.5 Input validation
- Every POST/PATCH body validated by Zod (frontend) AND `validator` crate (backend). Never trust client.
- Regex patterns in watchlist are compiled server-side; reject if compilation > 1ms (ReDoS guard). Limit pattern length to 256 chars.
- Query params: integers bounded (e.g. `per_page ≤ 100`), timestamps parsed strictly.
- All URLs returned to user are validated to be `https://` (no `javascript:`).
 
### M.6 Audit log
- Every mutation (POST/PATCH/DELETE on watchlist, PATCH on sources) writes to a `mutation_log` table:
```sql
CREATE TABLE mutation_log (
    id BIGSERIAL PRIMARY KEY,
    action TEXT NOT NULL,         -- 'watchlist.create', 'source.toggle', etc.
    target TEXT,
    actor TEXT,                   -- 'operator' (single user) for now
    payload JSONB,
    at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```
 
### M.7 Anti-bot / ethical scraping (reaffirmed)
- Honest UA on API sources: `DropHawk/0.1 (+https://your-homelab/drophawk)`.
- Browser impersonation only on Cloudflare-protected public pages, only for read.
- **Never solve CAPTCHA, never bypass rate limits via IP rotation that targets a specific account, never submit forms on behalf of any user, never store 3rd party credentials.**
 
---
 
## §N. Testing Strategy
 
### N.1 Pyramid
- **Unit (70%)**: pure functions - hash canonicalization, status inference, price-drop classification, regex compilation.
- **Integration (25%)**: DB access (testcontainers-postgres), NATS round-trip, ntfy mock (wiremock).
- **E2E (5%)**: Playwright through the full stack via `docker compose`.
 
### N.2 Coverage gates
- Rust: `cargo tarpaulin` → **≥ 80% line coverage** on `backend/src/{detect,sources,store,notify}`.
- Python: `pytest --cov=scrapers --cov-fail-under=75`.
- TypeScript: Vitest → **≥ 75% line** on `lib/` and `hooks/`.
 
### N.3 Fixtures
- **Golden JSON**: `backend/tests/fixtures/ticketmaster/sample_event.json` (real Ticketmaster response, sanitized). Hash test vectors locked against this.
- **HTTP replay**: `wiremock` for Rust, `vcrpy` for Python. Cassettes checked in under `tests/cassettes/`.
- **DB snapshot**: tiny Postgres dump with seed data, loaded via testcontainers in `conftest.rs`.
- **SSE fixture**: a recorded stream of 50 drop events for frontend testing.
 
### N.4 Test commands (run all before merge)
```bash
make check              # runs all of below
cargo clippy -- -D warnings
cargo fmt --check
cargo test --all
cd scrapers && uv run pytest
cd frontend && pnpm typecheck && pnpm lint && pnpm test
cd frontend && pnpm test:e2e   # only in CI, needs running stack
```
 
### N.5 Property tests (Rust, `proptest`)
- `content_hash` is deterministic: same input → same hash, across runs.
- `content_hash` differs when ANY participating field differs.
- Hash is stable across serializer versions (golden vectors).
 
### N.6 Load test
- `backend/benches/scheduler.rs`: simulate 50 sources × 1s interval × 1k events/poll → must sustain <60% CPU single core.
- `scripts/loadtest.sh`: 100 concurrent SSE clients, 1000 events/s broadcast → no SSE drops.
 
---
 
## §O. Performance Budgets
 
### O.1 Latency budgets
| Path | p50 | p99 |
|---|---|---|
| Poll → drop detected | 500ms | 2s |
| Drop detected → ntfy sent | 200ms | 1s |
| Drop detected → SSE fanout | 50ms | 250ms |
| HTTP API read | 30ms | 200ms |
| HTTP API write | 80ms | 400ms |
| Frontend TTFB (Next.js SSR) | 100ms | 400ms |
| Frontend TTI | 800ms | 2.5s |
| End-to-end (poll start → phone buzz) | 5s | 15s |
 
### O.2 Memory budgets (Docker container ceilings)
| Service | Limit | Notes |
|---|---|---|
| backend | 512MB | |
| scrapers | 1.5GB | Playwright hungry; cap concurrency to 4 tabs/worker |
| frontend (SSR) | 384MB | |
| postgres | 2GB | `shared_buffers=512MB`, `work_mem=16MB` |
| redis | 256MB | `maxmemory=200mb`, allkeys-lru |
| nats | 256MB | JetStream file storage, memory stream disabled |
| meilisearch | 1GB | |
| ntfy | 64MB | |
| minio | 256MB | |
| prometheus | 512MB | retention 30d |
| grafana | 256MB | |
| loki | 512MB | retention 14d |
 
Total ceiling: ~7.6 GB. Operators with 16 GB homelab have ample headroom.
 
### O.3 SLOs (measured by Prometheus)
- **API availability**: 99.9% over 30 days rolling.
- **API p99 latency** ≤ 500ms on hot paths.
- **SSE reconnect rate** ≤ 0.5/min/client (bad if proxies drop constantly).
 
### O.4 Frontend bundle budget
- Initial JS for `/` route: **≤ 250 KB** gzipped.
- Initial CSS: **≤ 60 KB** gzipped.
- No single image > 200 KB without `next/image` optimization.
 
---
 
## §P. Idempotency Rules
 
### P.1 NATS JetStream deduplication
- Every message published by `emit_drop` carries `Nats-Msg-Id: drop-{drop_id}`. JetStream dedupes within the stream's duplicate window (set to **10 minutes**).
- Scraper round-trip messages carry `Nats-Msg-Id: scrape-{source_id}-{epoch_ms_floor_1000}` (1s buckets). Idempotent.
 
### P.2 Notification dedup (Redis)
- Key: `notif:dedupe:{event_id}:{drop_type}` (TTL 600s). SETNX. Skip if exists.
- Cross-type guard: `notif:dedupe:{event_id}:any` with TTL 60s - no more than one push per event per minute even across types.
 
### P.3 Drop dedup (DB)
- `drops` has no unique constraint (same event can legitimately emit two status drops minutes apart if status oscillates).
- But the **detection layer** only emits when `content_hash` actually changes. So oscillation is naturally bounded to source's actual polling cadence.
 
### P.4 Insert race (upsert)
- `events` has `UNIQUE (source_id, source_event_id)`. Use `INSERT … ON CONFLICT (source_id, source_event_id) DO UPDATE SET … WHERE events.content_hash != EXCLUDED.content_hash RETURNING id, content_hash`. This makes ingest atomic and race-safe.
 
---
 
## §Q. Cross-Source Entity Resolution
 
The same physical event (e.g. Taylor Swift Aug 12 Miami) appears on Ticketmaster, SeatGeek, StubHub (resale), Vivid Seats. We want to link these so the UI shows aggregated info.
 
### Q.1 Algorithm (deterministic, runs in `detect::link_event`)
 
For each new/updated `events` row, attempt to link to existing clusters:
 
1. **Exact performer ID match**: if `raw.tm_attraction_ids[]` and `raw.seatgeek_performer_ids[]` intersect (after a normalization map), confidence = 1.0, basis = `performer_id`.
2. **Date + venue match**: `WHERE starts_at BETWEEN new.starts_at - 1h AND new.starts_at + 1h AND venue_name ILIKE new.venue_name AND city = new.city AND country = new.country`. Confidence = 0.85.
3. **Title + date match**: tokenized title similarity (Jaccard ≥ 0.7 on lowercased tokens, ignoring stopwords) + same date ± 1h. Confidence = 0.65.
 
If any match found, **insert into `cross_source_links` with the matched cluster_id** (create new cluster if no existing one). If multiple clusters match, merge them (lowest id wins).
 
### Q.2 When used
- `GET /api/events/:id` returns `cross_source_links[]` so the UI can show "Also on SeatGeek ($X), StubHub ($Y)".
- The buy_url shown in drops is always the canonical source's URL, but the UI surfaces alternatives.
 
### Q.3 Implementation notes
- Run linking **synchronously** during `ingest_candidate` (it's fast - 3 indexed queries).
- Re-run linking when venue names get normalized (write a `venue_normalization` table mapping messy names to canonical - populated manually over time).
 
---
 
## §R. Buy URL Canonicalization
 
### R.1 Rules
- Always `https://`.
- Strip tracking params added by our scrapers (`?utm_*`, `?ref=*`, `?clickId=*`, `?_branch_match_id=*`).
- Preserve source-required params (e.g. Ticketmaster's `event/id` path segment is essential).
- **Add** DropHawk's own ref param if affiliate program is set: `?drophawk=1`. (No affiliate abuse; honest disclosure in UA.)
- Sort query params alphabetically. (Stable URLs.)
- If URL has fragment, preserve.
 
### R.2 Reference implementation
```rust
pub fn canonicalize_buy_url(raw: &str) -> Result<String, AppError> {
    let mut url = url::Url::parse(raw).map_err(|e| AppError::Validation(e.to_string()))?;
    if url.scheme() != "https" {
        return Err(AppError::Validation("buy_url must be https".into()));
    }
    let drop_keys = ["utm_source","utm_medium","utm_campaign","utm_term","utm_content","ref","clickId","_branch_match_id"];
    let keys_to_remove: Vec<String> = url.query_pairs()
        .filter(|(k, _)| drop_keys.contains(&k.as_ref()))
        .map(|(k,_)| k.into_owned())
        .collect();
    for k in keys_to_remove {
        url.query_pairs_mut().remove_pair(&k);
    }
    url.query_pairs_mut().append_pair("drophawk", "1");
    url.query_pairs_mut().clear().extend_pairs(
        url.query_pairs().collect::<std::collections::BTreeMap<_,_>>()
    ); // alphabetical
    if url.query().map(|q| q.is_empty()).unwrap_or(true) {
        url.set_query(None);
    }
    Ok(url.to_string())
}
```
 
### R.3 Per-source overrides
- Ticketmaster: respect `event/<id>` URL format. Affiliate param `tm_link` allowed if operator has affiliate ID (env `TICKETMASTER_AFFILIATE_ID`).
- SeatGeek: same, `aid` param if `SEATGEEK_AFFILIATE_ID` set.
 
---
 
## §S. Mobile / PWA Requirements
 
### S.1 Installability
- `frontend/public/manifest.webmanifest` with name, short_name, theme_color (teal), background_color (bg-base), display `standalone`, scope `/`, start_url `/?source=pwa`.
- Icons: 192×192, 512×512, 512×512 maskable, all PNG. Generated from one SVG via `scripts/generate-pwa-icons.sh`.
- Apple touch icon: `apple-touch-icon.png` 180×180.
- `<meta name="apple-mobile-web-app-capable" content="yes">`.
- `<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">`.
 
### S.2 Service worker (`frontend/public/sw.js`)
- Use **Serwist** (modern Workbox alternative, Next 16 compatible).
- Cache strategy:
  - HTML navigations: **NetworkFirst** with 5s timeout, fallback to cached `/`.
  - Static assets (`/_next/static/*`): **CacheFirst** with stale-while-revalidate for fonts.
  - API GETs: **NetworkFirst** (no caching of live data).
  - SSE: bypass SW (browser handles natively).
- Update flow: SW detects new version → shows toast "Update available" → user clicks → SW takes over on next navigation.
 
### S.3 Touch interactions
- All tap targets ≥ 44×44 pt (WCAG 2.5.5).
- Pull-to-refresh on dashboard (use `react-pull-to-refresh` or custom Framer Motion).
- Long-press DropCard → context menu (Pin, Hide, Add to watchlist).
- Swipe-left on DropCard → dismiss.
 
### S.4 Push on PWA
- For v1, push is via **ntfy app** (already in scope). Web Push API integration is Phase 7+.
 
---
 
## §T. Accessibility - WCAG 2.2 AA (binding)
 
### T.1 Perceivable
- Color contrast: text ≥ 4.5:1, large text (≥18pt) ≥ 3:1. Tested against `--color-bg-base` and `--color-bg-elevated`. The OKLCH palette above is pre-verified; do not introduce new colors without re-test.
- Non-text contrast (UI components, borders): ≥ 3:1.
- All form inputs have associated `<label>` (Radix `Label`).
- Images have `alt`; decorative images have `alt=""`.
- Status pills: text label AND color. Never color alone.
 
### T.2 Operable
- Keyboard nav: tab order follows visual order; visible focus ring using `outline: 2px solid var(--color-accent-teal)` with `outline-offset: 2px`. Never `outline: none`.
- Skip-to-main link at top of every page.
- All interactive elements reachable in ≤ 6 tabs from page load.
- Cmd+K command palette has `role="dialog"`, `aria-modal`, focus trap, Escape to close.
- No keyboard trap.
 
### T.3 Understandable
- Form validation errors are announced via `aria-live="polite"`.
- Time formats include timezone suffix (e.g. `7:00 PM ET`).
- Relative time component has `title` with absolute timestamp.
 
### T.4 Robust
- Valid HTML5; tested with `axe-core` in Playwright suite. Zero critical or serious violations.
 
### T.5 Motion
- All animations honor `prefers-reduced-motion: reduce` (see globals.css).
 
### T.6 Audit
- Run `axe-playwright` against every route in e2e. Fail CI on new violations.
 
---
 
## §U. i18n
 
### U.1 v1 scope
- English only, but **structure for i18n from day one**.
- All UI strings via `next-intl` (`frontend/messages/en.json`).
- No hardcoded user-facing strings in components.
 
### U.2 Currency
- Each event carries `currency` (ISO 4217). Display via `Intl.NumberFormat` with user's preferred currency (Settings).
- Default user currency: `USD`. Operator can switch to `EUR`, `GBP`, etc.
- Conversion rates: fetched daily from `open.er-api.com` (free), cached in Redis.
 
### U.3 Dates / times
- All times stored UTC. Display in user's local timezone via `Intl.DateTimeFormat` with `timeZone` from `Intl.DateTimeFormat().resolvedOptions().timeZone`.
- Format pattern: `Aug 12 2026, 7:00 PM ET` (date, time, tz abbreviation).
 
---
 
## §V. Image Pipeline
 
### V.1 Source images
- Ticketmaster/SeatGeek provide `image_url`. Cache via Next.js `next/image` with remote pattern allow-list.
- For sources without images (FIFA), use a generated gradient placeholder keyed off `source_id` (deterministic hue).
 
### V.2 Allowed remote patterns (`next.config.mjs`)
```js
images: {
  remotePatterns: [
    { protocol: "https", hostname: "**.ticketmaster.com" },
    { protocol: "https", hostname: "**.seatgeek.com" },
    { protocol: "https", hostname: "cdn.fifa.com" },
    { protocol: "https", hostname: "**. axs.com" },
  ],
  formats: ["image/avif", "image/webp"],
  minimumCacheTTL: 86400,
}
```
 
### V.3 Generated placeholders
- Function `placeholderFor(seed: string): { from: string, to: string }`.
- Hash `seed` → pick hue from a curated 12-color palette.
- CSS gradient `linear-gradient(135deg, hsl1, hsl2)`.
- Cache the gradient in component state; no network.
 
### V.4 Lazy loading
- All `<Image>` below the fold use `loading="lazy"` (default in Next 16 Image).
- DropCard images are 64×64 (tiny); always load eagerly for top-of-feed.
 
---
 
## §W. Failure Mode Runbooks
 
For each service: what fails, what the system does, what the operator does.
 
### W.1 Postgres down
- **Detection**: `/api/ready` 503; `pg_up == 0` alert.
- **System behavior**: backend stops accepting requests (returns 503). Pollers pause (no DB to write to). NATS messages accumulate in JetStream (24h retention). Scrapers keep working but Rust can't ingest.
- **Operator**: investigate (`docker compose logs postgres`), restore from backup if needed (§L.3), restart. On recovery, JetStream replays unprocessed messages.
 
### W.2 Redis down
- **Detection**: `/api/ready` 503.
- **System behavior**: rate-limit tokens can't be acquired - pollers pause. Notification dedup breaks - temporarily allow duplicate notifications (safer than missing one). Cache misses.
- **Operator**: `docker compose restart redis`. Data is non-critical (cache only).
 
### W.3 NATS down
- **Detection**: backend startup fails `nats.connect`.
- **System behavior**: pollers for scrape-based sources can't RPC → they wait + retry. API-based sources keep working (direct fetch).
- **Operator**: restart NATS. JetStream persists to disk; no data loss.
 
### W.4 Meilisearch down
- **Detection**: `/api/explore` returns 503.
- **System behavior**: search UI disabled; everything else works. Backend falls back to Postgres trigram search (`idx_events_title_trgm`).
- **Operator**: restart. Rebuild index from Postgres via `POST /api/admin/reindex` (Phase 7).
 
### W.5 ntfy down
- **Detection**: `notify::push` returns error; metric counter.
- **System behavior**: notifications fail silently to user. Drops still flow to SSE → UI still works.
- **Operator**: restart ntfy. Missed drops: UI has them; user can scroll back.
 
### W.6 Scraper worker down (Playwright crash)
- **Detection**: source's poll round-trip times out → `SourceError::Network`.
- **System behavior**: 3 timeouts → source `degraded`. 10 → `down` + alert.
- **Operator**: `docker compose restart scrapers`. Source resumes.
 
### W.7 Source blocks us (403/429)
- **Detection**: `SourceError::Blocked`.
- **System behavior**: circuit opens after 3, source → `degraded`. Alert at 10.
- **Operator**: investigate robots.txt change, enable proxy pool (Phase 6), or disable source temporarily.
 
### W.8 Caddy down
- **Detection**: nothing accessible from operator.
- **System behavior**: backend still runs, scrapers still run, but no UI access.
- **Operator**: `docker compose restart caddy`. Caddy auto-HTTPS state in volume.
 
### W.9 Disk full
- **Detection**: Postgres write fails; Loki rejects logs.
- **System behavior**: cascade failure.
- **Operator**: clean old DropHawk data (`SELECT drop_chunks('drops', older_than => '30 days')`), prune Docker images, expand disk.
 
### W.10 Backend OOM
- **Detection**: container restarts; `drophawk_backend_oom_total` metric.
- **System behavior**: brief outage. JetStream replays missed messages on startup.
- **Operator**: investigate memory leak; raise memory limit; file issue.
 
---
 
## §X. CORS Configuration
 
`backend/src/api/mod.rs`:
```rust
let cors = CorsLayer::new()
    .allow_origin(["http://drophawk.lan", "http://localhost:3000"].map(|s| s.parse().unwrap()))
    .allow_methods([Method::GET, Method::POST, Method::PATCH, Method::DELETE, Method::OPTIONS])
    .allow_headers([
        header::AUTHORIZATION,
        header::CONTENT_TYPE,
        header::ACCEPT,
    ])
    .allow_credentials(false)
    .max_age(Duration::from_secs(600));
```
SSE handler bypasses CORS layer (handled separately to allow `text/event-stream`).
 
---
 
## §Y. Configuration Surface (env var reference)
 
Complete list. `.env.example` must contain every key below with placeholder values. CI fails if `.env.example` is missing any key.
 
### Y.1 Backend
```
# Required
DATABASE_URL=postgres://drophawk:CHANGE_ME@postgres:5432/drophawk
REDIS_URL=redis://:CHANGE_ME@redis:6379/0
NATS_URL=nats://drophawk:CHANGE_ME@nats:4222
MEILI_URL=http://meilisearch:7700
MEILI_MASTER_KEY=CHANGE_ME
NTFY_BASE_URL=http://ntfy:80
NTFY_TOPIC=drophawk-drops
NTFY_TOKEN=tk_CHANGE_ME
LOG_LEVEL=info                # trace|debug|info|warn|error
OTEL_EXPORTER_OTLP_ENDPOINT=http://loki:4317
PUBLIC_BASE_URL=https://drophawk.lan
 
# Source credentials (optional per source)
TICKETMASTER_API_KEYS=key1,key2,key3
SEATGEEK_CLIENT_ID=
TICKETMASTER_AFFILIATE_ID=
SEATGEEK_AFFILIATE_ID=
 
# Future
PROXY_POOL_URL=
TELEGRAM_BOT_TOKEN=
TWITTER_BEARER_TOKEN=
 
# Operational
API_RATE_LIMIT_PER_MIN=100
SSE_MAX_CLIENTS=200
SCRAPER_RPC_TIMEOUT_S=30
WATCHLIST_MAX_RULES=500
POLL_DEFAULT_INTERVAL_S=300
POLL_TIGHT_INTERVAL_S=10
POLL_TIGHT_WINDOW_S=900
```
 
### Y.2 Frontend (build-time)
```
NEXT_PUBLIC_API_BASE_URL=https://drophawk.lan/api
NEXT_PUBLIC_NTFY_PUBLIC_URL=https://drophawk.lan/ntfy
NEXT_PUBLIC_NTFY_PUBLIC_TOPIC=drophawk-drops
NEXT_PUBLIC_SENTRY_DSN=           # optional
```
 
### Y.3 Python scrapers
```
DATABASE_URL=                    # informational only; not used directly
NATS_URL=nats://drophawk:CHANGE_ME@nats:4222
REDIS_URL=redis://:CHANGE_ME@redis:6379/1
SCRAPER_CONCURRENCY=4
SCRAPER_LOG_LEVEL=INFO
PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
FIFA_BASE_URL=https://tickets.fifa.com
AXS_BASE_URL=https://www.axs.com
STUBHUB_API_KEY=
VIVIDSEATS_PROXY=
TWITTER_ACCOUNTS=               # comma list of @handles to watch
```
 
---
 
## §Z. Final Implementation Directives
 
These are the **non-negotiable directives** for any executing agent reading this contract:
 
1. **Implement Phase 1 first, end-to-end, no detours.** A thin working slice beats a wide unfinished one. The operator is disabled and depends on this working.
2. **Run `make check` before declaring any task done.** Zero warnings, zero errors.
3. **Commit per logical unit**, conventional commits, never amend shared branches.
4. **If this contract is silent on a decision, ask the operator.** Do not improvise on security, data loss, or notification correctness.
5. **Every file in §4 of SPEC.md exists in Phase 1 with a working implementation, not a stub.** Stub = `unimplemented!()` or `TODO` = merge blocked.
6. **Test fixtures are golden**. Hash vectors in §D.4 are regression gates.
7. **The OKLCH palette in §H.1 is the entire color system.** Do not introduce ad-hoc hex codes.
8. **Notification correctness is sacred.** False positives erode trust fastest. The dedupe + filter pipeline (§I.3 + §5.5) must be tested exhaustively.
9. **No third-party dependencies beyond those pinned in §A.** If a new one is truly required, bump the spec, justify, and pin a version.
10. **When in doubt, choose reliability over feature richness.** The dashboard showing 5 working sources is better than 25 half-broken ones.
 
---
 
**End of binding contracts. Return to SPEC.md §14 for the phased roadmap and §17 for per-phase verification.**