# Eyetrosoft Signage + Campaign Carousel System — PRD (MVP → v1)

## 1. Objective
Build a two-part system:
1) **Player (Front-End)** running on tablets/PCs that plays a main **video/image** in the **top half** of the screen and shows a clickable **bottom carousel** of curved “support cards” tied to the playing campaign.
2) **Admin Dashboard (Back Office)** to manage users, devices, campaigns, creatives, carousel cards, forms/competitions, schedules (Gantt), and reporting (proof-of-play + submissions).

The Player must support **offline-first** playback: scheduled campaigns are downloaded to the device ahead of time and play seamlessly. While playing, the Player must record **geo-tagged proof-of-play** (where it played and for how long) for reporting.

## 2. Personas & Roles
- **Super Admin**: full access; manages users, devices, global settings.
- **Campaign Admin**: creates campaigns, schedules flights, uploads creatives, configures carousel cards/forms.
- **Analyst/Viewer**: read-only reports.
- **Player Device/User**: logs into the Player to receive schedules and play campaigns.

## 3. Definitions
- **Creative**: a video or image asset.
- **Campaign**: a grouping of creatives + carousel cards + form configuration + reporting metadata.
- **Carousel Card**: an image tile with curved borders shown in the bottom carousel; clicking it opens a form or CTA.
- **Schedule/Flight**: a time window when a campaign must play on a device (or device group).
- **Manifest**: what the device should download (assets, hashes, schedule window, playback rules).
- **Proof-of-Play**: play start/end + heartbeats, duration, device, and geo coordinates.

## 4. Functional Requirements

### 4.1 Player (Front-End)
**UI/UX**
- Runs full screen in-browser (“kiosk-like”).
- Layout:
  - Top 50%: main media player (video or image).
  - Bottom 50%: horizontal carousel of “support cards” with rounded corners.
- Carousel:
  - Swipe/touch/scroll.
  - Click on a card opens an overlay form (e.g., Win a competition / enter details).
  - Form supports required fields & validation.

**Playback**
- Can play a campaign playlist (single or multiple creatives).
- Seamless looping within scheduled flight.
- If offline, continue playback from local cache.

**Offline-first download**
- Player requests a **manifest** for its schedule window (e.g., next 24–72 hours).
- Downloads assets not already cached (by checksum).
- Stores campaign metadata and cached assets locally (Cache Storage/IndexedDB).

**Reporting**
- Logs:
  - play-start (timestamp, campaign, creative, device)
  - heartbeats every N seconds while playing
  - play-end (duration)
  - geo-tag (lat/lon + accuracy) where available
- Stores events locally if offline; syncs when online.

**Controls**
- Receives server-side overrides:
  - pause/stop/resume a campaign immediately
  - update schedules / refresh manifest

### 4.2 Admin Dashboard
**User management**
- Create/edit/disable users.
- Roles: Super Admin, Campaign Admin, Analyst.

**Device management**
- Register device (tablet/PC).
- Assign device to a location/site and optional group.
- View device last-seen and player version.

**Campaign management**
- Create campaigns (name, client, notes).
- Upload/link creatives (video/image).
- Configure carousel cards (image + CTA + linked form).
- Configure form fields for competition/lead capture.

**Scheduling (Flighting)**
- Create schedule entries:
  - device(s) or device group
  - start/end datetime
  - optional dayparting rules (v1)
  - priority (v1)
- Visual schedule in **Gantt chart** with rows per device (or per location).

**Reporting**
- Proof-of-play reports:
  - total seconds played, per device, per campaign, date range
  - map-friendly exports (lat/lon)
- Form submission reports:
  - per campaign, per card, per device, date range
- Export CSV.

## 5. Non-Functional Requirements
- **Reliability**: Player continues playback during network outages.
- **Security**: JWT auth for admins; device tokens for players; signed URLs (v1 optional).
- **Performance**: preload next creative; avoid buffering gaps.
- **Scalability**: designed for many devices and many campaigns.
- **Privacy/POPIA**: forms collect only necessary fields; secure storage; audit and retention policies.

## 6. Acceptance Criteria (MVP)
- Player displays main media top-half and a curved-corner carousel bottom-half.
- Carousel click opens a form and successfully submits to backend (or queues offline and syncs later).
- Admin can create users, campaigns, carousel cards, schedules.
- Admin can see schedules on a Gantt timeline.
- Player downloads assets and plays from cache when offline.
- Player records geo-tagged proof-of-play and Admin can view/export logs.

## 7. Out of Scope (MVP)
- Advanced ad decisioning (real-time auctions).
- Complex conflict resolution with multiple priority layers (basic priority only).
- DRM and strict anti-tamper.
- Audience measurement via sensors.

## 8. Suggested Stack (Prototype)
- Backend: Node.js + Express + SQLite (prototype), Postgres-ready schema included.
- Admin UI: HTML + React (CDN) + Frappe Gantt (CDN).
- Player: HTML + React (CDN) + Cache Storage + geolocation APIs.