radziel/spotlightcam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b6ed1db084d573d4a8776341db621a1c1c9b5521
spotlightcam/docs/SESSION_CONTEXT.md
Radosław Gierwiało b6ed1db084 docs: update README and SESSION_CONTEXT for completed WebRTC implementation 
Updated documentation to reflect Phase 2.5 completion:
- Moved WebRTC from 'Next Up' to 'Implemented' features
- Added WebRTC to tech stack
- Updated test flow with real WebRTC details
- Marked Phase 2.5 as COMPLETED in roadmap
- Updated progress to ~78% overall
- Updated SESSION_CONTEXT.md current status and missing features
2025-11-15 16:16:03 +01:00

17 KiB
Raw Blame History

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:

docker compose up --build

Access:

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)