spotlight.cam 🎥

Web application (PWA) for the dance community enabling matchmaking, chat, and video file exchange directly via WebRTC (peer-to-peer).

🚀 Features

✅ Implemented

Authentication & Security:

• ✅ JWT Authentication - real authentication with bcrypt password hashing
• ✅ Email Verification - email verification via AWS SES (link + PIN code)
• ✅ Password Reset - complete password reset workflow
• ✅ WSDC Integration - auto-fill data from worldsdc.com during registration
• ✅ Event Slugs - unique alphanumeric identifiers preventing ID enumeration attacks

User Profiles:

• ✅ User Profiles - profile editing (first name, last name, WSDC ID)
• ✅ Social Media Links - YouTube, Instagram, Facebook, TikTok
• ✅ Location - country (dropdown with 195 countries with flags) and city
• ✅ Public Profiles - visible to other logged-in users at /@{username}
• ✅ Profile Statistics - number of matches, average rating, number of reviews
• ✅ Clickable Usernames - usernames in chat are clickable links to public profiles

Events & Chat:

• ✅ Event List - browse dance events from worldsdc.com
• ✅ Event Participation Tracking - automatic saving of joined events
• ✅ Real-time Event Chat - Socket.IO chat for event participants with country flags
• ✅ Active Users Sidebar - list of online users in the event
• ✅ Message History - message persistence in database
• ✅ Infinite Scroll - loading older messages
• ✅ Competitor Numbers - bib number display in event chat

Matchmaking & Private Chat:

• ✅ Match Requests - send and accept match requests with real-time notifications
• ✅ Match Management - view pending/active matches, accept/reject requests
• ✅ Private 1:1 Chat - private chat for matched users with Socket.IO and message history
• ✅ Match Slugs - secure random slugs (CUID) preventing ID enumeration

Ratings & Reviews:

• ✅ Partner Ratings - rate collaboration partners (1-5 stars, comments)
• ✅ Collaboration Preferences - "would collaborate again" indicator
• ✅ Public Rating Display - ratings visible on public user profiles
• ✅ Duplicate Prevention - users can only rate each match once
• ✅ Auto-completion - matches auto-complete when both partners have rated

WebRTC P2P File Transfer:

• ✅ WebRTC Signaling - SDP/ICE exchange via Socket.IO
• ✅ P2P File Transfer - RTCDataChannel with 16KB chunking (tested up to 700MB)
• ✅ WebRTC Detection - automatic detection of browser capabilities
• ✅ Fallback UX - user-friendly warnings when WebRTC blocked
• ✅ Real-time Progress - transfer progress monitoring for sender/receiver
• ✅ E2E Encryption - DTLS encryption (native WebRTC)
• ✅ Auto Download - automatic file download on receiver side

Landing Page:

• ✅ Homepage - professional landing page with hero section, features showcase, and CTAs
• ✅ Public Access - accessible to non-logged users with links to register/login
• ✅ Responsive Design - mobile-friendly with gradient backgrounds

Backend & Infrastructure:

• ✅ PostgreSQL Database - 11 tables with relations (Prisma ORM)
• ✅ RESTful API - Express.js backend with validation
• ✅ WebSocket - Socket.IO for real-time communication
• ✅ Docker Compose - full orchestration (nginx, frontend, backend, PostgreSQL)
• ✅ Test Coverage - comprehensive test suite for WebRTC, Auth, Events, Matches
• ✅ WebRTC Tests - full Socket.IO signaling and detection tests (7 tests passing)

Dashboard & Real-time:

• ✅ Dashboard - centralized landing page with active events, matches, requests
• ✅ Online Count - real-time users in event chat
• ✅ Unread Count - unread message badges per match
• ✅ Mobile-first Design - responsive chat layout with page titles on mobile

Auto-matching & Account Tiers:

