spotlightcam/docs/SESSION_CONTEXT.md

Session Context - spotlight.cam

Quick reference for resuming development sessions - optimized for minimal token usage

---

Project Overview

Name: spotlight.cam Purpose: P2P video exchange app for dance event participants Main Feature: WebRTC P2P video file transfer (no server storage) Tech Stack: React + Vite + Tailwind | Node.js + Express + Socket.IO | PostgreSQL 15 | Docker Compose

---

Current Status

Phase: 1.6 (Competition Heats System) - ✅ COMPLETED (Backend ✅ + Frontend ✅) Previous Phase: 1.5 (Email & WSDC & Profiles & Security & QR Check-in) - ✅ COMPLETED Progress: 100% Next Goal: Phase 2 - Core Features (Matches API, Ratings, WebRTC signaling)

What Works Now

• ✅ Docker Compose (nginx:8080 + frontend + backend + PostgreSQL)
• ✅ All frontend views with real API integration
• ✅ Backend API (Node.js + Express)
• ✅ PostgreSQL database with 8 tables (Prisma ORM)
• ✅ Real authentication (JWT + bcrypt)
• ✅ Email verification (AWS SES with link + PIN code) - Phase 1.5
• ✅ Password reset workflow - Phase 1.5
• ✅ WSDC ID integration for auto-fill registration - Phase 1.5
• ✅ User profiles with social media & location - Phase 1.5
• ✅ Public profiles (/{username}) - Phase 1.5
• ✅ Event participation tracking - Phase 1.5
• ✅ Event security (unique slugs, no ID enumeration) - Phase 1.5
• ✅ QR code event check-in system - Phase 1.5 (requires physical presence at venue)
• ✅ Competition heats declaration system - Phase 1.6 (matchmaking prerequisite)
• ✅ Real-time chat (Socket.IO for event & match rooms)
• ✅ WebRTC P2P transfer UI mockup

What's Missing

• ⏳ Matches API (create/accept/list matches)
• ⏳ Ratings API (rate partner after collaboration)
• ⏳ WebRTC signaling (SDP/ICE exchange via Socket.IO)
• ⏳ Actual WebRTC P2P file transfer implementation

---

Tech Stack

Infrastructure:

• Docker Compose (nginx, frontend, backend, PostgreSQL db)
• nginx reverse proxy on port 8080 (API + WebSocket)

Frontend:

• React 18 + Vite
• Tailwind CSS v3.4.0 (NOT v4 - compatibility issues)
• React Router
• Context API for state
• socket.io-client for real-time chat

Backend:

• Node.js 20 + Express 4.18.2
• Socket.IO 4.8.1 for WebSocket (real-time chat)
• PostgreSQL 15 with Prisma ORM 5.8.0
• bcrypt + JWT authentication
• Jest + supertest for testing (81%+ coverage)

WebRTC:

• RTCPeerConnection
• RTCDataChannel (file transfer)
• Chunking (16KB chunks)
• STUN/TURN servers

---

Project Structure

/spotlightcam
├── docker-compose.yml          # nginx + frontend + backend + PostgreSQL
├── nginx/                      # Proxy config (API + WebSocket)
├── frontend/                   # React PWA
│   ├── src/
│   │   ├── pages/             # All views (Login, Register, Events, Chat, Match, Rate, History)
│   │   ├── contexts/          # AuthContext (JWT integration)
│   │   ├── components/        # Layout, Navbar
│   │   ├── services/          # API client, Socket.IO client
│   │   └── mocks/             # Mock data (events, users for UI)
├── backend/                    # Node.js + Express API
│   ├── src/
│   │   ├── controllers/       # Auth, users, events
│   │   ├── middleware/        # Authentication middleware
│   │   ├── routes/            # API routes
│   │   ├── socket/            # Socket.IO server
│   │   ├── utils/             # Auth utils, DB connection
│   │   └── __tests__/         # Jest unit tests
│   └── prisma/                # Database schema, migrations, seed
└── docs/
    ├── SESSION_CONTEXT.md     # This file
    ├── CONTEXT.md             # Full project description
    ├── TODO.md                # Task list
    ├── ARCHITECTURE.md        # Technical details
    ├── COMPLETED.md           # Completed tasks archive
    └── RESOURCES.md           # Learning resources

---

Key Files

Frontend:

• frontend/src/pages/RegisterPage.jsx - Two-step registration (WSDC lookup + form)
• frontend/src/pages/VerifyEmailPage.jsx - Email verification (link + code)
• frontend/src/pages/ForgotPasswordPage.jsx - Request password reset
• frontend/src/pages/ResetPasswordPage.jsx - Reset password with token
• frontend/src/pages/ProfilePage.jsx - UPDATED: Edit profile (social media, location) - Phase 1.5
• frontend/src/pages/PublicProfilePage.jsx - NEW: View other user profiles - Phase 1.5
• frontend/src/pages/EventsPage.jsx - UPDATED: Shows check-in requirement, dev-only QR access - Phase 1.5
• frontend/src/pages/EventChatPage.jsx - UPDATED: Heats integration (banner, badges, filtering) - Phase 1.6
• frontend/src/pages/EventDetailsPage.jsx - NEW: QR code display, participant list - Phase 1.5
• frontend/src/pages/EventCheckinPage.jsx - NEW: Check-in confirmation page - Phase 1.5
• frontend/src/pages/MatchChatPage.jsx - Private chat + WebRTC mockup
• frontend/src/components/heats/HeatsBanner.jsx - NEW: Heats declaration form component - Phase 1.6
• frontend/src/components/common/PasswordStrengthIndicator.jsx - Password strength indicator
• frontend/src/components/common/VerificationBanner.jsx - Email verification banner
• frontend/src/contexts/AuthContext.jsx - JWT authentication integration
• frontend/src/services/api.js - UPDATED: Heats API (divisionsAPI, competitionTypesAPI, heatsAPI) - Phase 1.6
• frontend/src/services/socket.js - Socket.IO client connection manager
• frontend/src/data/countries.js - NEW: List of 195 countries - Phase 1.5

Backend:

• backend/src/controllers/auth.js - Register, login, email verification, password reset
• backend/src/controllers/user.js - UPDATED: Profile updates (social, location) - Phase 1.5
• backend/src/controllers/wsdc.js - WSDC API proxy for dancer lookup
• backend/src/routes/events.js - UPDATED: Heats management endpoints (POST/GET/DELETE /heats) - Phase 1.6
• backend/src/routes/divisions.js - NEW: List all divisions - Phase 1.6
• backend/src/routes/competitionTypes.js - NEW: List all competition types - Phase 1.6
• backend/src/routes/users.js - UPDATED: Public profile endpoint - Phase 1.5
• backend/src/socket/index.js - UPDATED: heats_updated broadcast event, getIO export - Phase 1.6
• backend/src/utils/email.js - AWS SES email service with HTML templates
• backend/src/utils/auth.js - Token generation utilities
• backend/src/middleware/auth.js - Email verification middleware
• backend/src/middleware/validators.js - UPDATED: Social media URL validation - Phase 1.5
• backend/src/server.js - Express server with Socket.IO integration
• backend/prisma/schema.prisma - UPDATED: 8 tables (EventCheckinToken added) - Phase 1.5
• backend/prisma/migrations/20251113151534_add_wsdc_and_email_verification/ - Phase 1.5 migration
• backend/prisma/migrations/20251113202500_add_event_slug/ - NEW: Event slugs migration - Phase 1.5
• backend/prisma/migrations/20251114125544_add_event_checkin_tokens/ - NEW: QR check-in tokens - Phase 1.5

Config:

• docker-compose.yml - nginx, frontend, backend, PostgreSQL
• nginx/conf.d/default.conf - Proxy for /api and /socket.io
• backend/.env - UPDATED: AWS SES credentials, email settings - Phase 1.5

---

Database Schema (Implemented - Prisma)

11 tables with relations:

• users - EXTENDED in Phase 1.5:
  • Base: id, username, email, password_hash, avatar, created_at, updated_at
  • WSDC: first_name, last_name, wsdc_id
  • Email Verification: email_verified, verification_token, verification_code, verification_token_expiry
  • Password Reset: reset_token, reset_token_expiry
  • Social Media: youtube_url, instagram_url, facebook_url, tiktok_url
  • Location: country, city
