spotlightcam/README.md

spotlight.cam 🎥

P2P video exchange app for the dance community - matchmaking, chat, and WebRTC file transfer directly between users.

---

🎯 What is this?

Web application (PWA) enabling dance event participants to:

• Find recording partners via smart auto-matching
• Exchange competition videos peer-to-peer using WebRTC
• Rate collaborations and track partnership history
• Chat in real-time (event rooms + private 1:1 messages)

Key Feature: Direct browser-to-browser video file transfer using WebRTC DataChannel - no files stored on server, end-to-end encrypted (DTLS), tested up to 700MB+.

---

✅ Core Features

Authentication & Security

• JWT authentication with bcrypt password hashing
• Email verification via AWS SES (link + PIN code)
• Password reset workflow
• WSDC integration (auto-fill profile data from worldsdc.com)
• Event slugs (alphanumeric IDs preventing enumeration attacks)
• Cloudflare Turnstile CAPTCHA (bot protection on registration & contact form)
• Security: CORS, CSRF, Helmet.js, rate limiting, account lockout
• Trust proxy for correct client IP detection behind nginx

Events & Chat

• Event list from worldsdc.com
• Real-time event chat (Socket.IO) with active users sidebar
• Real-time active users list (instant updates when users join/leave)
• Infinite scroll message history
• Clickable usernames (/@{username}) with country flags
• Competitor numbers (bib numbers) display
• Message validation: 2000 character limit with visual counter
• Spam protection: rate limiting (10 msg/min), duplicate detection, profanity filter
• Polish + English profanity filtering

Auto-matching & Fairness System

• Smart recording assignment for competition heats
• 3-tier account system (BASIC/SUPPORTER/COMFORT) with fairness algorithm
• Karma tracking (recordingsDone vs recordingsReceived)
• Dual buffer system (prep time before + rest time after dancing)
• Collision detection (schedule conflicts, max recordings limit)
• Matching runs audit with origin_run_id tracking
• Incremental matching (preserves accepted/completed suggestions)
• Automated scheduler (cron-based)

Matchmaking & Private Chat

• Manual match requests with real-time notifications
• Private 1:1 chat for matched users
• Match slugs (CUID) preventing ID enumeration

WebRTC P2P File Transfer

• Browser-to-browser video file exchange (RTCDataChannel)
• 16KB chunking with progress monitoring
• Cloudflare TURN/STUN servers for reliable NAT traversal
• Dynamic ICE server configuration with fallback to public STUN
• E2E encryption (DTLS/SRTP)
• WebRTC capability detection
• User-friendly fallback when WebRTC blocked
• Tested up to 700MB+ file transfers

Ratings & Stats

• Partner ratings (1-5 stars, comments)
• "Would collaborate again" indicator
• Public rating display on user profiles
• Atomic stats updates (race condition prevention)
• Source filtering (auto vs manual matches)
• Auto-completion when both partners rated

User Profiles & Public Pages

• Public profiles (/u/{username}) accessible without authentication
• Clickable usernames in navbar linking to profile
• Social media links (YouTube, Instagram, Facebook, TikTok)
• Location (country + city with 195 countries)
• Profile statistics (average rating, reviews)
• Responsive mobile layout
• 404 page with activity logging for invalid routes
• About Us and How It Works pages (markdown-based static content)

Admin & Monitoring

• Activity Log System with real-time streaming dashboard
• Comprehensive audit trail (auth, events, matches, chat, admin actions)
• Filter logs by date range, action type, category, username, success/failure
• Real-time Socket.IO streaming (like tail -f)
• Admin-only access with requireAdmin middleware
• Statistics dashboard (total logs, failures, 24h activity)
• Contact form submissions with admin panel
• Admin dropdown menu in navbar (Activity Logs, Contact Messages)

PWA & Infrastructure

• Progressive Web App (offline support, iOS compatible)
• Docker Compose orchestration (nginx, frontend, backend, PostgreSQL)
• PostgreSQL 15 with Prisma ORM (12 tables)
• Admin CLI with REPL for operations

---

🛠️ Tech Stack

Frontend: React 18 + Vite + Tailwind CSS v3.4.0 + Socket.IO Client + WebRTC Backend: Node.js 20 + Express 4.18 + Socket.IO 4.8 + JWT + bcrypt Database: PostgreSQL 15 + Prisma ORM 5.22 Infrastructure: Docker Compose + Nginx + Alpine Linux Testing: Jest + Supertest (351 tests, 73% coverage, 100% passing ✅) External Services: AWS SES (email), Cloudflare Turnstile (CAPTCHA), Cloudflare TURN (WebRTC)

