Events Guides & Philosophy
Nexgate-Event-mng-Requrements
1. PLATFORM PHILOSOPHY (the 7 unbreakable laws)
One person = One lifelong QR forever (physical / online / hybrid / exclusive)
Host gets paid 48 hours after each session ends – fastest in the industry
Money held in escrow until the session actually happens
100 % offline + cryptographically signed QR tokens – zero fraud possible
Zero queues – unlimited scanners + self-service kiosks
True recurring series that feel exactly like Google Calendar
One toggle controls everything: Public ↔ Private ↔ Application-only
2. ALL EVENT TYPES & COMBINATIONS SUPPORTED
Visibility → Public | Private (link) | Application-only
Location → In-person | Online | Hybrid → every combination allowed
Time → One-off | Multi-day | Recurring | Free → every combination allowed
3. MONEY & PAYOUT RULES (applies to EVERYTHING above)
Situation
Attendee pays
Host receives money (bank)
Public / Private
Instantly
48 h after session ends
Application-only
Only after host approves
48 h after session ends
Online / Hybrid
Same rules
48 h after scheduled end time
Recurring pay-per-session
Per session
48 h after each class
Monthly unlimited
1st of month
3–5th of next month
Class packs (10-class etc.)
Upfront or per use
Per use (or full after 1st class if trusted host)
4. FULL PROFESSIONAL FORMS – DOTTED LINES (2025 standard)
FORM 1 ─ CREATE NEW EVENT – STEP 1
┌────────────────────────────────────────────────────────────────────┐
│ ← All events New event │
├────────────────────────────────────────────────────────────────────┤
│ Event title │
│ Weekend Yoga & Sound Healing Retreat │ │
│ │
│ Tagline (shown under title) │
│ 2-day oceanfront immersion · March 15–16 │ │
│ │
│ Cover photo │
│ [ Drag & drop or click to upload ] │
│ │
│ Category │
│ Retreat & Wellness ▼ │
│ Tags │
│ #yoga #soundhealing #miami #oceanview #retreat │
│ │
│ Visibility & Access │
│ ○ Public – anyone can find & book │
│ ○ Private – only people with the direct link │
│ ● Application required – you approve every attendee │
│ │
│ Location type │
│ ○ In-person only ○ Online only ● Hybrid (both) │
│ │
│ [Continue →]│
└────────────────────────────────────────────────────────────────────┘
FORM 2 ─ RECURRING SERIES SETUP (the legendary screen)
┌────────────────────────────────────────────────────────────────────┐
│ Event type │
│ ○ One-time event ● Recurring series │
│ │
│ Repeats │
│ ● Every week ○ Every 2 weeks ○ Every month │
│ ○ Custom (advanced) │
│ │
│ Repeats on │
│ [●] Mon [●] Tue [ ] Wed [●] Thu [ ] Fri [ ] Sat [●] Sun │
│ │
│ + Add another class time (different title/time/price) │
│ │
│ Live preview – next 6 weeks │
│ Mon Mar 10 10:00 Gentle Flow $25 │
│ Tue Mar 11 18:30 Vinyasa Power $28 │
│ Thu Mar 13 18:30 Vinyasa Power $28 │
│ Sun Mar 16 17:00 Sunday Restore $25 │
│ … continues forever │
│ │
│ End condition │
│ ● No end date (we show next 18 months automatically) │
│ ○ Ends on ___/___/____ │
│ ○ After ___ occurrences │
│ │
│ [Continue →]│
└────────────────────────────────────────────────────────────────────┘
FORM 3 ─ APPLICATION-ONLY CUSTOM QUESTIONS
┌────────────────────────────────────────────────────────────────────┐
│ Application questions – attendees must answer before payment │
│ │
│ 1. Why do you want to attend this retreat? │
│ Long text – required │
│ │
│ 2. Dietary restrictions or allergies? │
│ Long text – optional │
│ │
│ 3. How experienced are you with yoga? │
│ Beginner / Intermediate / Advanced │
│ │
│ 4. Instagram handle (we love to repost!) │
│ Short text – optional │
│ │
│ 5. Bring a +1 partner? │
│ Yes / No │
│ │
│ + Add another question │
│ [Continue →]│
└────────────────────────────────────────────────────────────────────┘
FORM 4 ─ ATTENDEE APPLYING TO EXCLUSIVE EVENT
┌────────────────────────────────────────────────────────────────────┐
│ Application – Weekend Yoga & Sound Healing Retreat │
│ │
│ Why do you want to attend? │
│ [ I’ve been following Sun Studio for 2 years and this… ] │
│ │
│ Dietary restrictions? │
│ [ Vegan, allergic to nuts ] │
│ Instagram handle │
│ @emmayoga │
│ │
│ You will only be charged if approved │
│ │
│ [Submit Application]│
└────────────────────────────────────────────────────────────────────┘
FORM 5 ─ HOST APPROVAL DASHBOARD
┌────────────────────────────────────────────────────────────────────┐
│ Applications (52 pending · 28 approved · 123 total) │
│ │
│ ○ Emma Wilson @emmayoga Vegan, no nuts [+ Approve] │
│ “Long-time follower, perfect for my birthday” │
│ │
│ ○ Michael & Ana Couple – 10th anniversary [+ Approve ×2] │
│ │
│ ○ John Smith “Will bring camera crew” [− Reject] │
│ │
│ [ ] Select all [Approve selected] [Message selected] │
│ Waitlist: 31 people (auto-approve if spot opens) │
└────────────────────────────────────────────────────────────────────┘
FORM 6 ─ ETERNAL PASS / TICKET (what every attendee has forever)
┌────────────────────────────────────────────────────────────────────┐
│ Emma Wilson – Eternal Pass │
│ Valid forever across all Sun Studio events │
│ │
│ ████████████████████████████████████████████████████████████████ │
│ │
│ Next: Vinyasa Power – Tue Mar 11, 18:30 │
│ Gentle Flow – Mon Mar 17, 10:00 │
│ │
│ ● Hybrid event │
│ [ SCAN AT DOOR ] [ JOIN ZOOM LIVESTREAM ] │
│ │
│ Location revealed 48 h before (approved attendees only) │
│ │
│ + Add to Apple Wallet + Add to Google Wallet │
└────────────────────────────────────────────────────────────────────┘
FORM 7 ─ SELF-SERVICE KIOSK / SCANNER
┌────────────────────────────────────────────────────────────────────┐
│ Welcome to Sun Studio │
│ │
│ Hold your QR code to the camera │
│ │
│ ████████████████████████████ │
│ │
│ → ✓ Emma Wilson – Approved & paid │
│ Welcome back! Enjoy your class │
└────────────────────────────────────────────────────────────────────┘
5. FINAL SUMMARY – You now have everything
Complete philosophy & rules
Every event type & combination
Exact money & payout logic
Every single professional form with dotted lines
Ready to print and give to designers, developers, investors
Nexgate Platform - Check-in System Architecture
Table of Contents
System Overview
Architecture Principles
System Components
Ticket Generation Flow
Scanner Registration Flow
Ticket Validation Flow
Offline Mode Architecture
Security Model
Data Models
API Specifications
Database Schema
Deployment Architecture
System Overview
What is the Check-in System?
The Check-in System is a critical component of the Nexgate platform that handles secure, scalable ticket validation for events. It enables event organizers to verify attendee tickets at entry gates using mobile scanner devices, with the capability to work both online and offline.
Key Features
Cryptographic Security : Uses RSA-signed JWT tokens to prevent ticket forgery
Offline Capability : Scanners can validate tickets without internet connectivity
Multi-Gate Support : Coordinate validation across multiple entry points
Real-time Validation : Immediate duplicate detection when online
Scanner Management : Secure device registration and revocation
Audit Trail : Complete tracking of all scan activities
Inspiration
The system is inspired by electrical meter voucher systems commonly used in Tanzania and other African countries, where vouchers must be validated offline after purchase, with reconciliation happening later when connectivity is restored.
Architecture Principles
1. Security First
All tickets are cryptographically signed
Cannot be forged without the server's private key
Scanner devices only receive public keys for verification
2. Offline-First Design
Scanners must function without network connectivity
Local validation using JWT signature verification
Queue-based synchronization when connectivity returns
3. Zero-Trust Scanner Model
Each scanner is individually registered and can be revoked
Scanners receive time-limited registration tokens
All scanner actions are logged and auditable
4. Scalability
Stateless ticket validation (JWT-based)
No database queries required for offline validation
Server handles only registration and synchronization
System Components
Component Diagram
┌─────────────────────────────────────────────────────────────────────────────┐
│ NEXGATE PLATFORM │
│ │
│ ┌─────────────────┐ ┌──────────────────┐ │
│ │ Admin Dashboard │────────>│ Event Management │ │
│ └────────┬────────┘ └────────┬─────────┘ │
│ │ │ │
│ │ v │
│ │ ┌─────────────────┐ │
│ │ │ Ticketing │ │
│ │ │ Service │ │
│ │ └────────┬────────┘ │
│ │ │ │
│ v v │
│ ┌─────────────────┐ ┌──────────────────┐ │
│ │ Check-in │<────────│ │ │
│ │ Service │ │ │ │
│ │ ⚡ CORE SYSTEM │ │ │ │
│ └────────┬────────┘ │ │ │
│ │ │ │ │
│ v v v │
│ ┌─────────────────────────────────┐ │
│ │ PostgreSQL Database │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
▲ ▲ ▲
│ │ │
│ │ │
┌──────────┴────────┐ ┌──────────┴────────┐ ┌───────┴────────┐
│ Scanner App │ │ Customer App │ │ Email Service │
│ ⚡ MOBILE CLIENT │ │ Mobile/Web │ │ (External) │
└───────────────────┘ └──────────┬────────┘ └────────────────┘
│
v
┌────────────────────┐
│ Payment Gateway │
│ (External) │
└────────────────────┘
Legend:
──────> Data Flow
⚡ Critical Component
Core Components
1. Check-in Service (Spring Boot Backend)
Responsibilities:
Generate and manage scanner registration tokens
Issue scanner credentials
Generate RSA key pairs for ticket signing
Create JWT-based tickets with QR codes
Handle online ticket validation requests
Receive and process scan logs from scanners
Manage scanner settings and configurations
Maintain scan history and analytics
Technology Stack:
Spring Boot 3.x
Spring Security
PostgreSQL
Redis (for caching and rate limiting)
JWT (io.jsonwebtoken library)
ZXing (QR code generation)
2. Scanner Mobile App (Android)
Responsibilities:
Register scanner device using QR code
Store scanner credentials and server public key
Scan ticket QR codes
Validate tickets offline using JWT verification
Validate tickets online when connected
Queue scan logs for synchronization
Sync with server periodically
Display scan history and statistics
Technology Stack:
Android (Kotlin)
Room Database (local storage)
WorkManager (background sync)
ZXing (QR code scanning)
JWT library for validation
Retrofit (API communication)
3. Admin Dashboard (Web)
Responsibilities:
Generate scanner registration QR codes
View and manage registered scanners
Revoke scanner access
Configure scanner settings
View scan analytics and reports
Monitor real-time scanning activity
Export scan data
Technology Stack:
React.js / Vue.js
Chart.js (analytics)
WebSocket (real-time updates)
Ticket Generation Flow
Overview
When a customer purchases a ticket, the system generates a cryptographically signed JWT token that is embedded in a QR code. This QR code serves as the ticket that the customer presents at the event gate.
Detailed Flow
Customer Ticketing Check-in Database Email
│ Service Service │ Service
│ │ │ │ │
│ Purchase │ │ │ │
│ Ticket │ │ │ │
├─────────────────>│ │ │ │
│ │ │ │ │
│ │ Create Booking │ │ │
│ ├────────────────────────────────────>│ │
│ │ │ │ │
│ │ Request Ticket │ │ │
│ │ Generation │ │ │
│ ├────────────────>│ │ │
│ │ │ │ │
│ │ │ Load Private │ │
│ │ │ Key │ │
│ │ │─┐ │ │
│ │ │ │ │ │
│ │ │<┘ │ │
│ │ │ │ │
│ │ │ Create JWT │ │
│ │ │ Payload │ │
│ │ │─┐ │ │
│ │ │ │ │ │
│ │ │<┘ │ │
│ │ │ │ │
│ │ │ Sign JWT with │ │
│ │ │ Private Key │ │
│ │ │─┐ │ │
│ │ │ │ │ │
│ │ │<┘ │ │
│ │ │ │ │
│ │ │ Generate QR │ │
│ │ │ Code │ │
│ │ │─┐ │ │
│ │ │ │ │ │
│ │ │<┘ │ │
│ │ │ │ │
│ │ │ Store Ticket │ │
│ │ ├────────────────>│ │
│ │ │ │ │
│ │ Return JWT + │ │ │
│ │ QR Code │ │ │
│ │<────────────────┤ │ │
│ │ │ │ │
│ │ Send Email │ │ │
│ │ with QR │ │ │
│ ├──────────────────────────────────────────────────>│
│ │ │ │ │
│ │ │ │ Email with │
│<────────────────────────────────────────────────────────── QR Code │
│ │ │ │ │
│ Return Ticket │ │ │ │
│ Details │ │ │ │
│<─────────────────┤ │ │ │
│ │ │ │ │
Legend:
───> Synchronous request
──> Response
─┐ │ Internal processing
Step-by-Step Process
Step 1: Customer Completes Purchase
Customer → Ticketing Service
- Selects event and ticket type
- Completes payment
- Receives booking confirmation
Step 2: Ticketing Service Requests Ticket Generation
Ticketing Service → Check-in Service
POST /api/tickets/generate
{
"bookingId": "booking-uuid",
"eventId": "event-uuid",
"attendeeName": "John Doe",
"attendeeEmail": "john@example.com",
"ticketType": "VIP",
"validFrom": "2025-12-01T18:00:00Z",
"validUntil": "2025-12-01T23:59:59Z"
}
Step 3: Check-in Service Creates JWT
JWT Header:
{
"alg": "RS256",
"typ": "JWT"
}
JWT Payload:
{
"ticketId": "ticket-uuid-123",
"bookingId": "booking-uuid",
"eventId": "event-uuid",
"eventName": "Tech Conference 2025",
"attendeeName": "John Doe",
"attendeeEmail": "john@example.com",
"ticketType": "VIP",
"seatNumber": "A-12",
"iat": 1701234567,
"exp": 1703826567,
"nbf": 1701234567
}
Signing Process:
1. Encode Header as Base64URL
2. Encode Payload as Base64URL
3. Create signature:
SHA256withRSA(base64(header) + "." + base64(payload), PRIVATE_KEY)
4. Final JWT = header.payload.signature
Step 4: Generate QR Code
1. Take complete JWT string
2. Generate QR code image (300x300 pixels)
3. Encode as Base64 string
4. Store in ticket record
Step 5: Store and Distribute
Database Record:
- ticket_id
- booking_id
- event_id
- jwt_token (full JWT string)
- qr_code_base64
- status (ACTIVE, SCANNED, CANCELLED)
- created_at
Distribution:
- Email to customer with QR code image
- Available in mobile app
- Printable PDF option
Ticket JWT Example
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aWNrZXRJZCI6ImFiYy0xMjMiLCJldmVudElkIjoiZXZlbnQtMDAxIiwiYXR0ZW5kZWVOYW1lIjoiSm9obiBEb2UiLCJhdHRlbmRlZUVtYWlsIjoiam9obkBleGFtcGxlLmNvbSIsImlhdCI6MTcwMTIzNDU2NywiZXhwIjoxNzAzODI2NTY3fQ.signature_here
Scanner Registration Flow
Overview
Before a scanner device can validate tickets, it must be registered with the system. This process is similar to WhatsApp's "Link Device" feature, using a time-limited QR code for secure pairing.
Detailed Flow
Admin Dashboard Check-in Database Scanner
Service App
│ │ │ │ │
│ Click │ │ │ │
│ "Add │ │ │ │
│ Scanner" │ │ │ │
├─────────>│ │ │ │
│ │ │ │ │
│ │ Generate │ │ │
│ │ Token │ │ │
│ ├──────────>│ │ │
│ │ │ │ │
│ │ │ Create Token │ │
│ │ │ (UUID) │ │
│ │ │ Set Expiry │ │
│ │ │ (5 min) │ │
│ │ │─┐ │ │
│ │ │ │ │ │
│ │ │<┘ │ │
│ │ │ │ │
│ │ │ Store Token │ │
│ │ ├─────────────>│ │
│ │ │ │ │
│ │ Return │ │ │
│ │ Token │ │ │
│ │<──────────┤ │ │
│ │ │ │ │
│ │ Generate │ │ │
│ │ QR Code │ │ │
│ │─┐ │ │ │
│ │ │ │ │ │
│ │<┘ │ │ │
│ │ │ │ │
│ Display │ │ │ │
│ QR Code │ │ │ │
│<─────────┤ │ │ │
│ │ │ │ │
│ │
│ Scanner scans QR code │
│ │
│ Scan QR │ │ │ │
├──────────────────────────────────────────────────>│
│ │ │ │ │
│ │ │ │ Extract │
│ │ │ │ Token │
│ │ │ │─┐ │
│ │ │ │ │ │
│ │ │ │<┘ │
│ │ │ │ │
│ │ │ Register │ │
│ │ │ Scanner │ │
│ │ │<─────────────┼─────────────┤
│ │ │ {token, │ │
│ │ │ name} │ │
│ │ │ │ │
│ │ │ Validate │ │
│ │ │ Token │ │
│ │ ├─────────────>│ │
│ │ │ │ │
│ │ │ Token Valid? │ │
│ │ │<─────────────┤ │
│ │ │ │ │
│ │ │ Generate │ │
│ │ │ Credentials │ │
│ │ │ (JWT) │ │
│ │ │─┐ │ │
│ │ │ │ │ │
│ │ │<┘ │ │
│ │ │ │ │
│ │ │ Get Public │ │
│ │ │ Key │ │
│ │ │─┐ │ │
│ │ │ │ │ │
│ │ │<┘ │ │
│ │ │ │ │
│ │ │ Create │ │
│ │ │ Scanner │ │
│ │ │ Record │ │
│ │ ├─────────────>│ │
│ │ │ │ │
│ │ │ Mark Token │ │
│ │ │ as Used │ │
│ │ ├─────────────>│ │
│ │ │ │ │
│ │ │ Return │ │
│ │ │ {id, │ │
│ │ │ credentials│ │
│ │ │ publicKey, │ │
│ │ │ settings} │ │
│ │ ├──────────────┼────────────>│
│ │ │ │ │
│ │ │ │ Store │
│ │ │ │ Config │
│ │ │ │─┐ │
│ │ │ │ │ │
│ │ │ │<┘ │
│ │ │ │ │
│ Show │ │ │ Show │
│ Success │ │ │ Success │
│<─────────────────────────────────────────────────┤
│ │ │ │ │
Legend:
───> Request/Response
─┐ │ Internal processing
.... Scanner scans QR
Step-by-Step Process
Step 1: Admin Initiates Registration
Admin Dashboard:
1. Navigate to "Scanners" section
2. Click "Add New Scanner" button
3. Specify scanner details:
- Scanner Name: "Gate A - Main Entrance"
- Validity: 5 minutes (default)
- Notes: Optional description
Step 2: Server Generates Registration Token
POST /api/registration-tokens/generate
Request:
{
"validityMinutes": 5,
"notes": "Gate A scanner for Main Entrance"
}
Server Process:
1. Generate UUID token
2. Calculate expiry time (now + 5 minutes)
3. Store in database:
- token: "abc-123-xyz-789"
- expires_at: "2025-11-29T10:15:00Z"
- used: false
- created_by: "admin@nexgate.com"
Response:
{
"token": "abc-123-xyz-789",
"qrCodeBase64": "data:image/png;base64,iVBORw0KG...",
"expiresAt": "2025-11-29T10:15:00Z",
"validityMinutes": 5
}
Step 3: Display QR Code
Admin Dashboard displays:
- Large QR code containing the token
- Expiry countdown timer
- Token details
- "Waiting for scanner to connect..." message
Step 4: Scanner Scans QR Code
Scanner App:
1. Open camera for QR scanning
2. Scan QR code displayed on admin dashboard
3. Extract token string: "abc-123-xyz-789"
4. Prompt user to confirm device name
Step 5: Scanner Sends Registration Request
POST /api/scanners/register
Request:
{
"token": "abc-123-xyz-789",
"deviceName": "Gate A Scanner",
"deviceInfo": {
"model": "Samsung Galaxy S21",
"osVersion": "Android 14",
"appVersion": "1.0.0"
}
}
Step 6: Server Validates and Issues Credentials
Server Validation:
1. Find token in database
2. Check if token exists
3. Check if token.used == false
4. Check if token.expiresAt > now()
If valid:
1. Generate scanner credentials (JWT):
{
"scannerId": "scanner-uuid",
"scannerName": "Gate A Scanner",
"type": "scanner_credential",
"iat": now,
"exp": now + 1 year
}
2. Sign with server private key
3. Create scanner record in database:
- scanner_id: UUID
- name: "Gate A Scanner"
- credentials: JWT
- status: ACTIVE
- settings: default settings JSON
- created_at: now
4. Mark token as used:
- used: true
- used_at: now
- scanner_name: "Gate A Scanner"
Response:
{
"scannerId": "scanner-uuid",
"credentials": "eyJhbGc...scanner_jwt",
"publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
"settings": {
"offlineModeEnabled": false,
"syncIntervalMinutes": 15,
"maxOfflineHours": 24
}
}
Step 7: Scanner Stores Configuration
Scanner App (Local Storage):
1. Save scanner ID
2. Save credentials JWT
3. Convert publicKey string to PublicKey object
4. Save public key
5. Save settings
6. Mark device as "registered"
Scanner is now ready to validate tickets!
Registration Token Lifecycle
stateDiagram-v2
[*] --> Generated: Admin creates token
Generated --> Active: Token created, timer starts
Active --> Used: Scanner registers successfully
Active --> Expired: Time runs out
Used --> [*]: Token consumed
Expired --> Deleted: Cleanup job runs
Deleted --> [*]
note right of Active
Valid for 5 minutes
Can only be used once
end note
Ticket Validation Flow
Online Mode (Default)
sequenceDiagram
participant Attendee
participant ScannerApp
participant CheckInService
participant Database
participant Cache
Attendee->>ScannerApp: Present QR Code
ScannerApp->>ScannerApp: Scan QR Code
Extract JWT
ScannerApp->>CheckInService: Validate Ticket
POST /api/tickets/validate
{jwt, scannerId}
CheckInService->>CheckInService: Verify JWT Signature
using Public Key
alt Signature Invalid
CheckInService-->>ScannerApp: Error: Invalid Ticket (Forged)
ScannerApp-->>Attendee: ❌ ENTRY DENIED
Invalid Ticket
else Signature Valid
CheckInService->>CheckInService: Check JWT Expiration
alt Ticket Expired
CheckInService-->>ScannerApp: Error: Ticket Expired
ScannerApp-->>Attendee: ❌ ENTRY DENIED
Ticket Expired
else Ticket Valid
CheckInService->>Cache: Check if already scanned
(Redis: ticketId)
alt Already Scanned
Cache-->>CheckInService: Ticket found in scanned set
CheckInService-->>ScannerApp: Error: Already Scanned
ScannerApp-->>Attendee: ❌ ENTRY DENIED
Ticket Already Used
else First Scan
CheckInService->>Cache: Add to scanned set
SET scanned:ticketId
CheckInService->>Database: Record Scan
{ticketId, scannerId, timestamp}
CheckInService-->>ScannerApp: Success: Entry Granted
ScannerApp-->>Attendee: ✅ ENTRY GRANTED
Welcome!
end
end
end
Offline Mode (Emergency)
sequenceDiagram
participant Attendee
participant ScannerApp
participant LocalDB
participant PublicKey
Note over ScannerApp: Scanner is OFFLINE
No internet connection
Attendee->>ScannerApp: Present QR Code
ScannerApp->>ScannerApp: Scan QR Code
Extract JWT
ScannerApp->>ScannerApp: Parse JWT
(header.payload.signature)
ScannerApp->>PublicKey: Verify Signature
using stored Public Key
alt Signature Invalid
ScannerApp-->>Attendee: ❌ ENTRY DENIED
Invalid Ticket
else Signature Valid
ScannerApp->>ScannerApp: Check JWT Expiration
(from exp claim)
alt Ticket Expired
ScannerApp-->>Attendee: ❌ ENTRY DENIED
Ticket Expired
else Ticket Valid
ScannerApp->>LocalDB: Check local scanned list
SELECT WHERE ticketId = ?
alt Already Scanned Locally
LocalDB-->>ScannerApp: Ticket found
ScannerApp-->>Attendee: ❌ ENTRY DENIED
Already Scanned (Local)
else First Scan Locally
ScannerApp->>LocalDB: Add to scanned list
INSERT scan record
ScannerApp->>LocalDB: Add to sync queue
{ticketId, timestamp, offline:true}
ScannerApp-->>Attendee: ✅ ENTRY GRANTED
(OFFLINE MODE)
Note over ScannerApp: Scan queued for sync
when connection returns
end
end
end
Validation Details
JWT Signature Verification (Cryptographic Process)
Server Side (Ticket Generation):
1. Create payload: {ticketId, eventId, ...}
2. Sign: SIGNATURE = SHA256withRSA(header.payload, PRIVATE_KEY)
3. Result: JWT = header.payload.signature
Scanner Side (Validation):
1. Split JWT: parts = jwt.split(".")
2. Extract: header = parts[0], payload = parts[1], signature = parts[2]
3. Verify: SHA256withRSA.verify(header.payload, signature, PUBLIC_KEY)
4. If verification succeeds → Ticket is authentic
5. If verification fails → Ticket is forged/tampered
Online Validation Steps
1. Authentication Check
- Verify scanner credentials (JWT)
- Check if scanner is ACTIVE (not revoked)
2. Ticket Signature Verification
- Parse JWT
- Verify RSA signature
- If invalid → REJECT (forged ticket)
3. Expiration Check
- Extract exp claim from JWT
- Compare with current time
- If expired → REJECT
4. Duplicate Check (Redis)
- Key: "scanned:{ticketId}"
- Check if key exists
- If exists → REJECT (already scanned)
- If not exists → SET key with TTL (24 hours)
5. Database Logging
- Insert into ticket_scans table:
{
ticket_id: from JWT,
scanner_id: from request,
scanned_at: current timestamp,
validation_mode: "ONLINE",
scan_result: "SUCCESS"
}
6. Response
- Return success with attendee details
- Scanner displays: "Welcome, {attendee_name}!"
Offline Validation Steps
1. JWT Parsing
- Split JWT into parts
- Decode Base64URL payload
2. Signature Verification (Local)
- Use stored PUBLIC_KEY
- Verify signature cryptographically
- If invalid → REJECT
3. Expiration Check (Local)
- Extract exp from payload
- Compare with device time
- If expired → REJECT
4. Local Duplicate Check
- Query local SQLite:
SELECT * FROM scanned_tickets WHERE ticket_id = ?
- If found → REJECT
- If not found → Continue
5. Local Recording
- INSERT INTO scanned_tickets (ticket_id, scanned_at)
- INSERT INTO sync_queue (ticket_id, scanned_at, synced: false)
6. Response
- Display: "Entry Granted (Offline Mode)"
- Show sync pending indicator
Offline Mode Architecture
Why Offline Mode?
Events often happen in locations with poor or no internet connectivity:
Rural areas
Basements/underground venues
High-attendance events (network congestion)
Outdoor festivals
Emergency situations
The system must continue functioning even without internet.
Offline Capabilities
graph TB
subgraph "Online Operations"
O1[Real-time duplicate detection across all gates]
O2[Immediate sync to central database]
O3[Live analytics dashboard]
O4[Scanner settings updates]
end
subgraph "Offline Operations"
F1[JWT signature verification]
F2[Local duplicate detection at same gate]
F3[Scan logging to local database]
F4[Queue for later sync]
end
subgraph "Limitations in Offline Mode"
L1[Cannot detect duplicates at other gates]
L2[Cannot receive scanner revocations immediately]
L3[Cannot update settings in real-time]
L4[Relies on device clock for expiry check]
end
style F1 fill:#90EE90
style F2 fill:#90EE90
style L1 fill:#FFB6C1
style L2 fill:#FFB6C1
Offline Data Flow
sequenceDiagram
participant Gate1 as Scanner (Gate 1)
participant Gate2 as Scanner (Gate 2)
participant Server as Check-in Service
Note over Gate1,Gate2: Both scanners go OFFLINE
rect rgb(255, 200, 200)
Note over Gate1,Gate2: OFFLINE PERIOD
Gate1->>Gate1: Scan Ticket ABC
✅ Valid (first scan at Gate 1)
Gate2->>Gate2: Scan Ticket ABC
✅ Valid (Gate 2 doesn't know)
Note over Gate1,Gate2: PROBLEM: Same ticket scanned twice!
Offline mode cannot prevent this.
end
Note over Gate1,Gate2: Connection restored
rect rgb(200, 255, 200)
Note over Gate1,Gate2: SYNC PERIOD
Gate1->>Server: Sync scans
[{ticketABC, 10:00am}]
Server->>Server: Record: Gate 1 scanned ABC at 10:00
Gate2->>Server: Sync scans
[{ticketABC, 10:05am}]
Server->>Server: Detect: ABC already scanned!
Flag as duplicate
Server->>Server: Create alert for investigation
end
Sync Strategy
When to Sync
1. Automatic Sync Triggers:
- Every N minutes (configurable, default: 15 minutes)
- When connection restored after being offline
- When scanner app comes to foreground
- Before device goes to sleep
2. Manual Sync:
- Admin can trigger sync from scanner UI
- Force sync button available
3. Smart Sync:
- Only sync if there are pending scans
- Batch multiple scans in single request
- Retry failed syncs with exponential backoff
Sync Process
sequenceDiagram
participant Scanner
participant LocalDB
participant CheckInService
participant Database
Scanner->>LocalDB: Get pending scans
SELECT * FROM sync_queue
WHERE synced = false
LocalDB-->>Scanner: Return scan records
Scanner->>CheckInService: POST /api/scanners/sync
{scannerId, scans: [...]}
CheckInService->>CheckInService: Authenticate Scanner
loop For each scan
CheckInService->>Database: Check if ticket already scanned
alt First scan of this ticket
CheckInService->>Database: Record scan
CheckInService->>CheckInService: Mark as SUCCESS
else Duplicate scan
CheckInService->>Database: Record as DUPLICATE_SCAN
CheckInService->>CheckInService: Mark as DUPLICATE
Create alert
end
end
CheckInService->>CheckInService: Get latest scanner settings
CheckInService-->>Scanner: Return {syncResults, settings}
Scanner->>LocalDB: Update sync_queue
SET synced = true
Scanner->>Scanner: Apply new settings if changed
Sync Payload Example
POST /api/scanners/sync
Request:
{
"scannerId": "scanner-uuid",
"scans": [
{
"ticketId": "ticket-123",
"scannedAt": "2025-11-29T10:05:00Z",
"validationMode": "OFFLINE",
"deviceTime": "2025-11-29T10:05:00Z"
},
{
"ticketId": "ticket-456",
"scannedAt": "2025-11-29T10:10:00Z",
"validationMode": "OFFLINE",
"deviceTime": "2025-11-29T10:10:00Z"
}
],
"lastSyncAt": "2025-11-29T09:00:00Z"
}
Response:
{
"syncResults": [
{
"ticketId": "ticket-123",
"status": "SUCCESS",
"message": "Scan recorded"
},
{
"ticketId": "ticket-456",
"status": "DUPLICATE",
"message": "Ticket already scanned at Gate B",
"originalScanTime": "2025-11-29T10:08:00Z",
"originalScanner": "Gate B Scanner"
}
],
"settings": {
"offlineModeEnabled": true,
"syncIntervalMinutes": 15,
"maxOfflineHours": 24
},
"serverTime": "2025-11-29T10:30:00Z"
}
Conflict Resolution
Scenario: Same ticket scanned at multiple gates while offline
Gate A (10:05am): Scans ticket ABC - Valid ✅
Gate B (10:08am): Scans ticket ABC - Valid ✅ (doesn't know about Gate A)
Both sync at 10:30am:
Server Resolution:
1. Receive scan from Gate A (ABC at 10:05)
- First scan seen by server
- Record as VALID
2. Receive scan from Gate B (ABC at 10:08)
- Server already has ABC scanned at 10:05
- Record as DUPLICATE
- Create alert for investigation
3. Admin Investigation:
- Review: Was this intentional fraud?
- Or: Genuine user scanned at wrong gate first?
- Action: Take appropriate measures
4. Prevention for Future:
- Reduce offline periods
- More frequent syncs
- Better gate coordination
Security Model
Cryptographic Architecture
graph TB
subgraph "Server (Trust Anchor)"
PrivateKey[RSA Private Key
4096-bit
NEVER leaves server]
PublicKey[RSA Public Key
Distributed to scanners]
end
subgraph "Ticket Generation"
Ticket[Ticket Data
JSON Payload]
JWT[Signed JWT Token]
QR[QR Code
Contains JWT]
end
subgraph "Scanner Device"
StoredPubKey[Stored Public Key]
Verification[Signature Verification]
end
PrivateKey -->|Signs| JWT
PublicKey -->|Copied to| StoredPubKey
Ticket -->|Payload| JWT
JWT -->|Encoded in| QR
QR -->|Scanned| Verification
StoredPubKey -->|Verifies| Verification
style PrivateKey fill:#ff6666
style PublicKey fill:#66ff66
style Verification fill:#6666ff
Security Layers
Layer 1: Scanner Authentication
Every scanner request must include:
- Scanner credentials (JWT)
- Signed with server's private key during registration
- Contains: scannerId, scannerName, expiry (1 year)
Server validates:
1. JWT signature is valid
2. JWT not expired
3. Scanner status is ACTIVE (not revoked)
4. Scanner ID exists in database
Layer 2: Ticket Cryptography
Ticket Security Guarantees:
1. Cannot Forge Tickets
- Requires server's private key to sign
- Private key never leaves server
- Scanners only have public key (can verify, not sign)
2. Cannot Tamper with Tickets
- Any modification invalidates signature
- Changing even 1 character breaks verification
- Scanner detects tampering immediately
3. Cannot Reuse Expired Tickets
- Expiry timestamp in JWT payload
- Verified during each scan
- Cannot be modified (signature protection)
4. Cannot Clone Tickets (Online Mode)
- Each ticketId tracked in Redis
- Duplicate detection across all gates
- Scan recorded in database
Layer 3: Network Security
All API Communication:
- HTTPS/TLS 1.3 only
- Certificate pinning in mobile app
- API rate limiting
- Request signing for sensitive operations
Layer 4: Scanner Revocation
Immediate Revocation:
1. Admin marks scanner as REVOKED
2. Scanner added to revocation list (Redis)
3. Next API request from scanner → DENIED
4. Settings push: {status: "REVOKED"}
5. Scanner clears local data
Scanner receives revocation on:
- Next sync attempt
- Real-time push (if WebSocket connected)
- Settings update request
Attack Scenarios and Mitigations
Attack 1: Ticket Forgery
Attack: Attacker creates fake ticket JWT
Mitigation:
- Cannot sign without private key
- Signature verification fails
- Scanner rejects ticket
Result: ❌ Attack prevented
Attack 2: Ticket Cloning
Attack: User shares same ticket QR with friend
Online Mode:
- First scan: ✅ Valid
- Second scan: ❌ Duplicate detected
Result: ✅ Attack prevented
Offline Mode:
- Different gates: Both scans succeed locally
- Server detects on sync
- Alert generated for investigation
Result: ⚠️ Detected post-facto
Attack 3: Scanner Credential Theft
Attack: Attacker steals scanner credentials from device
Mitigation:
1. Admin revokes stolen scanner
2. Scanner credential becomes invalid
3. Server denies all requests
4. New scanner issued with new credentials
Best Practice:
- Secure credential storage (Android Keystore)
- Device encryption
- Remote wipe capability
Result: ✅ Contained quickly
Attack 4: Replay Attack
Attack: Attacker captures network traffic, replays requests
Mitigation:
- HTTPS prevents traffic capture
- Request timestamps checked
- Nonce validation for sensitive operations
- Short-lived sessions
Result: ✅ Attack prevented
Data Models
Database Entities
1. registration_tokens
CREATE TABLE registration_tokens (
id UUID PRIMARY KEY,
token VARCHAR(100) UNIQUE NOT NULL,
expires_at TIMESTAMP NOT NULL,
used BOOLEAN DEFAULT FALSE,
used_at TIMESTAMP,
created_by VARCHAR(100),
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
validity_minutes INTEGER NOT NULL,
scanner_name VARCHAR(200),
notes TEXT
);
-- Indexes
CREATE INDEX idx_token ON registration_tokens(token);
CREATE INDEX idx_valid_tokens ON registration_tokens(used, expires_at)
WHERE used = FALSE;
Purpose: Store time-limited tokens for scanner registration
Lifecycle:
Created when admin generates QR code
Marked as used when scanner registers
Cleaned up after 7 days (scheduled job)
2. scanners
CREATE TABLE scanners (
id UUID PRIMARY KEY,
scanner_id VARCHAR(100) UNIQUE NOT NULL,
name VARCHAR(200) NOT NULL,
credentials TEXT NOT NULL,
status VARCHAR(20) NOT NULL, -- ACTIVE, REVOKED
settings JSONB NOT NULL,
device_info JSONB,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
last_synced_at TIMESTAMP,
created_by VARCHAR(100)
);
-- Indexes
CREATE INDEX idx_scanner_id ON scanners(scanner_id);
CREATE INDEX idx_scanner_status ON scanners(status);
CREATE INDEX idx_last_synced ON scanners(last_synced_at);
Settings JSONB Structure:
{
"offlineModeEnabled": false,
"syncIntervalMinutes": 15,
"offlineDataSource": "AUTO_SYNC",
"maxOfflineHours": 24,
"allowedEventIds": ["event-1", "event-2"]
}
3. tickets
CREATE TABLE tickets (
id UUID PRIMARY KEY,
ticket_id VARCHAR(100) UNIQUE NOT NULL,
booking_id UUID NOT NULL,
event_id UUID NOT NULL,
attendee_name VARCHAR(200) NOT NULL,
attendee_email VARCHAR(200),
ticket_type VARCHAR(50),
jwt_token TEXT NOT NULL,
qr_code_base64 TEXT,
status VARCHAR(20) NOT NULL, -- ACTIVE, SCANNED, CANCELLED
valid_from TIMESTAMP NOT NULL,
valid_until TIMESTAMP NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (booking_id) REFERENCES bookings(id),
FOREIGN KEY (event_id) REFERENCES events(id)
);
-- Indexes
CREATE INDEX idx_ticket_id ON tickets(ticket_id);
CREATE INDEX idx_booking_id ON tickets(booking_id);
CREATE INDEX idx_event_id ON tickets(event_id);
CREATE INDEX idx_ticket_status ON tickets(status);
4. ticket_scans
CREATE TABLE ticket_scans (
id UUID PRIMARY KEY,
ticket_id VARCHAR(100) NOT NULL,
scanner_id UUID NOT NULL,
scanned_at TIMESTAMP NOT NULL,
validation_mode VARCHAR(20) NOT NULL, -- ONLINE, OFFLINE
scan_result VARCHAR(20) NOT NULL, -- SUCCESS, DUPLICATE, EXPIRED, INVALID
device_time TIMESTAMP,
synced_at TIMESTAMP,
metadata JSONB,
FOREIGN KEY (scanner_id) REFERENCES scanners(id)
);
-- Indexes
CREATE INDEX idx_ticket_scans_ticket ON ticket_scans(ticket_id);
CREATE INDEX idx_ticket_scans_scanner ON ticket_scans(scanner_id);
CREATE INDEX idx_ticket_scans_time ON ticket_scans(scanned_at);
CREATE INDEX idx_ticket_scans_result ON ticket_scans(scan_result);
Metadata JSONB Example:
{
"attendeeName": "John Doe",
"eventName": "Tech Conference 2025",
"gateLocation": "Main Entrance",
"duplicateOf": "scan-uuid-123",
"alertGenerated": true
}
5. rsa_keys
CREATE TABLE rsa_keys (
id UUID PRIMARY KEY,
key_version INTEGER UNIQUE NOT NULL,
private_key TEXT NOT NULL, -- Encrypted
public_key TEXT NOT NULL,
algorithm VARCHAR(20) DEFAULT 'RS256',
key_size INTEGER DEFAULT 4096,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
rotated_at TIMESTAMP,
status VARCHAR(20) NOT NULL -- ACTIVE, ROTATED, REVOKED
);
-- Only one active key at a time
CREATE UNIQUE INDEX idx_active_key ON rsa_keys(status)
WHERE status = 'ACTIVE';
Scanner Local Database (SQLite)
-- Scanner credentials and config
CREATE TABLE scanner_config (
key VARCHAR(50) PRIMARY KEY,
value TEXT NOT NULL
);
-- Locally scanned tickets
CREATE TABLE scanned_tickets (
id INTEGER PRIMARY KEY AUTOINCREMENT,
ticket_id VARCHAR(100) UNIQUE NOT NULL,
scanned_at TIMESTAMP NOT NULL,
attendee_name VARCHAR(200),
event_name VARCHAR(200),
validation_result VARCHAR(20) NOT NULL
);
-- Pending sync queue
CREATE TABLE sync_queue (
id INTEGER PRIMARY KEY AUTOINCREMENT,
ticket_id VARCHAR(100) NOT NULL,
scanned_at TIMESTAMP NOT NULL,
device_time TIMESTAMP NOT NULL,
validation_mode VARCHAR(20) NOT NULL,
synced BOOLEAN DEFAULT FALSE,
sync_attempts INTEGER DEFAULT 0,
last_sync_attempt TIMESTAMP,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- Indexes
CREATE INDEX idx_sync_pending ON sync_queue(synced) WHERE synced = FALSE;
CREATE INDEX idx_scanned_ticket_id ON scanned_tickets(ticket_id);
API Specifications
Base URL
Production: https://api.nexgate.com/v1
Staging: https://staging-api.nexgate.com/v1
Authentication
All requests require authentication via JWT in header:
Authorization: Bearer {scanner_credentials_jwt}
API Endpoints
1. Generate Registration Token
POST /api/registration-tokens/generate
Authorization: Bearer {admin_jwt}
Request Body:
{
"validityMinutes": 5,
"notes": "Gate A scanner for Main Entrance"
}
Response: 201 Created
{
"token": "abc-123-xyz-789",
"qrCodeBase64": "data:image/png;base64,iVBORw0KG...",
"expiresAt": "2025-11-29T10:15:00Z",
"validityMinutes": 5
}
Errors:
400 Bad Request - Invalid validity minutes
401 Unauthorized - Invalid admin credentials
2. Register Scanner
POST /api/scanners/register
Request Body:
{
"token": "abc-123-xyz-789",
"deviceName": "Gate A Scanner",
"deviceInfo": {
"model": "Samsung Galaxy S21",
"osVersion": "Android 14",
"appVersion": "1.0.0"
}
}
Response: 201 Created
{
"scannerId": "scanner-uuid",
"credentials": "eyJhbGc...scanner_jwt",
"publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCg...",
"settings": {
"offlineModeEnabled": false,
"syncIntervalMinutes": 15,
"maxOfflineHours": 24
}
}
Errors:
400 Bad Request - Invalid or expired token
409 Conflict - Token already used
3. Validate Ticket (Online)
POST /api/tickets/validate
Authorization: Bearer {scanner_credentials}
Request Body:
{
"jwt": "eyJhbGc...ticket_jwt",
"scannerId": "scanner-uuid",
"deviceTime": "2025-11-29T10:30:00Z"
}
Response: 200 OK
{
"valid": true,
"ticketId": "ticket-123",
"attendeeName": "John Doe",
"eventName": "Tech Conference 2025",
"ticketType": "VIP",
"message": "Entry granted"
}
Response: 400 Bad Request (Duplicate)
{
"valid": false,
"ticketId": "ticket-123",
"reason": "DUPLICATE",
"message": "Ticket already scanned",
"originalScanTime": "2025-11-29T10:25:00Z",
"originalScanner": "Gate B Scanner"
}
Response: 400 Bad Request (Expired)
{
"valid": false,
"ticketId": "ticket-123",
"reason": "EXPIRED",
"message": "Ticket has expired",
"expiredAt": "2025-11-29T10:00:00Z"
}
Response: 400 Bad Request (Invalid)
{
"valid": false,
"reason": "INVALID_SIGNATURE",
"message": "Ticket signature is invalid (possible forgery)"
}
Errors:
401 Unauthorized - Invalid scanner credentials
403 Forbidden - Scanner revoked
4. Sync Scanner
POST /api/scanners/sync
Authorization: Bearer {scanner_credentials}
Request Body:
{
"scannerId": "scanner-uuid",
"scans": [
{
"ticketId": "ticket-123",
"scannedAt": "2025-11-29T10:05:00Z",
"validationMode": "OFFLINE",
"deviceTime": "2025-11-29T10:05:00Z"
}
],
"lastSyncAt": "2025-11-29T09:00:00Z"
}
Response: 200 OK
{
"syncResults": [
{
"ticketId": "ticket-123",
"status": "SUCCESS",
"message": "Scan recorded"
}
],
"settings": {
"offlineModeEnabled": true,
"syncIntervalMinutes": 15
},
"serverTime": "2025-11-29T10:30:00Z",
"pendingUpdates": []
}
Errors:
401 Unauthorized - Invalid scanner credentials
403 Forbidden - Scanner revoked
5. Get Scanner Settings
GET /api/scanners/{scannerId}/settings
Authorization: Bearer {scanner_credentials}
Response: 200 OK
{
"offlineModeEnabled": false,
"syncIntervalMinutes": 15,
"offlineDataSource": "AUTO_SYNC",
"maxOfflineHours": 24,
"allowedEventIds": ["event-1", "event-2"]
}
Errors:
401 Unauthorized - Invalid scanner credentials
404 Not Found - Scanner not found
6. Revoke Scanner
POST /api/scanners/{scannerId}/revoke
Authorization: Bearer {admin_jwt}
Response: 200 OK
{
"scannerId": "scanner-uuid",
"status": "REVOKED",
"revokedAt": "2025-11-29T10:30:00Z"
}
Errors:
401 Unauthorized - Invalid admin credentials
404 Not Found - Scanner not found
Database Schema
Full Schema Diagram
erDiagram
REGISTRATION_TOKENS ||--o| SCANNERS : "used_by"
SCANNERS ||--o{ TICKET_SCANS : "performs"
TICKETS ||--o{ TICKET_SCANS : "scanned"
EVENTS ||--o{ TICKETS : "contains"
BOOKINGS ||--|| TICKETS : "generates"
RSA_KEYS ||--o{ TICKETS : "signs"
REGISTRATION_TOKENS {
uuid id PK
varchar token UK
timestamp expires_at
boolean used
timestamp used_at
varchar created_by
int validity_minutes
varchar scanner_name
}
SCANNERS {
uuid id PK
varchar scanner_id UK
varchar name
text credentials
varchar status
jsonb settings
jsonb device_info
timestamp last_synced_at
}
TICKETS {
uuid id PK
varchar ticket_id UK
uuid booking_id FK
uuid event_id FK
varchar attendee_name
text jwt_token
text qr_code_base64
varchar status
timestamp valid_from
timestamp valid_until
}
TICKET_SCANS {
uuid id PK
varchar ticket_id FK
uuid scanner_id FK
timestamp scanned_at
varchar validation_mode
varchar scan_result
jsonb metadata
}
EVENTS {
uuid id PK
varchar name
timestamp event_date
varchar venue
}
BOOKINGS {
uuid id PK
uuid event_id FK
varchar customer_email
timestamp booking_date
}
RSA_KEYS {
uuid id PK
int key_version UK
text private_key
text public_key
varchar status
}
Key Relationships
1. registration_tokens → scanners
- One token can register one scanner
- Token is marked as used when scanner created
2. scanners → ticket_scans
- One scanner performs many scans
- Track which scanner scanned which ticket
3. tickets → ticket_scans
- One ticket can be scanned multiple times (duplicates logged)
- Each scan recorded separately
4. events → tickets
- One event has many tickets
- Tickets belong to specific event
5. bookings → tickets
- One booking generates one or more tickets
- Ticket inherits customer info from booking
6. rsa_keys → tickets
- Active RSA key used to sign all new tickets
- Key rotation supported for security
Deployment Architecture
Infrastructure Overview
graph TB
subgraph "Client Layer"
ScannerApp[Scanner Android App]
AdminWeb[Admin Web Dashboard]
CustomerApp[Customer Mobile App]
end
subgraph "Load Balancer"
LB[AWS Application Load Balancer]
end
subgraph "Application Layer"
API1[Check-in Service Instance 1]
API2[Check-in Service Instance 2]
API3[Check-in Service Instance 3]
end
subgraph "Cache Layer"
Redis[(Redis Cluster
Scan Deduplication)]
end
subgraph "Database Layer"
PG_Primary[(PostgreSQL Primary)]
PG_Replica[(PostgreSQL Replica)]
end
subgraph "Storage Layer"
S3[S3 Bucket
QR Code Images]
end
subgraph "Monitoring"
CloudWatch[CloudWatch Logs]
Grafana[Grafana Dashboard]
end
ScannerApp --> LB
AdminWeb --> LB
CustomerApp --> LB
LB --> API1
LB --> API2
LB --> API3
API1 --> Redis
API2 --> Redis
API3 --> Redis
API1 --> PG_Primary
API2 --> PG_Primary
API3 --> PG_Primary
PG_Primary --> PG_Replica
API1 --> S3
API2 --> S3
API3 --> S3
API1 --> CloudWatch
API2 --> CloudWatch
API3 --> CloudWatch
CloudWatch --> Grafana
Deployment Configuration
Production Environment
Check-in Service:
Instances: 3 (Auto-scaling: 2-10)
Instance Type: t3.large (2 vCPU, 8 GB RAM)
Deployment: Blue-Green with ECS
Health Check: /api/health every 30s
Database:
Type: Amazon RDS PostgreSQL 15
Instance: db.r6g.xlarge (4 vCPU, 32 GB RAM)
Storage: 500 GB SSD (auto-scaling enabled)
Replication: 1 read replica in different AZ
Backup: Daily automated backups, 30-day retention
Redis:
Type: Amazon ElastiCache
Node Type: cache.r6g.large (2 vCPU, 13 GB RAM)
Cluster: 3 nodes (1 primary, 2 replicas)
Persistence: AOF enabled
Load Balancer:
Type: Application Load Balancer
SSL: AWS Certificate Manager
Zones: Multi-AZ deployment
Monitoring:
CloudWatch: All application and infrastructure metrics
Grafana: Custom dashboards for scan analytics
PagerDuty: Alert escalation
Backups:
Database: Daily automated + on-demand
Redis: Daily snapshots
S3: Versioning enabled
Scaling Strategy
Horizontal Scaling (API Instances):
- Metric: CPU > 70% or Request Count > 1000/min
- Scale up: Add 1 instance
- Scale down: Remove 1 instance if CPU < 30%
- Min instances: 2
- Max instances: 10
Database Scaling:
- Vertical: Upgrade instance type during low-traffic window
- Horizontal: Add read replicas for reporting/analytics
- Connection pooling: HikariCP with max 100 connections
Redis Scaling:
- Vertical: Upgrade node type
- Horizontal: Add replica nodes
- Cluster mode: Enable for > 10M keys
Regional Expansion:
- Deploy Check-in Service in multiple AWS regions
- Use Route 53 for geo-routing
- Replicate database across regions (read replicas)
Disaster Recovery
RTO (Recovery Time Objective): 1 hour
RPO (Recovery Point Objective): 5 minutes
Recovery Procedures:
1. Database Failure:
- Automatic failover to replica (< 2 minutes)
- Promote replica to primary
- Update application config
- Restore read replica from backup
2. API Service Failure:
- Auto Scaling Group spawns new instances
- Load Balancer routes to healthy instances
- Failed instances terminated and replaced
3. Redis Failure:
- Automatic failover to replica
- Application continues with slight latency
- Rebuild cache from database if needed
4. Complete Region Failure:
- Route 53 failover to backup region
- Promote backup region database to primary
- Update scanner apps via backend config
Monitoring and Analytics
Key Metrics
Scanner Metrics:
- Total active scanners
- Scanners online vs offline
- Scan rate per scanner
- Sync frequency and success rate
- Average offline duration
Ticket Metrics:
- Total scans per event
- Valid scans vs duplicates vs invalid
- Scan success rate
- Average scan time (online vs offline)
- Peak scan throughput
Performance Metrics:
- API response time (p50, p95, p99)
- Database query performance
- Redis hit/miss ratio
- Error rate by endpoint
Security Metrics:
- Invalid ticket attempts
- Scanner authentication failures
- Duplicate scan alerts
- Suspicious patterns (multiple duplicates)
Alerting
Critical Alerts (PagerDuty):
- Database connection pool exhausted
- API error rate > 5%
- Redis cluster down
- Duplicate scan rate > 10%
Warning Alerts (Slack):
- Scanner offline > 30 minutes
- Sync failure rate > 20%
- API response time > 2s (p95)
- Database replication lag > 10s
Info Alerts (Email):
- Daily scan summary
- Weekly duplicate report
- Monthly scanner registration report
Appendix
Glossary
RSA (Rivest-Shamir-Adleman) : Asymmetric encryption algorithm used for digital signatures
JWT (JSON Web Token) : Compact, URL-safe means of representing claims between two parties
QR Code : Two-dimensional barcode that can be scanned by cameras
Scanner Registration : Process of linking a scanner device to the system
Offline Mode : Scanner operation without internet connectivity
Duplicate Scan : Attempt to scan the same ticket multiple times
Sync Queue : Local storage of scans waiting to be sent to server
Public Key : Cryptographic key used to verify signatures (safe to distribute)
Private Key : Cryptographic key used to create signatures (must remain secret)
References
JWT RFC: https://datatracker.ietf.org/doc/html/rfc7519
RSA Cryptography: PKCS #1 v2.2
QR Code Standard: ISO/IEC 18004:2015
Android Keystore: https://developer.android.com/training/articles/keystore
Change Log
Version 1.0 (2025-11-29)
Initial architecture document
Complete system design
All core flows documented
Document Maintained By: Nexgate Platform Team
Last Updated: November 29, 2025
Next Review: December 29, 2025
NEXGATE EVENT MANAGEMENT PLATFORM
Version: 3.0
Last Updated: November 2024
Document Owner: Product Team
1. PLATFORM OVERVIEW
What is Nexgate Events?
A social commerce-integrated event management platform where events and products live together in one ecosystem.
The Problem We Solve
For Hosts:
Slow payouts (5-7 days)
High fees (8-15%)
Events disconnected from products
Complex ticket management
Limited check-in devices
For Attendees:
Events discovered through spam
Tickets scattered everywhere
Can't see which friends are going
No product connection
The Nexgate Solution
For Hosts:
✅ 48-hour payout (fastest in industry)
✅ 10% platform fee (transparent)
✅ Link products to events (unlimited)
✅ Simple per-tier pricing
✅ Unlimited scanner devices
✅ Coupon code system
✅ Social feed discovery
For Attendees:
✅ Discover through friends
✅ One QR per ticket
✅ Shop event products
✅ Hybrid options (physical/online)
✅ Mix free & paid tickets
✅ Use coupon codes
2. CORE PHILOSOPHY
The 7 Unbreakable Laws
1. One Ticket = One Unique QR Code
Every ticket has its own cryptographically signed QR code. Prevents fraud, perfect tracking, works offline.
2. 48-Hour Payout Rule
Host receives money 48 hours after event ends. Period.
3. Social Commerce First
Events ARE products. They live in the same feed. Events drive product sales, products drive event attendance.
4. Hybrid Events, Hybrid Pricing
Physical ≠ Online. Different experiences = different prices.
5. Per-Tier Pricing Freedom
Each tier decides: FREE or PAID. No global toggle. Mix freely.
6. Device Linking for Scanners
No accounts needed. Generate link → Scan with any device → Revoke anytime.
7. Gallery is Required
Minimum 3 photos. Events with photos get 3x more bookings.
3. USER ROLES
Host (Event Creator)
What they can do:
Create/edit/delete events
Set ticket pricing & tiers
Link unlimited products
Generate scanner links
Create coupon codes
View analytics
Receive payouts
Respond to reviews
Attendee
What they can do:
Browse/search events
Purchase tickets (with coupons)
Transfer tickets
Check-in with QR
Leave reviews
Shop event products
Share events
Scanner Device (No Account)
What it is:
Any device with scanner link
No Nexgate account needed
What it can do:
Scan QR codes (specific event only)
Show check-in confirmation
Display real-time count
Work offline
4. EVENT TYPES
One-Time Event
Single date, fixed capacity.
Use cases: Product launches, pop-ups, workshops, concerts
Example:
Fashion Launch Party
March 15, 2025, 7:00 PM
Wynwood Gallery, Miami
$25 General, $50 VIP
100 capacity
Recurring Series
Repeats weekly/monthly.
Use cases: Yoga classes, networking meetups, bootcamps
Configuration:
Repeat: Weekly/Bi-weekly/Monthly
Days: Mon, Wed, Fri
End: Never/After X times/End date
Example:
Sunday Morning Yoga
Every Sunday, 8:00 AM
$25 per class
30 capacity per class
How Recurring Payments Work
Pay-Per-Class Model:
Each class is a separate purchase with its own ticket.
USER BUYS TICKETS:
March 16 class → $25 → QR Code #1
March 23 class → $25 → QR Code #2
March 30 class → $25 → QR Code #3
Each ticket = unique QR code
Each purchase = separate transaction
Each class = separate payout 48h after
Why different QR codes?
Clear separation (each class is distinct)
Works offline (no database lookup needed)
Prevents fraud (can't reuse old ticket)
Easy refunds (refund specific class)
Simple transfers (transfer one class)
Better tracking (attendance per class)
User Experience:
Tickets grouped in wallet by series:
┌─────────────────────────────────────┐
│ SUNDAY MORNING YOGA SERIES │
├─────────────────────────────────────┤
│ Upcoming classes you purchased: │
│ │
│ ✓ March 16 · 8:00 AM │
│ [View QR Code] │
│ │
│ ○ March 23 · 8:00 AM │
│ [View QR Code] │
│ │
│ ○ March 30 · 8:00 AM │
│ [View QR Code] │
└─────────────────────────────────────┘
Smart features:
- Grouped by series name
- Highlights today's class
- Reminders show correct QR
- "Class 1 of 3 you purchased"
Host Dashboard:
SUNDAY MORNING YOGA (Recurring)
Next 6 classes:
━━━━━━━━━━━━━━━━━━
March 16 · $25 · 12/30 sold
March 23 · $25 · 18/30 sold
March 30 · $25 · 20/30 sold
April 6 · $25 · 25/30 sold
April 13 · $25 · 30/30 sold
April 20 · $25 · 30/30 sold
Revenue per class
Payout 48h after each class
Future Enhancement (Phase 2):
Class packs: 10-class pack for $200
Monthly unlimited: $99/month subscription
Same QR for packs (use anytime)
Multi-Day Event
Multiple consecutive days, same ticket.
Use cases: Festivals, retreats, conferences
Features:
Same QR works all days
Track attendance per day
Allow re-entry each day
Example:
Wellness Retreat
March 15-17, 2025 (3 days)
Bali Resort
$450 (all 3 days)
50 capacity
Location Types
In-Person Only
Google Maps address (always visible)
Parking info (optional)
Venue capacity
Online Only
Zoom/Google Meet/Custom
Link revealed after purchase
Unlimited or limited capacity
Hybrid (Physical + Online)
Separate pricing for each
Different capacities
Different benefits
Independent tracking
5. TICKET SYSTEM
Per-Tier Pricing (Core Concept)
Each tier independently decides: FREE or PAID
No global toggle. Maximum flexibility.
Creating Ticket Tiers
Every tier has:
Name - "VIP", "General", "Economy"
Pricing - ○ FREE or ○ PAID $[__]
Capacity - How many available
Description - What's included
Example: In-Person Event
HOST CREATES:
TIER 1: Economy
- Pricing: ● FREE
- Capacity: 30
- Description: Standing room, general entry
TIER 2: Regular
- Pricing: ● PAID $35
- Capacity: 20
- Description: Reserved seat, drink, gift bag
TIER 3: VIP
- Pricing: ● PAID $75
- Capacity: 10
- Description: Front row, meet & greet, merch
SYSTEM DISPLAYS:
"FREE & PAID OPTIONS"
"From FREE to $75"
Total: 60 tickets
Example: Hybrid Event
PHYSICAL TICKETS:
TIER 1: Standard In-Person
- ● PAID $40 · 25 capacity
- Entry, seating, refreshments
TIER 2: VIP In-Person
- ● PAID $85 · 10 capacity
- Front row, meet & greet
ONLINE TICKETS:
TIER 1: Basic Virtual
- ● FREE · Unlimited
- Livestream only
TIER 2: Premium Virtual
- ● PAID $20 · 100 capacity
- HD stream, recording, Q&A
Ticket Purchase Flow
Single Tier Purchase
1. Select tier: "VIP ($75)"
2. Quantity: 2
3. Enter names for each
4. Apply coupon (optional)
5. Payment: $150
6. 2 unique QR codes sent
Mixed Tier Purchase
1. Select "Economy (FREE)" × 2
2. Add "VIP ($75)" × 1
3. Enter 3 names
4. Apply coupon: "FRIEND20" (-$15)
5. Payment: $60
6. 3 unique QR codes sent
QR Code Structure
Each QR contains:
Unique ticket ID
Event ID
User ID
Tier ID
Cryptographic signature
Cannot be forged
Works offline
6. HYBRID EVENTS & PRICING
Why Hybrid Matters
Physical ≠ Online = Different pricing
Host Setup
STEP 1: Choose ● Hybrid
STEP 2: Physical Tiers
Economy: FREE, 20 capacity
Premium: $50, 15 capacity
STEP 3: Online Tiers
Basic: FREE, Unlimited
Premium: $20, 50 capacity
Attendee Selection
STEP 1: Choose Type
● In-Person ○ Virtual
STEP 2: Choose Tier
[Based on selection]
Physical:
💚 Economy - FREE
⭐ Premium - $50
Virtual:
💻 Basic - FREE
💻 Premium - $20
7. SCANNER SYSTEM (DEVICE LINKING)
How It Works
Generate link → Open on ANY device → Scan
No app. No account. Any device.
Creating Scanner Links
EVENT DASHBOARD → [+ Add Scanner]
Device name: "Front Desk iPad"
Expires: ● After event ○ Custom
[Generate Link]
→ Link: nexgate.app/scan/abc123xyz
→ QR code to share
→ Valid for this event only
Using Scanner
On ANY device:
Open link in browser
Camera permission
Point at ticket QR
Instant validation
Scanner Interface:
┌─────────────────────┐
│ NEXGATE SCANNER │
│ Beach Yoga - Mar 16 │
├─────────────────────┤
│ [CAMERA VIEW] │
│ Point at QR code │
├─────────────────────┤
│ 28/60 checked in │
└─────────────────────┘
Success:
✓ Emma Wilson
Ticket: #2847
Tier: VIP ($75)
First-time! 🎉
Features
Works Online:
Real-time validation
Live updates
Full details
Works Offline:
Cryptographic validation
Local storage
Syncs when online
Security:
Auto-expires
Revoke anytime
Event-specific
Activity tracking
8. PRODUCT INTEGRATION (SIMPLIFIED)
Link Products to Events
Attach products from your shop or any shop on Nexgate. Unlimited products.
Adding Products
EVENT DASHBOARD → Products Tab
[+ Add Product from My Shop]
[+ Add by Product Link]
OPTION 1: From Your Shop
→ Browse your products
→ Select any/all
→ [Add Selected]
OPTION 2: By Link
→ Paste: nexgate.com/products/yoga-mat
→ System fetches details
→ [Add Product]
Managing Products
ATTACHED PRODUCTS (12):
📸 Yoga Mat - $65
From: @yogagear
[Remove]
📸 Water Bottle - $15
From: Your Shop
[Remove]
[+ Add More Products]
Can add/remove anytime:
✓ Before event
✓ During event
✓ After event
Display to Attendees
On Event Page:
EVENT MARKETPLACE
📸 Yoga Mat - $65
by @yogagear
[View Product]
📸 Water Bottle - $15
by @sunstudio
[View Product]
📸 Workshop Recording - $10
by @sunstudio
[View Product]
+ View All Products (9 more)
[Browse Event Marketplace →]
Shows first 3-5 products, then "View All"
Event Marketplace Page:
Full grid of all attached products (unlimited)
That's It!
Simple rules:
✅ Attach unlimited products
✅ Yours or others' shops
✅ Add/remove anytime
✅ No timing restrictions
✅ Display on event page
✅ Users shop when they want
9. COUPON SYSTEM (NEW!)
Generate Discount Codes
Create coupon codes for ticket discounts.
Creating Coupons
EVENT DASHBOARD → Coupons Tab
[+ Create New Coupon]
┌─────────────────────────────────────┐
│ CREATE COUPON │
├─────────────────────────────────────┤
│ Coupon code: │
│ [EARLYBIRD2025] │
│ │
│ Discount type: │
│ ● Percentage: [20]% │
│ ○ Fixed amount: $[__] │
│ │
│ Applies to: │
│ ☑️ All ticket tiers │
│ ☐ Specific tiers only │
│ │
│ Usage limit: │
│ ● Unlimited uses │
│ ○ Limited: [100] total uses │
│ ○ One use per customer │
│ │
│ Valid period: │
│ Start: [March 1, 2025] │
│ End: [March 10, 2025] │
│ ○ No expiration │
│ │
│ [Create Coupon] │
└─────────────────────────────────────┘
Managing Coupons
ACTIVE COUPONS (3):
┌─────────────────────────────────────┐
│ EARLYBIRD2025 │
│ 20% off all tickets │
│ Used: 23 times │
│ Valid until: Mar 10 │
│ [Copy Code] [Edit] [Disable] │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│ FRIEND50 │
│ $5 off all tickets │
│ Used: 7/50 times │
│ No expiration │
│ [Copy Code] [Edit] [Disable] │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│ VIP100 │
│ $10 off VIP tier only │
│ Used: 2/10 times │
│ Valid until: Mar 15 │
│ [Copy Code] [Edit] [Disable] │
└─────────────────────────────────────┘
Attendee Using Coupon
CHECKOUT
Order Summary:
VIP Ticket × 1 $75.00
Have a coupon code?
[EARLYBIRD2025 ] [Apply]
✓ Coupon applied: EARLYBIRD2025
Discount (20%): -$15.00
────────────────────────────────
Total: $60.00
[Complete Purchase - $60]
Sharing Coupons
EARLYBIRD2025
[Copy Code] → "Copied!"
Share via:
[📧 Email] [📱 SMS] [📋 Copy Link]
Direct link with coupon:
nexgate.com/events/beach-yoga?coupon=EARLYBIRD2025
Coupon Analytics
COUPON PERFORMANCE
EARLYBIRD2025:
- Uses: 23
- Discount given: $345
- Revenue generated: $1,380
- Conversion boost: +15%
Top performers:
1. EARLYBIRD2025 (23 uses)
2. FRIEND50 (7 uses)
3. VIP100 (2 uses)
10. REVIEW SYSTEM
Collection Timeline
2 hours after event:
"Quick rating ⭐" → Tap 5 stars
24 hours later:
Full review request + incentives
1 week later:
Final reminder
Review Form
RATE BEACH YOGA
Overall: ⭐⭐⭐⭐⭐ (required)
Quick ratings (optional):
Venue: ⭐⭐⭐⭐⭐
Instructor: ⭐⭐⭐⭐⭐
Organization: ⭐⭐⭐⭐☆
Tell us more: (optional)
[Amazing sunrise session...]
Add photos: [+] [+] [+]
Privacy:
● Public ○ Anonymous ○ Private
EARN:
✓ 50 points ($5 credit)
✓ 10% off next event
+ Photos: 100 bonus points
[Submit Review]
Display
⭐ 4.8 out of 5 (127 reviews)
BREAKDOWN:
⭐⭐⭐⭐⭐ ████████ 89%
⭐⭐⭐⭐☆ ███ 8%
MOST MENTIONED:
🌅 Great vibes (42)
🧘 Amazing instructor (38)
REVIEWS:
Emma Wilson ⭐⭐⭐⭐⭐
"Magical sunrise session..."
📸📸📸
👍 12 helpful
↳ Host: "Thank you Emma! 🙏"
11. PAYMENT & PAYOUT
When Attendee Buys
1. Select ticket
2. Apply coupon (optional)
3. Enter payment
4. Charge immediately
5. Funds → Escrow
6. Confirmation sent
Escrow System
Purchase → Escrow → Event Completes → Wait 48h → Payout
Timeline:
Mar 1: Ticket bought ($75) → Escrow
Mar 16: Event ends (7pm)
Mar 18: Payout (7pm, 48h later)
The 48-Hour Rule
Event End Time + 48 Hours = Payout
Payout Calculation
SIMPLE:
Gross: $1,000
Platform fee (10%): -$100
Net: $900
MIXED FREE + PAID:
Free: 40 tickets (no revenue)
Paid: 30 × $25 = $750
Fee (on paid only): -$75
Net: $675
WITH COUPONS:
Gross: $1,500
Coupons used: -$200
Platform fee (10% of $1,300): -$130
Net: $1,170
Payout Dashboard
UPCOMING:
Beach Yoga - Mar 16
Payout: Mar 18, 7pm
Amount: $945
Status: ⏰ 32h left
COMPLETED:
Sunset Yoga - Mar 9
Paid: Mar 11, 6:30pm
Amount: $612.50
Status: ✓ Deposited
Refunds
Host-initiated:
Full refund to attendee
Platform fee non-refundable
Host absorbs fee cost
Automatic (event cancelled):
All attendees refunded
Full amount + platform fee
Nexgate absorbs cost
Within 24 hours
12. NOTIFICATION SYSTEM
Philosophy
Simple, smart, not annoying.
Only send notifications that matter. Automatic reminders based on event timing.
Attendance Confirmation (Optional)
Host can enable:
EVENT SETTINGS → Attendee Management
☑️ Request attendance confirmation
Send [3] days before event
Attendees confirm they're coming
Host sees who confirmed vs pending
Attendee receives:
┌─────────────────────────────────────┐
│ CONFIRM YOUR ATTENDANCE │
├─────────────────────────────────────┤
│ Beach Yoga - March 16, 5pm │
│ │
│ Are you still coming? │
│ │
│ [✓ Yes, I'm Coming] │
│ [✗ Can't Make It] │
└─────────────────────────────────────┘
Host Dashboard:
ATTENDANCE TRACKER
Total tickets: 30
✓ Confirmed: 22 people
⏳ Pending: 5 (no response)
✗ Can't attend: 3 people
Expected: ~73% attendance
[Send Reminder to Pending]
Benefits:
Host plans better (food, materials, space)
Reduces no-shows
Professional event management
Reminder Schedule (Automatic)
Smart formula based on event timing:
IF event is 2-7 DAYS AWAY:
→ 1 day before
→ 1 hour before
IF event is 8-30 DAYS AWAY:
→ 1 week before
→ 1 day before
→ 1 hour before
IF event is 30+ DAYS AWAY:
→ 2 weeks before
→ 1 week before
→ 1 day before
→ 1 hour before
IF event is SAME DAY:
→ 1 hour before only
Rules:
Always: 1 hour before (critical)
If time allows: 1 day before
If far out: 1 week before
If very far: 2 weeks before
Maximum: 4 reminders total
Minimum: 1 reminder (1h before)
Adaptive Reminders
System adjusts based on purchase timing:
Event: March 30 (30 days away)
User A buys March 1:
→ 2 weeks, 1 week, 1 day, 1h reminders
User B buys March 28 (2 days before):
→ 1 day, 1h reminders only
User C buys March 30 (same day):
→ 1h reminder only
Each user gets only relevant reminders
Notification Timeline
Before Event:
[X days before] (if host enabled)
"Confirm your attendance"
[Yes, I'm Coming] [Can't Make It]
[Auto-calculated]
"Beach Yoga is next week!"
[1 day before]
🔔 Beach Yoga tomorrow at 5pm!
📍 1234 Ocean Drive, Miami Beach
🚗 Street parking ($2/hr)
[View Ticket] [Get Directions]
[1 hour before]
🔔 Beach Yoga starts in 1 hour!
⏰ 5:00 PM - Don't be late!
[View Your Ticket QR]
After Event:
[2 hours after]
"How was Beach Yoga? ⭐"
Tap to rate: ⭐⭐⭐⭐⭐
Earn 50 points!
[24 hours after]
"Leave a review (earn 50 points)"
[Write Review]
Total Notifications Per Attendee
Minimum (same-day event):
1h before reminder
Rate request (2h after)
Total: 2 notifications
Typical (1-week advance):
1 day before reminder
1h before reminder
Rate request (2h after)
Total: 3 notifications
Maximum (1+ month advance):
Confirmation request (if host enabled)
2 weeks before
1 week before
1 day before
1h before
Rate request (2h after)
Total: 6 notifications
Host Notifications
Sales Activity:
"New ticket sale! 🎉"
Sarah Chen · Premium ($40)
Total: 23/30 tickets
[View Dashboard]
Sold Out:
"Beach Yoga is SOLD OUT! 🔥"
30/30 tickets · $1,200 gross
[View Analytics]
New Review:
"New 5-star review! ⭐"
Emma: "Amazing sunrise session..."
[View Review] [Respond]
Payout Ready:
"💰 Your payout is ready!"
$945 from Beach Yoga
[View Details]
Host Controls
EVENT SETTINGS → Notifications
ATTENDANCE CONFIRMATION:
○ Disabled
● Enabled: Send [3] days before
REMINDER SCHEDULE:
● Automatic (smart formula) ← Default
○ Custom schedule
POST-EVENT:
☑️ Request rating (2h after)
☑️ Request review (24h after)
[Save Settings]
User Notification Settings
NOTIFICATION PREFERENCES
Event Reminders:
☑️ Smart reminders (recommended)
☐ Disable all except 1h before
Review Requests:
☑️ After attending events
☐ Disable review requests
Friend Activity:
☑️ When friends create events
☑️ When friends buy tickets
Cannot disable:
- 1h before event (critical)
[Save Preferences]
Anti-Spam Rules
Frequency Caps:
Max 4 reminders per event
No more than 2 notifications per day
24h+ between marketing notifications
Smart Batching:
If multiple events same day:
"You have 3 events tomorrow 🗓️"
- Beach Yoga · 5pm
- Pottery Class · 7pm
- Food Festival · 8pm
[View All Tickets]
13. USER JOURNEYS
Journey 1: Host Creates Event
1. Emma logs in
2. [Create Event]
3. Upload 3 photos
4. Title: "Beach Yoga"
5. Category: Fitness
6. Location: ● Hybrid
7. Physical: FREE (20) + $40 (15)
8. Online: FREE (∞) + $15 (50)
9. Link products: Yoga mat, recording
10. Create coupon: "EARLY20" (20% off)
11. [Publish]
12. Share on Instagram
Time: 12 minutes
EVENT DAY:
- Generate 2 scanner links
- Send to iPad + volunteer
- 28 physical checked in
- 119 online joined
- Event ends successfully
48 HOURS LATER:
- Payout: $945 deposited
- 24 reviews (4.9 stars)
- 18 product purchases
Journey 2: Attendee Discovers & Attends
Sarah scrolling feed
→ "Beach Yoga - Emma +8 friends going"
→ Taps event
Event page:
→ Beautiful photos
→ 4.9 stars
→ Virtual Premium: $15
Checkout:
→ Apply coupon: "EARLY20"
→ $15 → $12
→ Apple Pay
→ Done!
Event day:
→ Zoom link opens
→ 130 people online
→ 90-min session
→ Downloads recording
2 hours later:
→ "Rate ⭐"
→ 5 stars
→ Earns 150 points
→ Buys recording: $10
14. TECHNICAL REQUIREMENTS
Performance
Event page: < 2s
Search: < 1s
Scanner: < 500ms
Payment: < 3s
Scalability
10k concurrent users
1k simultaneous purchases
500 simultaneous scans
Availability
99.9% uptime
Zero-downtime deploys
< 4h recovery
Security
OAuth login
JWT tokens
AES-256 encryption
TLS 1.3
PCI DSS compliant
GDPR compliant
SHA-256 QR signing
Mobile
Mobile-first design
Works on 3G/4G
Offline scanner
PWA support
iOS 14+, Android 8+
15. BUSINESS RULES
Capacity
Cannot oversell
Atomic transactions
Per-tier tracking
Sold-out states
Ticket Transfers
Allowed:
Before event starts
Unlimited transfers
New QR for recipient
Not allowed:
During/after event
Check-In Rules
Standard: One scan
Multi-day: Same QR all days
Recurring: Track class usage
Coupon Rules
Validation checks:
Code exists
Not expired
Usage limit not reached
Applies to selected tickets
Can be combined? (host setting)
Refund Policies
Host options:
Full refund anytime
Full until X days before
Partial after deadline
No refunds
16. SUCCESS METRICS
Platform Growth (Year 1)
Month 1: 50 events, 500 tickets
Month 6: 500 events, 10k tickets
Month 12: 2k events, 50k tickets
Key Metrics
Engagement:
View → purchase: 15%+
Repeat attendees: 40%+
Review rate: 40%+
Social share: 20%+
Coupon usage: 25%+
Revenue:
GMV growth
Platform revenue (10%)
Avg ticket price
Product revenue: +30%
Quality:
Event rating: 4.5+
Host retention: 60%+
Scanner success: 99%+
Uptime: 99.9%+
17. IMPLEMENTATION ROADMAP
Phase 1: MVP (Months 1-3)
Build:
Event creation (all types)
Hybrid pricing
Per-tier pricing (free+paid)
Multiple ticket purchase
Unique QR per ticket
Gallery (3 photos min)
Device linking scanner
Product attachment (unlimited)
Coupon system
48-hour payout
Basic reviews
Feed integration
Success:
50 events
500 tickets
4.0+ rating
Phase 2: Enhanced (Months 4-6)
Add:
Advanced analytics
Ticket transfer
Review filters
Host responses
Attendee messaging
Advanced coupons (tiered, bundled)
Product marketplace analytics
Success:
200 events/month
30% hybrid adoption
50% review rate
Phase 3: Scale (Months 7-12)
Add:
Class packs
Monthly passes
Multi-language
International currency
API access
White-label
Success:
1,000+ events/month
50,000+ tickets/month
Profitable
CONCLUSION
What Makes Nexgate Different
The Formula:
Social Commerce + Events = Network Effects
The Flywheel:
Host creates event
→ Links products
→ Creates coupons
→ Shares to feed
→ Friends discover
→ Use coupons
→ Buy tickets
→ Shop products
→ Leave reviews
→ More social proof
→ REPEAT
Key Advantages
48-hour payout - Fastest in industry
Unlimited products - Any shop on platform
Coupon system - Built-in marketing tool
Device linking - Unlimited scanners
Per-tier pricing - Mix free + paid freely
Hybrid events - Physical + online pricing
Social discovery - Friends drive attendance
Next Steps
Build MVP (3 months)
Beta with 50 hosts
Iterate & improve
Scale to 1,000+ hosts
Dominate social commerce events
END OF DOCUMENT
Version: 3.0 - Simplified & Focused
Last Updated: November 2024
Event Management System - Requirements & User Flow Documentation
Table of Contents
Overview
Event Types
Core Features
Event Creation Flows
Ticket Management
Registration & Attendance
User Roles & Permissions
Business Rules
Data Relationships
Overview
The Event Management System supports three distinct event lifecycle types with flexible ticketing, multiple location options, and comprehensive access control. The system is designed to handle everything from simple one-time events to complex recurring series with variable pricing.
Key Capabilities
Multiple event types (One-time, Multi-day, Recurring)
Flexible ticket types with varied pricing
Multiple location modes (In-person, Online, Hybrid)
Access control (Public, Private, Unlisted)
Integration with online meeting providers
Comprehensive registration and attendance tracking
Event Types
1. One-Time Event
A single event occurring once at a specific date and time.
Required Information:
Start date & time
End date & time
Location details
Ticket types (optional)
Example:
Event: Tech Conference 2025
Date: March 15, 2025
Time: 9:00 AM - 5:00 PM
Location: Convention Center
2. Multi-Day Event
A single event spanning multiple consecutive or non-consecutive days.
Required Information:
Start date
End date
Schedule per day (can vary)
Location details (can vary per day)
Single ticket for all days
Characteristics:
ONE event, multiple days
ONE ticket purchase covers ALL days
Each day can have different start/end times
Each day can have different locations
User registers once, attends multiple days
Example:
Event: Music Festival 2025
Dates: June 10-12, 2025
Day 1 (June 10): 2:00 PM - 11:00 PM - Main Stage
Day 2 (June 11): 12:00 PM - 11:00 PM - Multiple Stages
Day 3 (June 12): 1:00 PM - 10:00 PM - Main Stage
Ticket: $200 (access all 3 days)
3. Recurring Event
A series of separate events happening on a repeating schedule.
Required Information:
Series name & description
Recurrence pattern:
Frequency: Daily, Weekly, Monthly, Yearly
Interval: Every 1 week, every 2 weeks, etc.
Days of week (for weekly)
Day of month (for monthly)
Date range: Start date → End date OR number of occurrences
Default schedule for sessions
Default ticket types
Characteristics:
MULTIPLE separate events (series)
Each session = independent event
Users buy tickets per session
Must buy at least ONE session to register for series
Can buy multiple sessions at once or separately
Each session can have own ticket types and pricing
Example:
Series: Monday Yoga Classes
Pattern: Every Monday
Time: 9:00 AM - 10:00 AM
Duration: January - March 2025 (12 sessions)
Individual Sessions:
- Session 1: Jan 6, 2025, 9-10 AM
- Session 2: Jan 13, 2025, 9-10 AM
- Session 3: Jan 20, 2025, 9-10 AM
... (12 total)
Each session has tickets: Regular ($15), Student ($10), Member ($8)
Recurrence Patterns Supported:
Daily: Every day, every 2 days, weekdays only, etc.
Weekly: Every Monday, Mon/Wed/Fri, every 2 weeks on Tuesday, etc.
Monthly: First Monday, 15th of each month, last Friday, etc.
Yearly: Same date each year
Core Features
Event Visibility & Access Control
┌──────────────────────────────────────────────────────────────┐
│ VISIBILITY OPTIONS │
├──────────────────────────────────────────────────────────────┤
│ │
│ ○ Public │
│ • Discoverable in search │
│ • Anyone can view and register │
│ • Appears in event listings │
│ │
│ ○ Private │
│ • Not discoverable │
│ • Invitation-only access │
│ • Organizer sends invitations │
│ • Invitees must be explicitly added │
│ │
│ ○ Unlisted │
│ • Not discoverable in search │
│ • Anyone with link can access │
│ • No invitation required │
│ • Link-based sharing │
│ │
└──────────────────────────────────────────────────────────────┘
Public Events
Visible to everyone
Appear in search results and listings
Anyone can register/buy tickets
No access restrictions
Private Events
Not visible in search
Access by invitation only
Organizer manages invitations
Invitation System:
Organizer invites by email or username
Invitations have optional expiration dates
Invitation statuses: Pending, Accepted, Declined, Expired
Invited users get notifications
Can generate shareable invite links with tokens
Invitation Expiration Rules:
Automatically expires when event ends
Optional custom expiration date
Token-based links can be regenerated (invalidates old tokens)
Unlisted Events
Not discoverable in search
Anyone with the link can access
No explicit invitation needed
Access through direct URL only
Access Mechanism:
Simple approach: Direct URL with event ID
Secure approach: URL includes access token
Organizer can regenerate link (invalidates previous link)
No expiration on the link itself (valid until event ends)
Location Types
┌──────────────────────────────────────────────────────────────┐
│ LOCATION TYPE │
├──────────────────────────────────────────────────────────────┤
│ │
│ ○ In-Person Only │
│ Required: Physical address, venue name │
│ Optional: Coordinates (lat/long), directions │
│ │
│ ○ Online Only │
│ Required: Meeting platform, link/credentials │
│ Options: Manual link OR provider integration │
│ │
│ ○ Hybrid (Both) │
│ Required: ALL in-person + online details │
│ Attendees choose: in-person OR online │
│ │
└──────────────────────────────────────────────────────────────┘
In-Person Events
Required Fields:
Venue name
Full address
City, State, Country
Optional Fields:
Latitude/Longitude (for maps)
Venue description
Parking information
Accessibility details
Online Events
Meeting Provider Options:
Option 1: Manual Entry
Organizer provides meeting link directly
Platform-agnostic (Zoom, Google Meet, Teams, Discord, etc.)
Organizer manages meeting creation
Meeting details stored:
Meeting URL
Meeting ID (optional)
Password/Access code (optional)
Security for Manual Links:
Link hidden until 30 minutes before event
User must be logged in
User must have valid ticket
Link visible until 1 hour after event ends
Option 2: Provider Integration (Zoom)
OAuth connection to organizer's account
System creates meeting automatically
Enhanced security features available
Zoom Integration Flow:
┌─────────────────────────────────────────────────────────────┐
│ Event Creation: Online Event → Select "Connect with Zoom" │
└──────────────────┬──────────────────────────────────────────┘
↓
┌─────────────────────┐
│ Has Zoom connected? │
└─────────┬───────────┘
↓
┌───────┴────────┐
│ │
NO YES
│ │
↓ ↓
┌──────────────────┐ ┌──────────────────┐
│ Redirect to Zoom │ │ Create meeting │
│ OAuth page │ │ immediately via │
│ │ │ API │
└────────┬─────────┘ └─────────┬────────┘
│ │
↓ │
┌──────────────────┐ │
│ User authorizes │ │
│ on Zoom │ │
└────────┬─────────┘ │
│ │
↓ │
┌──────────────────┐ │
│ Save tokens to │ │
│ user account │ │
└────────┬─────────┘ │
│ │
↓ │
┌──────────────────┐ │
│ Create meeting │←──────────┘
│ via Zoom API │
└────────┬─────────┘
│
↓
┌──────────────────────────────┐
│ Each paid attendee gets │
│ UNIQUE registration link │
│ (cannot be shared) │
└──────────────────────────────┘
Zoom Integration Benefits:
Each registered attendee gets unique join URL
URLs tied to email (not shareable)
Waiting room can be enabled
Attendance tracking automatic
Registration approval control
Zoom Account Responsibility:
Organizer uses their own Zoom account
Organizer pays for Zoom subscription
Platform creates meetings using organizer's credentials
No cost to platform
Hybrid Events
Requirements:
ALL in-person details (venue, address, etc.)
ALL online details (meeting link/platform)
Attendee Selection:
During registration, attendee chooses: "Attending in-person" OR "Attending online"
Helps organizer plan:
Seating/catering for in-person
Meeting capacity for online
Attendee can change preference before event
Event Creation Flows
Flow 1: One-Time Event Creation
┌──────────────────────────────────────────────────────────────┐
│ CREATE ONE-TIME EVENT │
└──────────────────────┬───────────────────────────────────────┘
↓
┌─────────────────────────────┐
│ Step 1: Basic Information │
│ • Event name │
│ • Description │
│ • Category │
│ • Cover image │
│ • Visibility (Public/Private│
│ /Unlisted) │
└──────────┬──────────────────┘
↓
┌─────────────────────────────┐
│ Step 2: Date & Time │
│ • Start date & time │
│ • End date & time │
│ • Timezone │
└──────────┬──────────────────┘
↓
┌─────────────────────────────┐
│ Step 3: Location Type │
│ Select: │
│ • In-person │
│ • Online │
│ • Hybrid │
└──────────┬──────────────────┘
↓
┌───────────────┴────────────────┐
│ │
↓ ↓
┌────────────────┐ ┌──────────────────────┐
│ If In-Person: │ │ If Online: │
│ • Venue │ │ • Choose provider │
│ • Address │ │ - Manual link │
│ • Coordinates │ │ - Zoom integration │
└───────┬────────┘ │ • Meeting details │
│ └──────────┬───────────┘
│ │
└────────┬─────────────────┘
↓
┌─────────────────────────────┐
│ Step 4: Tickets │
│ [Add Ticket Type] button │
│ │
│ For each ticket type: │
│ • Name │
│ • Price │
│ • Quantity │
│ • Description │
│ • Sales start/end dates │
│ │
│ [Add Another Ticket Type] │
└──────────┬──────────────────┘
↓
┌─────────────────────────────┐
│ Step 5: Review & Publish │
│ • Preview event details │
│ • Save as draft OR │
│ • Publish immediately │
└─────────────────────────────┘
Flow 2: Multi-Day Event Creation
┌──────────────────────────────────────────────────────────────┐
│ CREATE MULTI-DAY EVENT │
└──────────────────────┬───────────────────────────────────────┘
↓
┌─────────────────────────────┐
│ Steps 1-3: Same as one-time │
│ (Basic info, Location type) │
└──────────┬──────────────────┘
↓
┌─────────────────────────────┐
│ Step 4: Multi-Day Schedule │
│ • Overall start date │
│ • Overall end date │
│ │
│ Configure each day: │
│ │
│ Day 1: │
│ • Date: March 10, 2025 │
│ • Start time: 9:00 AM │
│ • End time: 6:00 PM │
│ • Location (can differ) │
│ • Description │
│ │
│ Day 2: │
│ • Date: March 11, 2025 │
│ • Start time: 10:00 AM │
│ • End time: 8:00 PM │
│ • Location (can differ) │
│ • Description │
│ │
│ [Add Another Day] │
└──────────┬──────────────────┘
↓
┌─────────────────────────────┐
│ Step 5: Tickets │
│ │
│ Ticket Type Options: │
│ │
│ 1. Full Event Pass (common) │
│ • Price: $200 │
│ • Access to all days │
│ │
│ 2. Day Passes (optional) │
│ • Day 1 only: $80 │
│ • Day 2 only: $80 │
│ • Day 3 only: $60 │
│ │
│ 3. VIP/Tier options │
└──────────┬──────────────────┘
↓
┌─────────────────────────────┐
│ Step 6: Review & Publish │
└─────────────────────────────┘
Flow 3: Recurring Event Creation
┌──────────────────────────────────────────────────────────────┐
│ CREATE RECURRING EVENT │
└──────────────────────┬───────────────────────────────────────┘
↓
┌─────────────────────────────┐
│ Step 1: Series Information │
│ • Series name │
│ • Description │
│ • Category │
│ • Cover image │
│ • Visibility │
└──────────┬──────────────────┘
↓
┌─────────────────────────────┐
│ Step 2: Recurrence Pattern │
│ │
│ Frequency: │
│ ○ Daily │
│ ○ Weekly │
│ ○ Monthly │
│ ○ Yearly │
│ │
│ Interval: │
│ Every [1] [week(s)] │
│ │
│ If Weekly, select days: │
│ ☐ Monday │
│ ☐ Tuesday │
│ ☐ Wednesday │
│ ☐ Thursday │
│ ☐ Friday │
│ ☐ Saturday │
│ ☐ Sunday │
│ │
│ Session Time: │
│ Start: [9:00 AM] │
│ End: [10:00 AM] │
│ │
│ Duration: │
│ ○ End date: [March 31, 2025]│
│ ○ Number of occurrences: 12 │
│ ○ No end date (ongoing) │
└──────────┬──────────────────┘
↓
┌─────────────────────────────┐
│ Step 3: Location Type │
│ (Same as one-time event) │
└──────────┬──────────────────┘
↓
┌─────────────────────────────┐
│ Step 4: Default Ticket Types│
│ │
│ These will apply to ALL │
│ sessions by default: │
│ │
│ Ticket Type 1: │
│ • Name: Regular │
│ • Price: $15 │
│ • Quantity per session: 15 │
│ • Description │
│ │
│ Ticket Type 2: │
│ • Name: Student │
│ • Price: $10 │
│ • Quantity per session: 3 │
│ • Requires verification │
│ │
│ Ticket Type 3: │
│ • Name: Member │
│ • Price: $8 │
│ • Quantity per session: 2 │
│ │
│ [Add Another Ticket Type] │
└──────────┬──────────────────┘
↓
┌─────────────────────────────┐
│ Step 5: Generate Sessions │
│ │
│ System generates all │
│ sessions based on pattern: │
│ │
│ Preview: │
│ • Session 1: Jan 6, 9-10 AM │
│ • Session 2: Jan 13, 9-10 AM│
│ • Session 3: Jan 20, 9-10 AM│
│ ... (12 total sessions) │
│ │
│ Each session gets: │
│ • Copy of all ticket types │
│ • Default quantities │
│ • Default prices │
│ │
│ [Confirm & Generate] │
└──────────┬──────────────────┘
↓
┌─────────────────────────────┐
│ Step 6: Customize Sessions │
│ (Optional) │
│ │
│ Organizer can edit any │
│ individual session: │
│ │
│ • Change prices │
│ • Add/remove ticket types │
│ • Change quantities │
│ • Modify time/location │
│ • Cancel specific session │
│ │
│ Example: Jan 20 special │
│ guest session │
│ • Increase price to $20 │
│ • Add VIP ticket ($30) │
└──────────┬──────────────────┘
↓
┌─────────────────────────────┐
│ Step 7: Publish Series │
│ • All sessions now active │
│ • Users can start registering│
└─────────────────────────────┘
Ticket Management
Ticket Types Structure
For One-Time & Multi-Day Events:
Event
│
├── Ticket Type 1: Early Bird
│ ├── Name: "Early Bird"
│ ├── Price: $80
│ ├── Quantity Available: 100
│ ├── Quantity Sold: 87
│ ├── Description: "Save $40 with early registration"
│ ├── Sales Start: Dec 1, 2024
│ ├── Sales End: Jan 31, 2025
│ └── Status: Active
│
├── Ticket Type 2: Regular
│ ├── Name: "Regular"
│ ├── Price: $120
│ ├── Quantity Available: 200
│ ├── Quantity Sold: 45
│ ├── Sales Start: Feb 1, 2025
│ ├── Sales End: March 14, 2025
│ └── Status: Active
│
└── Ticket Type 3: VIP
├── Name: "VIP Pass"
├── Price: $250
├── Quantity Available: 50
├── Quantity Sold: 28
├── Benefits: ["VIP lounge access", "Meet speakers", "Premium seating"]
├── Sales Start: Dec 1, 2024
├── Sales End: March 14, 2025
└── Status: Active
For Recurring Events:
Series: "Monday Yoga"
│
├── Default Ticket Templates
│ ├── Template 1: Regular ($15)
│ ├── Template 2: Student ($10)
│ └── Template 3: Member ($8)
│
└── Sessions
│
├── Session 1: Jan 6
│ ├── Ticket Type: Regular - $15 (15 available, 12 sold)
│ ├── Ticket Type: Student - $10 (3 available, 2 sold)
│ └── Ticket Type: Member - $8 (2 available, 1 sold)
│
├── Session 2: Jan 13
│ ├── Ticket Type: Regular - $15 (15 available, 8 sold)
│ ├── Ticket Type: Student - $10 (3 available, 1 sold)
│ └── Ticket Type: Member - $8 (2 available, 0 sold)
│
└── Session 3: Jan 20 (Customized - Special Guest)
├── Ticket Type: Regular - $20 (15 available, 5 sold) ← Price changed
├── Ticket Type: Student - $15 (3 available, 1 sold) ← Price changed
└── Ticket Type: VIP - $30 (5 available, 2 sold) ← New type added
Ticket Type Properties
Required Fields:
Name (e.g., "Early Bird", "VIP", "Student")
Price (can be $0 for free tickets)
Quantity available
Optional Fields:
Description
Benefits list
Sales start date/time
Sales end date/time
Minimum purchase quantity
Maximum purchase quantity per user
Requires verification (e.g., student ID)
Hidden (invite-only tickets)
Ticket Purchase Rules
General Rules:
User must select at least one ticket
Cannot exceed available quantity
Cannot purchase after sales end date
Cannot purchase before sales start date
One ticket per session per user (for recurring events)
For Recurring Events:
First purchase = automatic series registration
Must buy at least one session to join series
Can buy different ticket types for different sessions
Can purchase multiple sessions at once
Can return later to purchase more sessions
Ticket Selection Flow:
┌──────────────────────────────────────────────────────────────┐
│ EVENT: Tech Conference 2025 │
├──────────────────────────────────────────────────────────────┤
│ │
│ Available Tickets: │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ ☐ Early Bird - $80 │ │
│ │ Save $40 with early registration │ │
│ │ [Only 13 left!] Sales end Jan 31 │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ ☐ Regular - $120 │ │
│ │ Standard conference access │ │
│ │ [200 available] │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ ☐ VIP Pass - $250 │ │
│ │ ✓ All conference access │ │
│ │ ✓ VIP lounge access │ │
│ │ ✓ Meet the speakers │ │
│ │ ✓ Premium seating │ │
│ │ [22 available] │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ Quantity: [1] ▼ │
│ │
│ Selected: Regular Ticket × 1 = $120 │
│ │
│ [Proceed to Checkout →] │
└──────────────────────────────────────────────────────────────┘
For Recurring Events:
┌──────────────────────────────────────────────────────────────┐
│ SERIES: Monday Yoga - January 2025 │
├──────────────────────────────────────────────────────────────┤
│ │
│ Select sessions you want to attend: │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Session: Monday, Jan 6, 2025 · 9:00 AM - 10:00 AM │ │
│ │ │ │
│ │ ☐ Regular - $15 [15 available] │ │
│ │ ☐ Student - $10 [3 available] │ │
│ │ ☐ Member - $8 [2 available] │ │
│ │ ☐ First-Timer Free - $0 [5 available] │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Session: Monday, Jan 13, 2025 · 9:00 AM - 10:00 AM │ │
│ │ │ │
│ │ ☐ Regular - $15 [15 available] │ │
│ │ ☐ Student - $10 [3 available] │ │
│ │ ☐ Member - $8 [2 available] │ │
│ │ ☐ First-Timer Free - $0 [5 available] │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Session: Monday, Jan 20, 2025 · 9:00 AM - 10:00 AM │ │
│ │ 🌟 SPECIAL GUEST SESSION │ │
│ │ │ │
│ │ ☐ Regular - $20 [15 available] │ │
│ │ ☐ Student - $15 [3 available] │ │
│ │ ☐ VIP - $30 [5 available] Meet the guest! │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ Selected: │
│ • Jan 6 - Student ticket: $10 │
│ • Jan 13 - Student ticket: $10 │
│ • Jan 20 - Regular ticket: $20 │
│ │
│ Total: $40 for 3 sessions │
│ │
│ [Proceed to Checkout →] │
└──────────────────────────────────────────────────────────────┘
Registration & Attendance
Registration Flow
For One-Time & Multi-Day Events:
User selects ticket
↓
Proceeds to checkout
↓
Payment processed
↓
Registration created
↓
Ticket issued
↓
Confirmation email sent
↓
User can view ticket in "My Events"
For Recurring Events:
User selects session(s) and ticket type(s)
↓
First purchase?
↓
┌───┴────┐
YES NO
│ │
↓ ↓
Create Already
Series registered
Registration
│ │
└───┬────┘
↓
Payment processed
↓
Session ticket(s) issued
↓
Confirmation email sent
↓
User can:
• View registered series
• See owned session tickets
• Purchase more sessions
Registration Data Tracking
One-Time Event Registration:
User ID
Event ID
Ticket Type ID
Payment status
Registration date/time
Ticket unique code/QR
Attendance status (for check-in)
Multi-Day Event Registration:
User ID
Event ID
Ticket Type ID
Payment status
Registration date/time
Ticket unique code/QR
Attendance per day (optional tracking):
Day 1: Attended/Not attended
Day 2: Attended/Not attended
Day 3: Attended/Not attended
Recurring Event Registration:
Series Level:
User ID
Series ID
Registration date (first purchase date)
Status: Active/Cancelled
Total sessions owned
Session Level:
User ID
Session ID
Ticket Type ID
Payment status
Purchase date/time
Ticket unique code/QR
Attendance status
Attendance Tracking
Check-in Methods:
QR code scan
Manual check-in by organizer
Email verification
Unique ticket code entry
For Recurring Events:
Track attendance per session
User can have tickets for sessions 1, 3, 5 but not 2, 4
Each session = separate check-in
Attendance Reports:
Who registered vs who attended
No-show rate
For recurring: attendance patterns across sessions
User Roles & Permissions
Role Definitions
1. Event Organizer (Creator)
Creates events
Manages event details
Creates/modifies ticket types
Manages invitations (for private events)
Views registrations and attendance
Can edit event before it starts
Can cancel event
Receives payments (event revenue)
2. Attendee (Regular User)
Browses public/unlisted events
Registers for events
Purchases tickets
Receives invitations (for private events)
Views owned tickets
Can cancel registration (based on refund policy)
3. Platform Administrator
Manages all events
Can modify/delete any event
Views all registrations
Manages users
Handles disputes
Platform-level reporting
Organizer Capabilities
Event Management:
Create new events (all types)
Edit unpublished events (full edit)
Edit published events (limited - can't change past dates, can modify future details)
Cancel events (with attendee notifications)
Duplicate events
Ticket Management:
Create ticket types
Modify ticket quantities
Modify ticket prices (before sales start)
Enable/disable ticket types
Set sales periods
Recurring Event Specific:
Customize individual sessions
Cancel specific sessions
Reschedule sessions (with attendee notifications)
Modify session-specific ticket pricing
Registration Management:
View all registrations
Export attendee lists
Send messages to attendees
Manually add attendees (comp tickets)
Issue refunds
Check-in attendees
For Private Events:
Send invitations
Approve/reject registration requests
Regenerate invite links
View invitation status
Attendee Capabilities
Event Discovery:
Browse public events
Search events by category, date, location
Filter by event type
View event details
Registration:
Register for public events
Access unlisted events via link
Accept invitations for private events
Select ticket types
Purchase multiple tickets/sessions
Account Management:
View "My Events" (upcoming, past, cancelled)
View tickets/QR codes
Download tickets
Cancel registration (if allowed)
Rate/review events (after attendance)
For Recurring Events:
View registered series
See which sessions owned
Purchase additional sessions
View attendance history
Business Rules
Event Creation Rules
Required Information:
Event name (3-200 characters)
Start date/time (must be in future)
End date/time (must be after start)
Location details (based on type)
At least one ticket type OR mark as free
Date Validation:
Start date must be in future (at event creation)
End date must be after start date
For multi-day: Each day's dates must be sequential or specified
For recurring: End date must be after start date OR specify number of occurrences
Location Validation:
In-person: Address required
Online: Meeting link OR provider integration required
Hybrid: Both in-person AND online details required
Ticket Validation:
At least one ticket type OR mark event as free
Ticket quantity must be positive integer or unlimited
Price must be >= 0
Sales end date must be before or on event start date
Sales start date must be before sales end date
Registration Rules
Capacity Management:
Cannot register if event/session is at capacity
Cannot register if ticket type is sold out
For recurring: Each session has independent capacity
Time Restrictions:
Cannot register after event starts
Cannot register before ticket sales start
Cannot register after ticket sales end
For recurring: Can register for future sessions even if past sessions occurred
User Restrictions:
One registration per user per event (one-time/multi-day)
One ticket per user per session (recurring)
Cannot purchase same ticket type twice for same session
Can purchase different ticket types across different sessions
Private Event Rules:
Must have valid invitation
Invitation must not be expired
User email must match invitation email (or logged-in account)
Payment Rules:
Payment required before ticket issued (except free tickets)
Payment amount must match ticket price at time of purchase
For recurring: Can pay for multiple sessions in single transaction
Cancellation & Refund Rules
Event Cancellation (by Organizer):
Can cancel event at any time
Must notify all registered attendees
Automatic full refund to all attendees
For recurring: Can cancel entire series OR individual sessions
Registration Cancellation (by Attendee):
Depends on organizer's refund policy
Common policies:
Full refund until X days before event
Partial refund until Y days before event
No refund after Z days before event
For recurring:
Can cancel individual session tickets
If all sessions cancelled, series registration remains (can buy more sessions later)
Automated Actions:
Send cancellation notifications
Process refunds
Update capacities
Mark tickets as cancelled
Recurring Event Specific Rules
Session Generation:
Sessions auto-generated based on recurrence pattern
Each session gets copy of default ticket types
Sessions created in "scheduled" status
Session Customization:
Organizer can modify any session independently
Changes to one session don't affect others
Can cancel individual sessions
Registration Requirements:
Must purchase at least one session to register for series
First purchase = automatic series registration
Can purchase more sessions anytime before session starts
Session Attendance:
Each session = separate attendance record
User can own tickets for non-consecutive sessions
Missing a session doesn't affect future session tickets
Series Management:
Cannot delete series if any session has registrations
Can cancel future sessions
Past sessions remain in history
Data Relationships
Core Entities
┌─────────────────────────────────────────────────────────────┐
│ User │
├─────────────────────────────────────────────────────────────┤
│ • User ID (PK) │
│ • Name, Email, Phone │
│ • Zoom access token (optional) │
│ • Account created date │
│ • Role (Organizer, Attendee, Admin) │
└──────────────┬──────────────────────────────────────────────┘
│
│ creates
↓
┌─────────────────────────────────────────────────────────────┐
│ Event (One-Time or Multi-Day) │
├─────────────────────────────────────────────────────────────┤
│ • Event ID (PK) │
│ • Organizer ID (FK → User) │
│ • Name, Description, Category │
│ • Event Type (ONE_TIME, MULTI_DAY) │
│ • Visibility (PUBLIC, PRIVATE, UNLISTED) │
│ • Location Type (IN_PERSON, ONLINE, HYBRID) │
│ • Start Date/Time, End Date/Time │
│ • Venue/Address (if in-person) │
│ • Meeting URL/Platform (if online) │
│ • Access Token (if unlisted) │
│ • Status (DRAFT, PUBLISHED, CANCELLED, COMPLETED) │
│ • Created/Updated timestamps │
└──────────────┬──────────────────────────────────────────────┘
│
│ has many
↓
┌─────────────────────────────────────────────────────────────┐
│ Ticket Type │
├─────────────────────────────────────────────────────────────┤
│ • Ticket Type ID (PK) │
│ • Event ID (FK → Event) │
│ • Name (e.g., "Early Bird", "VIP") │
│ • Price │
│ • Quantity Available │
│ • Quantity Sold │
│ • Description, Benefits │
│ • Sales Start Date, Sales End Date │
│ • Status (ACTIVE, SOLD_OUT, EXPIRED) │
└──────────────┬──────────────────────────────────────────────┘
│
│ purchased via
↓
┌─────────────────────────────────────────────────────────────┐
│ Event Registration │
├─────────────────────────────────────────────────────────────┤
│ • Registration ID (PK) │
│ • Event ID (FK → Event) │
│ • User ID (FK → User) │
│ • Ticket Type ID (FK → Ticket Type) │
│ • Unique Ticket Code / QR Code │
│ • Payment Status (PENDING, PAID, REFUNDED) │
│ • Registration Date/Time │
│ • Attendance Status (NOT_ATTENDED, ATTENDED) │
│ • Check-in Time (if attended) │
│ • Attendance Mode (IN_PERSON, ONLINE) - for hybrid events │
└─────────────────────────────────────────────────────────────┘
For Multi-Day Events:
┌─────────────────────────────────────────────────────────────┐
│ Event Day Schedule │
├─────────────────────────────────────────────────────────────┤
│ • Day Schedule ID (PK) │
│ • Event ID (FK → Event) │
│ • Day Number (1, 2, 3...) │
│ • Date │
│ • Start Time, End Time │
│ • Location (if different from main) │
│ • Description │
└─────────────────────────────────────────────────────────────┘
For Private Events:
┌─────────────────────────────────────────────────────────────┐
│ Event Invitation │
├─────────────────────────────────────────────────────────────┤
│ • Invitation ID (PK) │
│ • Event ID (FK → Event) │
│ • Invited User ID (FK → User, nullable) │
│ • Invited Email (if user doesn't exist) │
│ • Invite Token (unique) │
│ • Status (PENDING, ACCEPTED, DECLINED, EXPIRED) │
│ • Sent At, Expires At │
│ • Responded At │
└─────────────────────────────────────────────────────────────┘
Recurring Event Relationships
┌─────────────────────────────────────────────────────────────┐
│ Recurring Event Series │
├─────────────────────────────────────────────────────────────┤
│ • Series ID (PK) │
│ • Organizer ID (FK → User) │
│ • Series Name, Description │
│ • Visibility, Location Type │
│ • Recurrence Pattern (DAILY, WEEKLY, MONTHLY, YEARLY) │
│ • Recurrence Interval (e.g., every 2 weeks) │
│ • Days of Week (if weekly) │
│ • Day of Month (if monthly) │
│ • Series Start Date, Series End Date │
│ • Default Session Duration │
│ • Default Session Time │
│ • Total Sessions Generated │
│ • Status (DRAFT, PUBLISHED, CANCELLED, COMPLETED) │
└──────────────┬──────────────────────────────────────────────┘
│
│ has many
↓
┌─────────────────────────────────────────────────────────────┐
│ Series Session (Individual Occurrence) │
├─────────────────────────────────────────────────────────────┤
│ • Session ID (PK) │
│ • Series ID (FK → Recurring Event Series) │
│ • Session Number (1, 2, 3...) │
│ • Session Date │
│ • Start Time, End Time │
│ • Location (can differ from default) │
│ • Meeting URL (if online) │
│ • Status (SCHEDULED, CANCELLED, COMPLETED) │
│ • Is Customized (boolean - if differs from defaults) │
└──────────────┬──────────────────────────────────────────────┘
│
│ has many
↓
┌─────────────────────────────────────────────────────────────┐
│ Session Ticket Type │
├─────────────────────────────────────────────────────────────┤
│ • Session Ticket Type ID (PK) │
│ • Session ID (FK → Series Session) │
│ • Name (e.g., "Regular", "Student") │
│ • Price (can differ per session) │
│ • Quantity Available │
│ • Quantity Sold │
│ • Description │
│ • Requires Verification (boolean) │
└──────────────┬──────────────────────────────────────────────┘
│
│ purchased via
↓
┌─────────────────────────────────────────────────────────────┐
│ Series Registration (User enrolled in series) │
├─────────────────────────────────────────────────────────────┤
│ • Series Registration ID (PK) │
│ • Series ID (FK → Recurring Event Series) │
│ • User ID (FK → User) │
│ • Registration Date (first purchase date) │
│ • Status (ACTIVE, CANCELLED) │
│ • Total Sessions Owned │
└──────────────┬──────────────────────────────────────────────┘
│
│ owns
↓
┌─────────────────────────────────────────────────────────────┐
│ Session Ticket (User's ticket for specific session) │
├─────────────────────────────────────────────────────────────┤
│ • Session Ticket ID (PK) │
│ • Series Registration ID (FK → Series Registration) │
│ • Session ID (FK → Series Session) │
│ • Session Ticket Type ID (FK → Session Ticket Type) │
│ • User ID (FK → User) │
│ • Unique Ticket Code / QR Code │
│ • Payment Status (PENDING, PAID, REFUNDED) │
│ • Purchase Date/Time │
│ • Attendance Status (NOT_ATTENDED, ATTENDED) │
│ • Check-in Time (if attended) │
└─────────────────────────────────────────────────────────────┘
Relationship Summary
One-to-Many Relationships:
User → Events (user creates many events)
Event → Ticket Types (event has many ticket types)
Event → Registrations (event has many registrations)
User → Registrations (user has many registrations)
Event → Event Invitations (private event has many invitations)
For Recurring Events:
Recurring Series → Sessions (series has many sessions)
Session → Session Ticket Types (each session has many ticket types)
User → Series Registrations (user registered for many series)
Series Registration → Session Tickets (registration owns many session tickets)
For Multi-Day Events:
Event → Day Schedules (event has schedule for each day)
Key Technical Considerations
Performance Optimization
Capacity Checks:
Cache available tickets count
Use optimistic locking for ticket purchases
Handle race conditions (multiple users buying last ticket)
Recurring Event Sessions:
Generate sessions in batches
Index sessions by date for quick lookups
Lazy load past sessions
Search & Discovery:
Index events by: date, category, location, visibility
Full-text search on event name/description
Filter by event type, price range, location type
Security Considerations
Access Control:
Verify user owns event before allowing edits
Validate invitation tokens
Rate limit invitation sends
Sanitize all user inputs
Payment Security:
Never store credit card details
Use payment gateway webhooks for status updates
Verify payment before issuing tickets
Handle failed payments gracefully
Online Meeting Links:
Don't expose links before access time
Validate user has valid ticket before showing link
Log link access for security auditing
Support link regeneration for compromised links
Edge Cases to Handle
Event Modifications:
Event date changed after registrations exist → Notify all attendees
Event cancelled → Auto-refund + notifications
Ticket quantity reduced below sold amount → Prevent or handle gracefully
Event visibility changed from Public to Private → Handle existing registrations
Recurring Events:
Session cancelled → Refund that session only, keep other tickets
Series cancelled → Refund all future sessions
User wants to change ticket type for purchased session → Depends on policy
Session time conflicts with another event user registered for → User's problem to manage
Capacity:
Event at capacity but user in checkout process → Reserve temporarily or first-come-first-served
Refund issued → Increase available capacity
Organizer increases capacity mid-sale → Allow more registrations
Payment:
Payment pending during checkout → Hold temporarily, expire after X minutes
Payment fails → Release reserved ticket, notify user
Refund requested → Verify eligibility, process, update capacity
User Experience Flows
Attendee: Discovering & Registering for One-Time Event
Homepage / Event Listing
↓
Browse or Search Events
↓
Filter by Category/Date/Location
↓
Click on Event
↓
View Event Details Page
• Description, Date, Location
• Available Tickets
• Organizer Info
↓
Select Ticket Type & Quantity
↓
Click "Register" or "Buy Ticket"
↓
Login / Sign Up (if not logged in)
↓
Review Order
• Ticket details
• Price breakdown
• Terms & conditions
↓
Enter Payment Information
↓
Complete Purchase
↓
Receive Confirmation
• Email with ticket
• QR code for check-in
↓
View in "My Events"
• Access ticket anytime
• Add to calendar
• Get event updates
↓
Day of Event
• Show QR code for check-in
• Access online meeting link (if applicable)
Attendee: Registering for Recurring Event
Browse Events
↓
Discover Recurring Series
↓
View Series Details
• Pattern (every Monday)
• Dates covered
• Location & time
↓
View All Sessions
• Upcoming sessions listed
• Each with ticket options
↓
Select Session(s) & Ticket Type(s)
• Can select multiple sessions
• Choose appropriate ticket type per session
↓
Review Selection
• Jan 6 - Student: $10
• Jan 13 - Student: $10
• Jan 20 - Regular: $20
• Total: $40
↓
Checkout & Pay
↓
First Purchase?
↓
YES → Create Series Registration
NO → Add to existing registration
↓
Receive Confirmation
• Email with tickets for purchased sessions
• Series enrollment confirmed
↓
View in "My Events"
• See series enrollment
• View owned session tickets
• See upcoming sessions
↓
Later: Want to Attend More Sessions
↓
Go to Series Page
↓
Select Additional Sessions
↓
Purchase & Receive New Tickets
↓
Day of Session
• Show session-specific QR code
• Check in for that session only
Organizer: Creating One-Time Event
Dashboard
↓
Click "Create New Event"
↓
Select Event Type: One-Time
↓
Step 1: Basic Info
• Name, description, category
• Upload cover image
• Select visibility
↓
Step 2: Date & Time
• Start date/time
• End date/time
• Timezone
↓
Step 3: Location
• Select type (in-person/online/hybrid)
• Enter details based on type
• If online + Zoom: Connect account or manual link
↓
Step 4: Tickets
• Add ticket types
• For each: name, price, quantity, description
• Set sales periods
↓
Step 5: Review
• Preview how event looks
• Check all details
↓
Save as Draft OR Publish
↓
If Published:
• Event goes live
• Appears in listings (if public)
• Tickets available for purchase
↓
Monitor Event
• View registrations
• Track ticket sales
• Send updates to attendees
↓
Day of Event
• Check in attendees
• View attendance list
↓
After Event
• View final attendance
• Download reports
• Close event
Organizer: Creating Recurring Event Series
Dashboard
↓
Click "Create New Event"
↓
Select Event Type: Recurring
↓
Step 1: Series Info
• Series name & description
• Cover image
• Visibility
↓
Step 2: Recurrence Pattern
• Frequency (daily/weekly/monthly/yearly)
• Interval (every X weeks)
• Days of week (if weekly)
• Start & end date OR # of occurrences
↓
Step 3: Session Details
• Default session time
• Default duration
• Location type & details
↓
Step 4: Default Tickets
• Create ticket type templates
• These apply to all sessions by default
• Name, price, quantity per session
↓
Review Pattern & Generate Sessions
• Preview: "This will create 12 sessions"
• Show first few sessions as examples
↓
Confirm Generation
↓
System Creates All Sessions
• Each session = copy of defaults
• All sessions in "scheduled" status
↓
Optional: Customize Individual Sessions
• Click on any session
• Modify price, add ticket types, change time
• Example: Special guest session - increase price
↓
Publish Series
• All sessions go live
• Users can start registering
↓
Ongoing Management
• Monitor registrations per session
• Can still customize future sessions
• Cancel individual sessions if needed
• View attendance per session
↓
Each Session Day
• Check in attendees for that specific session
• Track attendance per session
↓
After Series Completes
• View overall series analytics
• Attendance patterns
• Revenue per session
• Download reports
Additional Features & Considerations
Waitlist Management
When Event/Session is at Capacity:
User tries to register
↓
Event is full
↓
Option to "Join Waitlist"
↓
User added to waitlist
↓
If spot opens (cancellation/refund)
↓
First person on waitlist notified
↓
Limited time to claim spot (e.g., 24 hours)
↓
If claimed: Registration processed
If not claimed: Offer to next person
Waitlist Properties:
Order (first-come, first-served)
Expiration time for offers
Notifications when spots available
User can leave waitlist
Event Updates & Notifications
Notify Attendees When:
Event details changed (date, time, location)
Event cancelled
New announcement from organizer
Reminder before event (24 hours, 1 hour)
Event starts soon (for online events - show link)
For Recurring Events:
Notify about upcoming session (24 hours before)
Notify if specific session cancelled
Notify if session time/location changed
Analytics & Reporting
For Organizers:
Total registrations
Revenue by ticket type
Sales over time (graph)
Attendance rate
Demographics (if collected)
For recurring: Per-session breakdown
For Platform:
Total events created
Event types distribution
Popular categories
Revenue metrics
User engagement
Social Features
Event Sharing:
Share on social media
Generate shareable link
Embed event widget
Reviews & Ratings:
After event, attendees can rate/review
Displayed on event page
Builds organizer reputation
Following:
Users can follow organizers
Get notified of new events
Implementation Priority
Phase 1: MVP (Core Features)
One-time event creation & management
Basic ticket types (free & paid)
Simple registration flow
Public event visibility
In-person and manual online link support
Basic attendee management
Phase 2: Enhanced Features
Multi-day events
Recurring events (simple - uniform pricing)
Private events with invitation system
Unlisted events
Multiple ticket types per event
Waitlist functionality
Phase 3: Advanced Features
Recurring events with variable pricing per session
Zoom/provider integration
Hybrid events with attendance mode selection
Advanced analytics
Event series customization (per-session modifications)
Refund automation
Phase 4: Premium Features
Social features (reviews, following)
Event recommendations
Advanced reporting
API for third-party integrations
White-label options
Mobile app
Conclusion
This document provides comprehensive requirements for an event management system supporting three distinct event types with flexible ticketing and access control. The system is designed to scale from simple one-time events to complex recurring series with variable pricing.
Key Differentiators:
Support for recurring events with per-session ticket management
Flexible visibility options (public, private, unlisted)
Multiple location modes including hybrid
Integration with online meeting providers
Granular ticket type control
Success Metrics:
Number of events created
Registration conversion rate
User satisfaction (organizers & attendees)
Platform revenue
Event completion rate
This system empowers organizers to create professional events while providing attendees with a smooth discovery and registration experience.
Document Version: 1.0
Last Updated: November 23, 2025
Status: Requirements Approved - Ready for Development