• events - id, slug (unique), name, location, start_date, end_date, description, worldsdc_id, participants_count
• event_participants - NEW in Phase 1.5: id, user_id, event_id, joined_at (many-to-many)
• event_checkin_tokens - NEW in Phase 1.5: id, event_id (unique), token (cuid, unique), created_at
• divisions - NEW in Phase 1.6: id, name, abbreviation, display_order (Newcomer, Novice, Intermediate, Advanced, All-Star, Champion)
• competition_types - NEW in Phase 1.6: id, name, abbreviation (Jack & Jill, Strictly)
• event_user_heats - NEW in Phase 1.6: id, user_id, event_id, division_id, competition_type_id, heat_number (1-9), role (Leader/Follower/NULL)
• chat_rooms - id, event_id, match_id, type (event/private), created_at
• messages - id, room_id, user_id, content, type, created_at
• matches - id, user1_id, user2_id, event_id, room_id, status, created_at
• ratings - id, match_id, rater_id, rated_id, score, comment, would_collaborate_again, created_at

Migrations:

• 20251112205214_init - Initial schema
• 20251113151534_add_wsdc_and_email_verification - Phase 1.5 (email, WSDC, social, location)
• 20251113202500_add_event_slug - Phase 1.5 (event security - unique slugs)
• 20251114125544_add_event_checkin_tokens - Phase 1.5 (QR code check-in system)
• 20251114142504_add_competition_heats_system - Phase 1.6 (competition heats for matchmaking)

Seed data: 4 events, 6 divisions, 2 competition types, event chat rooms

---

User Flow

1. Register/Login
2. Choose event (from worldsdc.com list)
3. Event chat - matchmaking
4. Match confirmation → private 1:1 chat
5. Select video from gallery (recorded outside app)
6. WebRTC P2P transfer (direct, no server storage) OR link sharing fallback
7. Rate partner (1-5 stars, comment)

---

Development Guidelines

Code Language

• All code, strings, UI text, comments: ENGLISH
• Variable/function names: ENGLISH
• Communication with developer: POLISH

Git Commits

• Standard format, NO mentions of AI/automatic generation
• ✅ Good: feat: add WebRTC P2P video transfer
• ❌ Bad: feat: add video transfer (generated by AI)

Important Decisions

• Port 8080 (port 80 was occupied)
• Tailwind CSS v3.4.0 (v4 has breaking changes with Vite)
• Mock authentication uses localStorage
• All UI text in English

---

Next Steps (Phase 2 - Core Features)

Priority: HIGH Estimated Time: 12-15 hours

Step 1: Matches API (3-4h)

• POST /api/matches - Create match request
• POST /api/matches/:id/accept - Accept match
• GET /api/matches - List user's matches
• Frontend integration (match request flow)
• Tests

Step 2: Ratings API (2-3h)

• POST /api/ratings - Submit rating after collaboration
• GET /api/users/:id/ratings - Get user's ratings
• Frontend integration (rating form)
• Tests

Step 3: WebRTC Signaling (3-4h)

• Socket.IO events for SDP/ICE exchange
• Signaling flow (offer/answer/ice-candidate)
• Frontend WebRTC setup (RTCPeerConnection)
• Connection establishment tests

Step 4: WebRTC File Transfer (4-5h)

• RTCDataChannel setup
• File chunking (16KB chunks)
• Progress monitoring (sender & receiver)
• Error handling & reconnection
• Complete P2P video transfer flow

---

Common Commands

Start project:

docker compose up --build

Access:

• Frontend: http://localhost:8080
• Backend API: http://localhost:8080/api
• Socket.IO: ws://localhost:8080/socket.io
• Health check: http://localhost:8080/api/health

Rebuild after changes:

docker compose down
docker compose up --build

Git:

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

---

Known Issues & Solutions

Issue: Tailwind v4 compatibility error

Solution: Downgraded to Tailwind v3.4.0

npm install -D tailwindcss@^3.4.0

Issue: Port 80 already allocated

Solution: Changed nginx port to 8080 in docker-compose.yml

Issue: Prisma OpenSSL error in Alpine Linux

Solution: Added OpenSSL to Dockerfile

RUN apk add --no-cache openssl

---

WebRTC Implementation Notes (Future)

Main functionality - P2P file transfer:

• RTCPeerConnection for connection establishment
• RTCDataChannel for binary data transfer
• File chunking (16KB chunks recommended)
• Progress monitoring (both sender and receiver)
• Metadata exchange (filename, size, MIME type)
• Error handling and reconnection logic
• Fallback: link sharing (Google Drive, Dropbox)

Signaling:

• WebSocket (Socket.IO) for SDP/ICE exchange
• Server only for signaling, NOT for file storage

Security:

• WebRTC native encryption (DTLS/SRTP)
• Optional: additional chat encryption (WebCrypto API)

---

Quick Reference - Frontend Routes

• /login - Login page
• /register - Two-step registration (WSDC lookup + form)
• /verify-email - Email verification (link + PIN code)
• /forgot-password - Request password reset
• /reset-password/:token - Reset password with token
• /profile - Edit user profile (social media, location)
• /:username - Public profile view
• /events - Event list (joined events first, check-in requirement notice)
• /events/:slug/chat - Event chat (requires check-in, real-time Socket.IO)
• /events/:slug/details - NEW: Event details with QR code, participant list
• /events/checkin/:token - NEW: QR code check-in confirmation page
• /matches/:id/chat - Private 1:1 chat + WebRTC mockup
• /matches/:id/rate - Rate partner
• /history - Match history

---

Test Accounts

Test users for manual testing (seeded in database):

1. john_dancer

   • Email: john@example.com
   • Password: Dance123!
   • Profile: John Smith (WSDC #12345), Los Angeles, USA
   • Social: Instagram, YouTube
   • Events: Warsaw Dance Festival (checked in), Swing Camp Barcelona (checked in)
   • Heats in Warsaw: J&J NOV 1 L, STR INT 2 L

2. sarah_swings

   • Email: sarah@example.com
   • Password: Swing456!
   • Profile: Sarah Johnson (WSDC #23456), London, UK
   • Social: TikTok, Facebook
   • Events: Warsaw Dance Festival (checked in)
   • Heats in Warsaw: J&J NOV 1 F, J&J ADV 3

3. mike_blues

   • Email: mike@example.com
   • Password: Blues789!
   • Profile: Mike Williams (WSDC #34567), Stockholm, Sweden
   • Social: Instagram, YouTube, TikTok, Facebook
   • Events: Warsaw Dance Festival (checked in)
   • Heats in Warsaw: J&J INT 5 L, STR ADV 1 F

Note: All test users are verified and checked in to Warsaw Dance Festival 2025 event. They have pre-configured heats to test the matchmaking system.

---

Quick Reference - Events

Seeded Events (slugs are auto-generated cuid for security):

• Warsaw Dance Festival 2025 (slug: auto-generated, e.g. cmhz3lcgb00018vbn34v4phoi)
• Swing Camp Barcelona 2025 (slug: auto-generated)
• Blues Week Herräng 2025 (slug: auto-generated)
• Krakow Swing Connection 2025 (slug: auto-generated)

Note: Event slugs are randomly generated cuid strings to prevent ID enumeration attacks. To find the actual slug, log in and check the Events page URL.

---

Files to Read for Full Context

Minimal (for quick start):

• docs/SESSION_CONTEXT.md (this file)
• docker-compose.yml
• frontend/src/pages/MatchChatPage.jsx (WebRTC mockup)

Full context:

• docs/CONTEXT.md (project description)
• docs/TODO.md (task list)
• docs/ARCHITECTURE.md (technical details)

Archives:

• docs/COMPLETED.md (completed tasks)
• docs/RESOURCES.md (learning resources)

---

Last Updated: 2025-11-14 Phase 1 Status: ✅ COMPLETED - Backend Foundation (Express + PostgreSQL + JWT + Socket.IO) Phase 1.5 Status: ✅ COMPLETED - Email Verification & WSDC Integration & User Profiles & Security

• AWS SES email verification (link + PIN)
• Password reset workflow
• WSDC API integration
• User profiles (social media, location)
• Public profiles (/{username})
• Event participation tracking
• Event security (unique slugs, no ID enumeration)
• QR code event check-in system (physical presence required, dev mode bypass) Phase 1.6 Status: ✅ COMPLETED - Competition Heats System
• ✅ Backend: 3 new tables (divisions, competition_types, event_user_heats)
• ✅ API endpoints (GET /divisions, GET /competition-types, heats CRUD)
• ✅ Socket.IO heats_updated broadcast for real-time updates
• ✅ Frontend: HeatsBanner component for declaration
• ✅ EventChatPage integration: heat badges, filtering, Edit button
• ✅ Matchmaking disabled for users without declared heats Next Phase: Phase 2 - Core Features (Matches API + Ratings + WebRTC)