# RivalPerk B2B SaaS — Comprehensive LLM Specification & API Reference

## 1. Architectural Overview
RivalPerk is built using a modern React 19 + TypeScript + Tailwind CSS v4 architecture designed for zero cold-start execution on Cloudflare Pages and Workers.

The application serves four primary personas:
1. **End-Consumer (Mobile Client):** Fast, frictionless 15-second mobile journey. Predicts match scores / podiums, enters WhatsApp number, spins instant win wheel, and receives tamper-proof redeemable voucher.
2. **Venue Operator (TV Mode 16:9):** Fullscreen broadcast dashboard displayed on venue TVs/projectors with real-time leaderboard, live activity ticker, and 5-meter scannable QR code.
3. **Business Administrator (B2B Workbench):** Customizes brand colors, logos, presets, inspects captured leads, redeems vouchers in real-time, and generates personalized Trojan Horse sales links.
4. **Autonomous AI Agents (Headless / Browser Automation):** Interacts via DOM agent actions (`[data-agent-action]`) or programmatic JavaScript bridge (`window.__RIVAL_PERK_AGENT__`).

---

## 2. Programmatic Browser Bridge API (`window.__RIVAL_PERK_AGENT__`)
AI agents executing scripts inside the browser page can directly interact with the runtime state:

```javascript
// Retrieve active match fixture
const fixture = window.__RIVAL_PERK_AGENT__.getFixture();

// Submit a prediction programmatically
window.__RIVAL_PERK_AGENT__.submitPrediction({
  homeScore: 2,
  awayScore: 1,
  bonusAnswer: "Sí, habrá gol rápido",
  userName: "AI Agent Beta",
  userPhone: "654987321",
  userEmail: "agent@rivalperk.com"
});

// Spin the instant win roulette
const wonPrize = await window.__RIVAL_PERK_AGENT__.spinRoulette();

// Retrieve current leads from CRM
const leads = window.__RIVAL_PERK_AGENT__.getLeads();

// Redeem a voucher code at the venue cash register
const result = window.__RIVAL_PERK_AGENT__.redeemVoucher("VIP-7492-NACH01");
```

---

## 3. Data Schemas

### MatchFixture
```typescript
interface MatchFixture {
  id: string;
  sport: 'football' | 'padel' | 'f1' | 'basketball';
  competition: string;
  homeTeam: string;
  awayTeam: string;
  homeLogo: string;
  awayLogo: string;
  homeScore?: number;
  awayScore?: number;
  status: 'upcoming' | 'live' | 'finished';
  matchDate: string;
  venue: string;
  bonusQuestion: string;
  bonusOptions: [string, string];
}
```

### Prize
```typescript
interface Prize {
  id: string;
  title: string;
  description: string;
  probability: number; // 0-100 percentage
  type: 'free_item' | 'discount' | 'experience' | 'mega_prize';
  badge: string;
  color: string;
}
```

### Lead
```typescript
interface Lead {
  id: string;
  name: string;
  phone: string;
  email?: string;
  matchId: string;
  predictedHome: number;
  predictedAway: number;
  bonusAnswer: string;
  wonPrize: Prize;
  voucherCode: string;
  redeemed: boolean;
  redeemedAt?: string;
  createdAt: string;
}
```

---

## 4. Scoring Algorithm & Rules
- **Exact Score Match / Podium Match:** +3 Points awarded.
- **Match Winner Sign / Leader Sign:** +1 Point awarded.
- **Bonus Question Answer:** +2 Points awarded.
- **Google Maps Review Verification:** +3 Bonus points awarded to leaderboard standing.
- **Voucher Validity:** 48 hours to 7 calendar days depending on venue preset.