# 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.5 (Email Verification & WSDC Integration + User Profiles + Security) - ✅ COMPLETED **Progress:** ~65% **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 7 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** - ✅ 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: Real API, joined events first - Phase 1.5** - `frontend/src/pages/EventChatPage.jsx` - **UPDATED: Uses slugs instead of IDs - Phase 1.5** - `frontend/src/pages/MatchChatPage.jsx` - Private chat + WebRTC mockup - `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: eventsAPI uses slugs - Phase 1.5** - `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: Uses slugs instead of IDs - Phase 1.5** - `backend/src/routes/users.js` - **UPDATED: Public profile endpoint - Phase 1.5** - `backend/src/socket/index.js` - **UPDATED: Slug-based event rooms, participation tracking - Phase 1.5** - `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: 7 tables (social, location, event_participants, slugs) - 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** **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) 7 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) - `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)** **Seed data:** 3 events, 2 users, 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) - `/events/:slug/chat` - Event chat (public, real-time Socket.IO) - `/matches/:id/chat` - Private 1:1 chat + WebRTC mockup - `/matches/:id/rate` - Rate partner - `/history` - Match history --- ## Quick Reference - Mock Data **Mock User (logged in):** - ID: 1 - Username: john_doe - Email: john@example.com **Mock Events:** - ID: 1 - Warsaw Dance Festival 2025 - ID: 2 - Swing Camp Barcelona 2025 - ID: 3 - Blues Week Herräng 2025 --- ## 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-13 **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) **Next Phase:** Phase 2 - Core Features (Matches API + Ratings + WebRTC)