---

🚀 Quick Start

Prerequisites

• Docker and Docker Compose

1. Start the application

# Clone repository
git clone <repo-url>
cd spotlightcam

# Copy environment file
cp backend/.env.example backend/.env

# Start development mode
docker compose --profile dev up

# Open browser
http://localhost:8080

2. Test the application

Use seeded accounts:

• john@example.com / Dance123!
• sarah@example.com / Swing456!
• mike@example.com / Blues789!

Flow:

1. Login → Select event → Join chat
2. Request match with another user → Accept
3. Send video via WebRTC (P2P transfer)
4. Rate partner after exchange

Commands

# Stop services
docker compose --profile dev down

# Rebuild after changes
docker compose --profile dev up --build

# Run tests
docker compose exec backend npm test

# Run specific test suite
docker compose exec backend npm test -- matching-algorithm.test.js

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

# Admin CLI
docker compose exec backend npm run cli -- users:list --limit 20

---

📊 Test Coverage

Backend: 351/351 tests passing - 100% ✅ (73% overall coverage)

Test Suites

• Matching Algorithm: 19/19 integration tests
  • Fundamentals, collision detection, limits, fairness, edge cases
• Ratings & Stats Flow: 9/9 E2E tests
  • Atomic updates, race prevention, idempotency
• Matching Runs Audit: 6/6 tests
  • origin_run_id tracking, sequential runs, filtering
• Incremental Matching: 5/5 tests
• Recording Stats Integration: 6/6 tests
• WebRTC Signaling: 12/12 tests
• WebRTC API: 9/9 tests (Cloudflare TURN integration, fallbacks, authentication)
• Socket.IO: 12/12 tests
• API Routes: Full CRUD coverage (auth, events, matches, dashboard, webrtc)

Code Coverage Highlights

• matching.js: 94.71% statements, 91.5% branches
• routes/matches.js: 76.11% statements
• routes/events.js: 78.2% statements
• routes/webrtc.js: 100% coverage (9 comprehensive tests)

Comprehensive test documentation: See docs/TESTING_MATCHING_RATINGS.md for detailed breakdown of all 45 matching/ratings tests.

---

📁 Project Structure

spotlightcam/
├── docker-compose.yml          # Container orchestration (dev + prod profiles)
├── nginx/                      # Nginx reverse proxy config
├── frontend/                   # React PWA
│   ├── public/content/        # Static markdown content (About Us, How It Works)
│   ├── src/
│   │   ├── components/        # React components
│   │   ├── pages/             # Application pages (Home, Profile, Contact, 404)
│   │   │   └── admin/         # Admin pages (ActivityLogsPage, ContactMessages)
│   │   ├── hooks/             # Custom hooks (useWebRTC with Cloudflare TURN)
│   │   ├── contexts/          # AuthContext
│   │   ├── services/          # API client, Socket.IO client, WebRTC API
│   │   └── constants/         # Status constants
│   ├── Dockerfile             # Development container
│   └── Dockerfile.prod        # Production build
├── backend/                    # Node.js + Express API
│   ├── src/
│   │   ├── controllers/       # Auth, users, events, WSDC
│   │   ├── routes/            # API routes (events, matches, admin, webrtc, public)
│   │   ├── services/          # Matching algorithm, activity logging
│   │   ├── middleware/        # Auth, admin access, message validation (spam protection)
│   │   ├── socket/            # Socket.IO handlers (chat, WebRTC signaling, admin logs)
│   │   └── __tests__/         # Jest tests (351 tests, 100% passing)
│   ├── prisma/
│   │   ├── schema.prisma      # Database schema (12 tables)
│   │   └── migrations/        # Database migrations
│   ├── Dockerfile             # Development container
│   └── Dockerfile.prod        # Production build
└── docs/                       # Documentation
    ├── SESSION_CONTEXT.md     # Quick session context (for resuming work)
    ├── TODO.md                # Active tasks & roadmap
    ├── ARCHITECTURE.md        # Technical implementation details
    ├── DEPLOYMENT.md          # Production deployment guide
    ├── MONITORING.md          # Operations & monitoring
    ├── TESTING_MATCHING_RATINGS.md  # Comprehensive test documentation
    ├── WEBRTC_TESTING_GUIDE.md      # WebRTC testing guide
    └── archive/               # Archived documentation

