radziel/spotlightcam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
02d3d7ac4286e246916103decd2c1d1132b32ab2
spotlightcam/docs/SESSION_CONTEXT.md
Radosław Gierwiało 61f504fa72 docs: update documentation for QR code check-in system
2025-11-14 14:43:33 +01:00

14 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: 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 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)
  • ✅ 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: Access control with check-in verification, Leave Event - Phase 1.5
  • 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/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: QR check-in methods (checkin, getDetails, leave) - 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: QR check-in endpoints (checkin, details, leave), participant verification - Phase 1.5
  • backend/src/routes/users.js - UPDATED: Public profile endpoint - Phase 1.5
  • backend/src/socket/index.js - UPDATED: Participant verification before room join, security fix - 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: 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)

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

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:

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

Quick Reference - Mock Data

Mock User (logged in):

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-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) Next Phase: Phase 2 - Core Features (Matches API + Ratings + WebRTC)