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

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)
• /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)