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) and city
• ✅ Public Profiles - visible to other logged-in users at /{username}
• ✅ Profile Statistics - number of matches, average rating, number of reviews

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
• ✅ Active Users Sidebar - list of online users in the event
• ✅ Message History - message persistence in database
• ✅ Infinite Scroll - loading older messages

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

Backend & Infrastructure:

• ✅ PostgreSQL Database - 7 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 - 81%+ coverage (Jest + Supertest)

🔜 Next Up

• ⏳ STUN/TURN Servers - WebRTC NAT traversal for production
• ⏳ Server Upload Fallback - alternative when WebRTC blocked
• ⏳ Competition Heats - complete UI integration and real-time updates

🛠️ 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 (81%+ 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 video transfer (mockup)
│   │   │   └── layout/        # Navbar, Layout
│   │   ├── pages/             # Application pages
│   │   │   ├── 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 mockup
│   │   │   ├── RatePartnerPage.jsx      # Rate partner after collaboration
│   │   │   └── HistoryPage.jsx          # Match history
│   │   ├── 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)
│   │   ├── utils/             # Auth utils, DB, email service (AWS SES)
│   │   └── __tests__/         # Jest unit tests (81%+ coverage)
│   ├── 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
    ├── COMPLETED.md           # Completed tasks archive
    ├── PHASE_1.5.md           # Phase 1.5 documentation
    ├── SECURITY_AUDIT.md      # Security audit & fixes
    ├── DEPLOYMENT.md          # Deployment guide
    └── RESOURCES.md           # Learning resources

🚀 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

7 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

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

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

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. 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)

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

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

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

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

4. 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

5. 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)

6. 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

7. 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 (supports files up to 700MB+)
     • See real-time progress bar
     • Receiver automatically downloads the file
   • 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)

8. Rate Partner (coming soon - Matches & Ratings API)

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

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

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

10. Public Profiles

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

🔐 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

Planned Security Features (Phase 3):

⏳ CORS configuration ⏳ CSRF protection (cookies) ⏳ Helmet.js security headers ⏳ Content Security Policy ⏳ HTTPS enforcement (production)

📊 Test Coverage

Backend: 81%+ coverage

• Auth controllers: 78%
• Socket.IO module: 89%
• Jest + Supertest

# Run tests
docker compose exec backend npm test

# 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)
• WebRTC capability detection (browser/network compatibility)
• User-friendly fallback UX when WebRTC blocked
• Tested up to 700MB file transfers
• E2E encryption (DTLS)

⏳ Phase 3: MVP Finalization (PLANNED)

• Security hardening
• Integration & E2E tests
• PWA features (manifest, service worker)
• Production deployment
• Monitoring & logging

⏳ 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

Detailed Documentation:

• docs/ARCHITECTURE.md - Technical details and implementation
• docs/PHASE_1.5.md - Phase 1.5 documentation (Email & WSDC)
• docs/SECURITY_AUDIT.md - Security audit & fixes
• docs/DEPLOYMENT.md - Deployment guide
• docs/COMPLETED.md - Completed tasks archive
• docs/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: Phase 2.5 (WebRTC) ✅ Completed | Phase 3 (MVP) ⏳ Next | Progress: ~78% overall

Last Updated: 2025-11-15