• ✅ Smart Recording Matching - auto-assign recorders for competition heats with collision detection
• ✅ 3-Tier Account System - BASIC (free), SUPPORTER, COMFORT tiers with fairness-based assignment
• ✅ Fairness Algorithm - karma tracking (recordingsDone vs recordingsReceived) for balanced workload
• ✅ Dual Buffer System - prep time before and rest time after dancing (no buffer for recording)
• ✅ Tier Penalties - SUPPORTER (-10 fairness), COMFORT (-50 fairness) for reduced recording frequency
• ✅ Event-specific Upgrades - accountTierOverride for temporary tier boosts (e.g., Comfort Pass)
• ✅ Multi-criteria Sorting - Location > Fairness > Load balancing priority
• ✅ Competitor Numbers - bib number support for events

Security & PWA (All Implemented):

• ✅ Security Hardening - CORS, CSRF, Helmet.js, account lockout, rate limiting
• ✅ PWA Features - manifest, service worker, offline support, iOS compatible

🔜 Future Extensions

• ⏳ User Badges - trust system and reputation badges
• ⏳ Push Notifications - real-time alerts for matches and messages
• ⏳ Video Compression - client-side compression before transfer

🛠️ Tech Stack

Frontend

• React 18 - UI framework
• Vite - build tool and dev server
• Tailwind CSS v3.4.0 - styling
• React Router - routing
• Lucide React - icons
• Context API - state management (auth)
• Socket.IO Client - real-time WebSocket communication
• WebRTC - P2P file transfer (RTCPeerConnection, RTCDataChannel)

Backend

• Node.js 20 - runtime
• Express 4.18 - web framework
• PostgreSQL 15 - relational database
• Prisma ORM 5.22 - type-safe database client
• Socket.IO 4.8 - WebSocket server
• bcrypt - password hashing
• JWT - token-based authentication
• AWS SES - email service
• Jest + Supertest - testing (286 tests, 73% coverage)

Infrastructure

• Docker Compose - container orchestration (dev + prod profiles)
• Nginx - reverse proxy & static file serving
• Alpine Linux - lightweight container base images

📁 Project Structure

