# Screenshot Submission → AI Extraction → Leaderboard Pattern

Generic pattern for any event/app where users upload a screenshot of a device readout (Dragy, lap timer, dyno sheet, etc.) and AI extracts structured data.

## Architecture

```
User uploads screenshot
        ↓
Web form (WPForms / custom HTML) → N8N webhook
        ↓
GPT-4o vision reads image → extracts structured data (lap time, 0-60, Gs, etc.)
        ↓
N8N writes to Google Sheet (merged with pre-registration data by email)
        ↓
Leaderboard page or TV display pulls from sheet (auto-refresh)
```

## Key Design Decisions

### Pre-registration + email match

Instead of making users fill in name/car/class on every screenshot upload:
1. **Registration sheet** — one-time form collecting name, email, vehicle, class
2. **Submission form** — email + screenshot ONLY
3. **Merge** — N8N looks up email in registration sheet, appends vehicle info, writes to results sheet

This keeps the upload form dead simple (2 fields) and prevents data entry errors from repeated submissions.

### Why AI vision instead of manual entry

Dragy screenshots have a consistent layout (dark background, big white numbers). GPT-4o can reliably extract:
- Lap time (e.g. 1:32.45)
- 0-60 (e.g. 2.8s)
- 1/4 mile time and trap speed
- 60-0 braking distance
- Lateral G and Peak G

No manual typing, no errors from the submitter.

### TV display

Simplest option: **Google Sheets "Publish to web"** — renders as a clean sortable table, auto-updates, runs on any TV with a browser (Chromecast, Apple TV, Roku). Or build a custom HTML page that pulls from the sheet via JS.

## Screenshot submission → AI extraction → leaderboard cycle

See `templates/apex-track-form-and-leaderboard.html` for the full mockup covering:
- Submit Your Run tab (email + Dragy screenshot upload zone)
- View Leaderboard tab (class-filterable, ranked, with run detail popup)
- Sample data showing parsed Dragy metrics

## Portal Mockup

The multi-role RBAC portal mockup (admin vs customer view with server monitoring, DNS, backups, call logs, reports, customer management) lives at `/root/portal-mockup/index.html`. The Apex Dragy form mockup at `/root/portal-mockup/apex.html`. Both served via Tailscale at `/portal`.
