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:** 2.5 (WebRTC P2P File Transfer) - ✅ COMPLETED
**Previous Phases:**
- Phase 2 (Matches & Ratings API) - ✅ COMPLETED
- Phase 1.6 (Competition Heats) - ✅ COMPLETED
- Phase 1.5 (Email & WSDC & Profiles & Security & QR Check-in) - ✅ COMPLETED
**Progress:** ~78% overall
**Next Goal:** Phase 3 - MVP Finalization (Security hardening, PWA, Production deployment)

### 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)
- ✅ **Matches API (create/accept/list matches with slugs) - Phase 2**
- ✅ **Ratings API (rate partners, 1-5 stars, comments) - Phase 2**
- ✅ **WebRTC signaling (SDP/ICE exchange via Socket.IO) - Phase 2.5**
- ✅ **WebRTC P2P file transfer (RTCDataChannel, 16KB chunks, up to 700MB tested) - Phase 2.5**
- ✅ **WebRTC detection & fallback UX (auto-detect browser capabilities) - Phase 2.5**
- ✅ Real-time chat (Socket.IO for event & match rooms)

### What's Missing
- ⏳ STUN/TURN servers configuration for production (NAT traversal)
- ⏳ Server-based upload fallback (when WebRTC blocked)
- ⏳ Security hardening (CORS, CSRF, Helmet, CSP)
- ⏳ PWA features (manifest, service worker, offline support)
- ⏳ Production deployment & monitoring

---

## 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:**
```bash
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:**
```bash
docker compose down
docker compose up --build
```

**Git:**
```bash
git status
git add .
git commit -m "feat: description"
```

---

## Known Issues & Solutions

### Issue: Tailwind v4 compatibility error
**Solution:** Downgraded to Tailwind v3.4.0
```bash
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
```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)