spotlightcam/
├── docker-compose.yml          # Container orchestration (dev + prod profiles)
├── nginx/                      # Nginx reverse proxy config
│   ├── nginx.conf
│   └── conf.d/default.conf    # Proxy /api & /socket.io to backend
├── frontend/                   # React PWA
│   ├── src/
│   │   ├── components/        # React components
│   │   │   ├── common/        # Shared components, PasswordStrength, VerificationBanner
│   │   │   ├── chat/          # Chat components
│   │   │   ├── video/         # WebRTC components (WebRTCWarning)
│   │   │   ├── layout/        # Navbar, Layout
│   │   │   └── __tests__/     # Component tests (WebRTCWarning)
│   │   ├── pages/             # Application pages
│   │   │   ├── HomePage.jsx             # Landing page with hero & features
│   │   │   ├── LoginPage.jsx
│   │   │   ├── RegisterPage.jsx         # Two-step registration with WSDC lookup
│   │   │   ├── VerifyEmailPage.jsx      # Email verification (link + PIN)
│   │   │   ├── ForgotPasswordPage.jsx   # Request password reset
│   │   │   ├── ResetPasswordPage.jsx    # Reset password with token
│   │   │   ├── ProfilePage.jsx          # Edit profile (social media, location)
│   │   │   ├── PublicProfilePage.jsx    # View other user's profile
│   │   │   ├── EventsPage.jsx           # Event list with real API
│   │   │   ├── EventChatPage.jsx        # Real-time event chat
│   │   │   ├── MatchChatPage.jsx        # Private chat + WebRTC P2P transfer
│   │   │   ├── RatePartnerPage.jsx      # Rate partner after collaboration
│   │   │   └── HistoryPage.jsx          # Match history
│   │   ├── hooks/             # Custom hooks (useWebRTC)
│   │   ├── utils/             # Utilities (webrtcDetection)
│   │   │   └── __tests__/     # Utility tests (webrtcDetection)
│   │   ├── contexts/          # AuthContext (JWT integration)
│   │   ├── services/          # API client, Socket.IO client
│   │   ├── data/              # Static data (countries list)
│   │   └── mocks/             # Mock data (for UI development)
│   ├── Dockerfile             # Development container
│   ├── Dockerfile.prod        # Production build
│   └── package.json
├── backend/                    # Node.js + Express API
│   ├── src/
│   │   ├── controllers/       # Auth, users, events, WSDC
│   │   ├── middleware/        # Auth, validation, error handling
│   │   ├── routes/            # API routes
│   │   ├── socket/            # Socket.IO server (event/match rooms, WebRTC signaling)
│   │   ├── utils/             # Auth utils, DB, email service (AWS SES)
│   │   └── __tests__/         # Jest unit tests
│   │   │   ├── socket-webrtc.test.js  # WebRTC signaling tests (7 tests)
│   │   │   ├── auth.test.js           # Authentication tests
│   │   │   ├── events.test.js         # Events API tests
│   │   │   ├── matches.test.js        # Matches API tests
│   │   │   └── ...                    # Other test suites
│   ├── prisma/
│   │   ├── schema.prisma      # Database schema (7 tables)
│   │   ├── migrations/        # Database migrations
│   │   └── seed.js            # Seed data
│   ├── Dockerfile             # Development container
│   ├── Dockerfile.prod        # Production build
│   └── package.json
└── docs/                       # Documentation
    ├── SESSION_CONTEXT.md     # Quick session context (minimal tokens)
    ├── CONTEXT.md             # Full project description
    ├── TODO.md                # Task list & roadmap
    ├── ARCHITECTURE.md        # Technical details
    ├── DEPLOYMENT.md          # Deployment guide
    ├── MONITORING.md          # Monitoring & operations
    ├── QUICKSTART.md          # Quick start guide
    ├── QUICK_TEST.md          # Quick test instructions
    ├── WEBRTC_TESTING_GUIDE.md # WebRTC testing guide
    └── archive/               # Archived documentation
        ├── COMPLETED.md       # Completed tasks archive
        ├── PHASE_1.5.md       # Phase 1.5 documentation
        ├── SECURITY_AUDIT.md  # Security audit & fixes
        ├── RESOURCES.md       # Learning resources
        └── ADMIN_CLI.md       # Admin CLI documentation

🚀 Getting Started

Requirements

• Docker and Docker Compose
• (Optional) Node.js 20+ for development without Docker

Development Mode

1. Clone the repository:

git clone <repo-url>
cd spotlightcam

2. Copy example .env file:

cp backend/.env.example backend/.env

3. Start Docker Compose with dev profile:

docker compose --profile dev up

4. Open browser:

http://localhost:8080

Production Mode

docker compose --profile prod up -d

Service Access

Development:

• Frontend: http://localhost:8080
• Backend API: http://localhost:8080/api
• WebSocket: ws://localhost:8080/socket.io
• Health check: http://localhost:8080/api/health
• PostgreSQL: localhost:5432 (exposed for dev tools)

Production:

• Application: http://localhost (port 80)
• HTTPS: https://localhost (port 443, requires SSL certificates)
• PostgreSQL: internal only (not exposed)

Stopping Services

# Development
docker compose --profile dev down

# Production
docker compose --profile prod down

Rebuild After Changes

docker compose --profile dev down
docker compose --profile dev up --build

🗄️ Database Schema

11 tables with relations (Prisma ORM):

1. users - users

   • Base: id, username, email, password_hash, avatar, created_at, updated_at
   • WSDC: first_name, last_name, wsdc_id
   • Email: email_verified, verification_token, verification_code, verification_token_expiry
   • Password Reset: reset_token, reset_token_expiry
   • Social: youtube_url, instagram_url, facebook_url, tiktok_url
   • Location: country, city
   • Account Tiers: account_tier (BASIC/SUPPORTER/COMFORT), recordings_done, recordings_received

2. events - dance events

   • id, slug (unique), name, location, start_date, end_date, description, worldsdc_id, participants_count