---

🗄️ Database Schema

12 tables with relations (Prisma ORM):

Core Tables:

• users - Authentication, profile, social links, location, account tiers, isAdmin flag
• events - Dance events with unique slugs
• event_participants - User-event relationship, competitor numbers
• matches - User pairings with CUID slugs
• ratings - 1-5 stars, comments, statsApplied flag
• chat_rooms / messages - Real-time chat persistence

Matching System:

• divisions / competition_types / event_user_heats - Competition heats
• recording_suggestions - Auto-matching results with collision detection, originRunId
• matching_runs - Audit trail (manual/scheduler, status, stats)

Admin & Monitoring:

• activity_logs - Comprehensive audit trail with 18 action types, indexed for performance

Other:

• event_checkin_tokens - QR code check-in

See docs/ARCHITECTURE.md for detailed schema documentation.

---

🧰 Admin CLI

Quick operations via REPL or command mode:

# Start REPL
docker compose exec backend npm run cli

# 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 events
docker compose exec backend npm run cli -- events:import:wsdc --dry-run --since 2024-01-01 --until 2024-12-31

# Event details
docker compose exec backend npm run cli -- events:details --slug warsaw-dance-2025

# Check-in user to event
docker compose exec backend npm run cli -- events:checkin --username john_doe --slug warsaw-dance-2025

# List matches
docker compose exec backend npm run cli -- matches:list --limit 20 --status accepted

REPL mode: Top-level await works for Prisma queries, e.g., await prisma.user.findMany({ take: 5 })

---

🔐 Security Features

Implemented:

• bcrypt password hashing (10 salt rounds)
• JWT authentication (httpOnly cookies in production)
• Email verification required
• Input validation (express-validator)
• SQL injection prevention (Prisma parameterized queries)
• XSS protection (input sanitization)
• Rate limiting (login: 5/15min, registration: 3/hour, email: 3/hour)
• CORS configuration
• CSRF protection
• Helmet.js security headers
• Account lockout after failed attempts
• Content Security Policy
• Unique slugs preventing ID enumeration

---

📖 Documentation

For quick start:

• docs/SESSION_CONTEXT.md - Quick context for resuming sessions (recommended for AI assistants)

Main documentation:

• docs/TODO.md - Active tasks, security audit, roadmap
• docs/ARCHITECTURE.md - Technical details, WebRTC flow, API endpoints
• docs/TESTING_MATCHING_RATINGS.md - Comprehensive test documentation (45 tests)
• docs/DEPLOYMENT.md - Production deployment guide
• docs/MONITORING.md - Operations and monitoring

Testing guides:

• docs/WEBRTC_TESTING_GUIDE.md - WebRTC P2P testing

Archived:

• docs/archive/COMPLETED.md - Full history of completed features
• docs/archive/PHASE_1.5.md - Phase 1.5 documentation
• docs/archive/SECURITY_AUDIT.md - Security audit & fixes

---

🎯 Roadmap

✅ Completed Phases

Phase 0: Frontend mockup with routing Phase 1: Backend foundation (Node.js, Express, PostgreSQL, Socket.IO) Phase 1.5: Email verification (AWS SES), WSDC integration, profiles Phase 2: Matches & ratings API, message history Phase 2.5: WebRTC P2P file transfer with fallback UX Phase 3: MVP finalization (landing page, dashboard, security hardening, PWA, auto-matching) Phase 3.5: Activity Log System (admin monitoring, real-time streaming dashboard, 18 action types) Phase 3.6: Public enhancements (Cloudflare CAPTCHA, public profiles, static pages, responsive design, Cloudflare TURN)

⏳ Future Extensions (Phase 4)

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

---

🤝 Contributing

Development Guidelines:

• Code language: All code, strings, comments in ENGLISH
• Communication: POLISH with team
• Git commits: Standard format WITHOUT AI mentions
• Port: 8080 (not 80 in dev)
• Tailwind: v3.4.0 (NOT v4 - breaking changes)

Git workflow:

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

---

📄 License

TBD

---

Status: MVP Complete ✅ | 351/351 tests passing (100%) | Production Ready Last Updated: 2025-12-05