3. event_participants - event participants (many-to-many)

   • id, user_id, event_id, joined_at, recorder_opt_out, competitor_number
   • account_tier_override (optional event-specific tier upgrade)

4. chat_rooms - chat rooms

   • id, event_id, type (event/private), created_at

5. messages - messages

   • id, room_id, user_id, content, type (text/link/video), created_at

6. matches - user pairs

   • id, slug (unique cuid), user1_id, user2_id, event_id, room_id, status (pending/accepted/completed), created_at

7. ratings - ratings

   • id, match_id, rater_id, rated_id, score (1-5), comment, would_collaborate_again, created_at
   • Unique constraint: (match_id, rater_id, rated_id) - prevents duplicate ratings

8. event_checkin_tokens - QR code tokens for event access

   • id, event_id, token (cuid), created_at

9. divisions - competition divisions (Newcomer, Novice, Intermediate, etc.)

   • id, name, abbreviation, display_order

10. competition_types - competition types (Jack & Jill, Strictly, etc.)

    • id, name, abbreviation

11. event_user_heats - user's declared heats for matchmaking

    • id, user_id, event_id, division_id, competition_type_id, heat_number (1-9), role (Leader/Follower), created_at, updated_at
    • Unique constraint: (user_id, event_id, division_id, competition_type_id, role)

Migrations

# Development (inside backend container)
docker compose exec backend npx prisma migrate dev

# Production
docker compose exec backend-prod npx prisma migrate deploy

# Generate Prisma Client
docker compose exec backend npx prisma generate

Seed Data

docker compose exec backend npx prisma db seed

Adds:

• 3 events (Warsaw, Barcelona, Herräng)
• 2 users (john_doe, jane_smith)
• Event chat rooms

🧪 Testing the Application

Test Flow:

1. Landing Page (http://localhost:8080/)

   • View professional landing page with hero section
   • Explore features showcase and how-it-works section
   • Click "Get Started" to register or "Sign in" to login

2. Registration with WSDC (http://localhost:8080/register)

   • Optional: provide WSDC ID (e.g., 12345) for auto-fill
   • Complete registration form
   • You'll receive verification email (check AWS SES sandbox)

3. Email Verification (http://localhost:8080/verify-email)

   • Click link from email OR enter 6-digit PIN code
   • Email will be verified

4. Login (http://localhost:8080/login)

   • Email: john@example.com
   • Password: password123

5. Profile Editing (http://localhost:8080/profile)

   • Add social media links (Instagram, YouTube, etc.)
   • Select country from list of 195 countries
   • Enter city
   • Edit WSDC ID, first name, last name

6. Event Selection (http://localhost:8080/events)

   • View event list (joined events appear at top)
   • Select event (e.g., "Warsaw Dance Festival 2025")
   • Click "Join chat" or "Open chat" (if already joined)

7. Event Chat

   • Real-time chat with Socket.IO
   • Active users list on the right side
   • Click "+" icon next to user to connect
   • You'll be redirected to private 1:1 chat

8. 1:1 Chat - WebRTC P2P File Transfer 🔥

   • See partner's profile at top (click username to view public profile)
   • WebRTC connection status (disconnected/connecting/connected)
   • Sending video via WebRTC:
     • Click "Send video (WebRTC)"
     • Select video file from disk
     • Real P2P transfer via RTCDataChannel with STUN servers for NAT traversal
     • Supports files up to 700MB+ tested successfully
     • See real-time progress bar (16KB chunking)
     • Receiver automatically downloads the file
     • End-to-end encryption via DTLS (native WebRTC)
   • WebRTC Detection:
     • Automatic detection if WebRTC is blocked
     • User-friendly warning with fix suggestions
     • Button disabled when WebRTC unavailable
   • Fallback - link sharing:
     • Click "Link"
     • Paste video URL (Google Drive, Dropbox, etc.)
     • Alternative when WebRTC blocked (Opera, VPNs, privacy settings)

9. Rate Partner

   • Click "Finish and rate"
   • Select rating (1-5 stars)
   • Add comment
   • Mark if you want to collaborate again

10. Collaboration History (http://localhost:8080/history)

    • See list of matches
    • See received ratings
    • See statistics

11. Public Profiles

    • Click on another user's username
    • View profile: avatar, location, social media, statistics

🧰 Admin CLI

Use an in-container admin console for quick maintenance.

• Start REPL (default): docker compose exec backend npm run cli
• Explicit REPL: docker compose exec backend npm run cli -- repl
• List users: docker compose exec backend npm run cli -- users:list --limit 20
• Create user: docker compose exec backend npm run cli -- users:create --email admin@example.com --username admin --password 'Secret123!'
• Verify email: docker compose exec backend npm run cli -- users:verify --email admin@example.com
• List events: docker compose exec backend npm run cli -- events:list --limit 10
• Import WSDC (calendar/list) dry-run: docker compose exec backend npm run cli -- events:import:wsdc --dry-run --since 2024-01-01 --until 2024-12-31
• Import with location from list: docker compose exec backend npm run cli -- events:import:wsdc --source list --limit 50
• Enrich missing location: docker compose exec backend npm run cli -- events:import:wsdc --source list --update-missing-location
• Event details by slug: docker compose exec backend npm run cli -- events:details --slug warsaw-dance-2025 [--participants 25]
• Event participants: docker compose exec backend npm run cli -- events:participants --slug warsaw-dance-2025 --limit 100
• Event participants CSV: docker compose exec backend npm run cli -- events:participants --slug warsaw-dance-2025 --limit 200 --csv > participants.csv
• List matches: docker compose exec backend npm run cli -- matches:list --limit 20 [--status accepted|pending|completed]
• Check-in user to event (simulate QR): docker compose exec backend npm run cli -- events:checkin --username john_doe --slug warsaw-dance-2025
• App logs (if LOG_FILE configured): docker compose exec backend npm run cli -- logs:app --lines 200
• Recent chat messages: docker compose exec backend npm run cli -- logs:messages --limit 50

Production equivalents use backend-prod instead of backend.

REPL specifics:

• Inside REPL use run('users:list --limit 20') or .cli users:list --limit 20.
• Top-level await works for Prisma: await prisma.user.findMany({ take: 5 }).
• CLI errors in REPL do not exit the session; the error is printed so you can correct and retry.

🔐 Security

Implemented Security Features:

✅ Authentication:

• bcrypt password hashing (10 salt rounds)
• JWT tokens (httpOnly cookies in production)
• Protected routes with auth middleware
• Email verification required

✅ Input Validation:

• express-validator for all inputs
• Custom validators for URLs (domain checking)
• SQL injection prevention (Prisma parameterized queries)
• XSS protection (input sanitization)

✅ Rate Limiting:

• Login attempts: 5 per 15 minutes
• Registration: 3 per hour
• Email sending: 3 per hour

✅ Database:

• Unique constraints on emails, usernames
• Indexed fields for performance
• Cascading deletes for data integrity

✅ Event Security:

• Unique alphanumeric slugs (12 chars, MD5-based)
• Prevents ID enumeration attacks
• URLs: /events/{slug}/chat instead of /events/{id}/chat

✅ Socket.IO:

• JWT authentication for WebSocket connections
• Room-based access control
• User verification before joining rooms

Additional Security (Phase 3 - Implemented):

✅ CORS configuration ✅ CSRF protection (cookies) ✅ Helmet.js security headers ✅ Account lockout (after failed attempts) ✅ Content Security Policy ⏳ HTTPS enforcement (requires production SSL setup)

📊 Test Coverage

Backend: 73% overall coverage (285/286 tests passing - 99.7%)

• Matching Algorithm: 30/30 tests passing (unit tests for collision detection, buffers, tier system)
• WebRTC Signaling: 7/7 tests passing (offer/answer/ICE relay, authorization)
• Auth Controllers: Comprehensive coverage
• Events API: Full test suite
• Matches API: Full CRUD tests
• Dashboard API: 12 tests passing
• Socket.IO: Full WebRTC + chat coverage (1 flaky timeout test)
• Test Isolation: Fixed with unique test data per suite

Frontend: Test files ready (requires test runner setup)

• WebRTC detection utility tests
• WebRTC warning component tests

# Run all backend tests
docker compose exec backend npm test

# Run specific test suite
docker compose exec backend npm test -- socket-webrtc.test.js

# Coverage report
docker compose exec backend npm run test:coverage

🎯 Roadmap

✅ Phase 0: Frontend Mockup (COMPLETED)

• All views with mock data
• WebRTC UI mockup
• Routing & navigation

✅ Phase 1: Backend Foundation (COMPLETED)

• Node.js + Express + PostgreSQL
• JWT authentication
• Socket.IO real-time chat
• Test coverage 81%+

✅ Phase 1.5: Email & WSDC Integration (COMPLETED)

• Email verification (AWS SES)
• Password reset workflow
• WSDC API integration
• User profiles with social media & location
• Public profiles
• Event participation tracking
• Event security (slugs)

✅ Phase 2: Matches & Ratings API (COMPLETED)

• Matches API (create/accept match requests with slugs)
• Real-time match notifications via Socket.IO
• Ratings API (1-5 stars, comments, collaboration preferences)
• Public profile ratings display
• Profile links from chat and matches pages
• Message history for matches
• Duplicate rating prevention

✅ Phase 2.5: WebRTC P2P File Transfer (COMPLETED)

• WebRTC signaling (SDP/ICE exchange via Socket.IO)
• P2P file transfer via RTCDataChannel (16KB chunking)
• STUN servers for NAT traversal (production-ready)
• WebRTC capability detection (browser/network compatibility)
• User-friendly fallback UX when WebRTC blocked
• Tested up to 700MB file transfers
• E2E encryption (DTLS)
• Comprehensive test suite (7 backend tests passing)
• Professional landing page with hero section

✅ Phase 3: MVP Finalization (COMPLETED)

• ✅ Landing page
• ✅ Dashboard with online/unread counts
• ✅ Recording matching system (auto-assign recorders)
• ✅ Security hardening (CSRF, account lockout, rate limiting)
• ✅ PWA features (manifest, service worker, iOS support)
• ✅ All backend tests passing (286/286 - 100%)
• ✅ Production operations scripts (backup, restore, health check)
• ✅ Documentation cleanup and reorganization

⏳ Phase 4: Extensions (FUTURE)

• User badges & trust system
• Block users
• Push notifications
• Video compression
• Multi-file transfer

📖 Documentation

Quick Start:

• docs/SESSION_CONTEXT.md - Quick context for resuming sessions (minimal tokens)

Main Documentation:

• docs/CONTEXT.md - Main project description and assumptions
• docs/TODO.md - Active tasks and roadmap
• docs/ARCHITECTURE.md - Technical details and implementation
• docs/DEPLOYMENT.md - Deployment and production setup guide
• docs/MONITORING.md - Monitoring and operations guide

Quick Guides:

• docs/QUICKSTART.md - Quick start guide (2 minutes)
• docs/QUICK_TEST.md - Quick testing instructions
• docs/WEBRTC_TESTING_GUIDE.md - WebRTC testing guide

Archived Documentation:

• docs/archive/PHASE_1.5.md - Phase 1.5 documentation (Email & WSDC)
• docs/archive/SECURITY_AUDIT.md - Security audit & fixes
• docs/archive/ADMIN_CLI.md - Admin CLI & REPL usage
• docs/archive/COMPLETED.md - Completed tasks archive
• docs/archive/RESOURCES.md - Links to documentation and learning resources

🤝 Contributing

Project is in development phase. Currently implementing Phase 2 (Matches & Ratings API, WebRTC P2P transfer).

Git workflow:

git status
git add .
git commit -m "feat: description"

Note: Commit messages without mentions of AI/automatic generation.

📄 License

TBD

---

Current Status: MVP Complete ✅ | 285/286 tests passing (99.7%) | Ready for Production Deployment

Last Updated: 2025-11-29