# Session Context - spotlight.cam **Quick reference for resuming development sessions** --- ## 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:** MVP Complete - Production Ready (Phase 3.7 complete) **Tests:** 351/351 backend tests passing - 100% ✅ (73% coverage) **Recent Work:** Beta testing features, environment reorganization, footer updates, seed script separation, production resource limits ### Core Features (All Implemented) - JWT authentication with email verification (AWS SES) - Cloudflare Turnstile CAPTCHA (bot protection on registration & contact form) - Real-time chat (Socket.IO) - event rooms + private 1:1 - Real-time active users with instant updates - Message validation (2000 char limit with visual counter) - Spam protection (rate limiting, duplicate detection, profanity filter) - WebRTC P2P file transfer (RTCDataChannel, up to 700MB tested) - Cloudflare TURN/STUN servers with dynamic configuration - Fallback to public STUN servers - Competition heats system for matchmaking - Recording matching system with 3-tier account system (BASIC/SUPPORTER/COMFORT) - Fairness algorithm (karma tracking: recordingsDone vs recordingsReceived) - Dual buffer system (prep before + rest after dancing) - Matching runs audit with origin_run_id tracking - Incremental matching (preserves accepted/completed suggestions) - Scheduler integration (automated matching with cron) - Atomic stats updates with race condition prevention - Clickable usernames in navbar, country flags - Public profiles (/u/{username}) - accessible without authentication - Static content pages (About Us, How It Works, Privacy Policy) - HTML-based - Contact form with admin panel - 404 page with activity logging - Dedicated Footer component for authenticated users (removed History link) - GDPR/RODO cookie consent banner - Google Analytics 4 integration with privacy controls - Beta testing features (dismissible banner, auto SUPPORTER tier assignment) - Matches & ratings API - QR code event check-in - PWA (offline support, iOS compatible) - Responsive mobile design - Security: CSRF, rate limiting, account lockout, trust proxy - Test bot for automated testing - Activity Log System - admin monitoring dashboard with real-time streaming (18 action types) --- ## Project Structure (Key Paths) ``` /spotlightcam ├── Makefile # Dev commands (dev-up, seed-dev, seed-prod, test, etc.) ├── docker-compose.yml # nginx:8080 + frontend + backend + db (dev/prod profiles with resource limits) ├── frontend/ │ ├── .env.development # Frontend env vars (VITE_BETA_MODE, VITE_GA_MEASUREMENT_ID) │ ├── .env.production │ ├── public/content/ # Static HTML content (about-us.html, how-it-works.html, privacy.html) │ └── src/ │ ├── pages/ # React pages (Home, Profile, Contact, 404, AboutUs, HowItWorks, Privacy) │ │ └── admin/ # Admin pages (ActivityLogsPage.jsx, ContactMessagesPage.jsx) │ ├── components/ # Reusable components │ │ ├── common/ # TierBadge, CookieConsent, BetaBanner │ │ ├── layout/ # Navbar (no History link), Layout (with Footer), Footer │ │ └── events/ # ParticipantsSidebar (user status grouping) │ ├── contexts/ # AuthContext │ ├── services/ # api.js, socket.js, webrtcAPI │ ├── hooks/ # useWebRTC.js, usePageTracking.js (GA4) │ ├── utils/ # analytics.js (GA4 integration) │ └── constants/ # MATCH_STATUS, SUGGESTION_STATUS, etc. ├── backend/ │ ├── .env.development # Backend env vars (BETA_AUTO_SUPPORTER) │ ├── .env.production │ └── src/ │ ├── routes/ # API endpoints (events.js, matches.js, admin.js, webrtc.js, public.js) │ ├── controllers/ # Business logic (auth.js with beta auto-tier) │ ├── services/ # matching.js (auto-matching), activityLog.js (audit trail) │ ├── middleware/ # auth.js, admin.js (requireAdmin) │ ├── socket/ # Socket.IO handlers (chat, WebRTC, admin logs) │ ├── utils/ # request.js (IP extraction) │ ├── constants/ # Status constants │ ├── prisma/ │ │ ├── seed.development.js # Admin + test users + events │ │ └── seed.production.js # Admin + divisions + competition types only │ └── __tests__/ # Jest tests (351 tests - 100% passing) └── docs/ ├── SESSION_CONTEXT.md # This file - quick context ├── TODO.md # Current tasks & roadmap ├── ARCHITECTURE.md # Technical details ├── DEPLOYMENT.md # Deployment guide ├── MONITORING.md # Operations guide ├── GOOGLE_ANALYTICS_SETUP.md # GA4 integration ├── TESTING_MATCHING_RATINGS.md # Test documentation ├── WEBRTC_TESTING_GUIDE.md # WebRTC testing guide └── archive/ # Archived documentation ``` --- ## Database Schema (12 tables) Key models: - `users` - Auth, profile, social links, location, lockout fields, `isAdmin` flag - Account tiers: `accountTier` (BASIC/SUPPORTER/COMFORT), `recordingsDone`, `recordingsReceived` - `events` - Dance events with unique slugs - `event_participants` - User-event relationship, competitorNumber, recorderOptOut, `accountTierOverride` - `divisions` / `competition_types` / `event_user_heats` - Competition system - `matches` - User pairings with CUID slugs - `ratings` - 1-5 stars, comments, `statsApplied` flag - `recording_suggestions` - Auto-matching results with collision detection, `originRunId` tracking - `matching_runs` - Audit trail (manual/scheduler, status, stats) - `chat_rooms` / `messages` - Real-time chat persistence - `activity_logs` - Comprehensive audit trail (18 action types, indexed for performance) --- ## Recent Changes (2025-12-06) ### Phase 3.7 - Beta Testing & Infrastructure Updates ✅ **Beta features, environment reorganization, footer improvements, seed separation, resource limits** **Commits:** `a786b1d` (GA4), `3523172` (GDPR cookie consent), `2cab8c3` (profile links), `229aafc` (remove manual matching), `76be8a4` (confirmation modals), `4066bf1` (footer & navbar), `b556abb` (seed scripts), `e1fabeb` (resource limits) **1. Beta Testing Features** - Dismissible beta banner (BetaBanner component) controlled by `VITE_BETA_MODE` env var - Auto-assign SUPPORTER tier to new registrations via `BETA_AUTO_SUPPORTER` env var - TierBadge component for displaying SUPPORTER/COMFORT badges (Sparkles/Crown icons) - Badge display in navbar, public profiles, and user lists - Files: `frontend/src/components/BetaBanner.jsx`, `frontend/src/components/common/TierBadge.jsx`, `backend/src/controllers/auth.js` **2. Environment Reorganization** - Moved .env files from root to `frontend/` and `backend/` subdirectories - Pattern: `.env.{development,production}{,.example}` - Updated docker-compose.yml to use new paths - Files: `frontend/.env.development`, `backend/.env.development`, docker-compose.yml **3. Privacy & Analytics** - Created dedicated /privacy page with GDPR/RODO compliant privacy policy - GDPR cookie consent banner (CookieConsent component) with localStorage persistence - Google Analytics 4 integration with privacy controls - Cookie consent controls GA initialization - Files: `frontend/public/content/privacy.html`, `frontend/src/components/common/CookieConsent.jsx`, `frontend/src/utils/analytics.js` **4. UI/UX Improvements** - Updated How It Works page with detailed 10-step user guide - Dedicated Footer component for authenticated users (Layout) - Removed History link from navbar (desktop & mobile) - ParticipantsSidebar now groups users by status: - Available (online + heats) - green dot - Online - No Heats (yellow dot) - disabled match button - Offline (gray dot) - faded match button if has heats - "No heats declared" badge in UserListItem - Profile links to usernames in Participants tab - Files: `frontend/src/components/layout/Footer.jsx`, `frontend/src/components/layout/Navbar.jsx`, `frontend/src/components/events/ParticipantsSidebar.jsx` **5. Database Seeding** - Split seed.js into seed.development.js and seed.production.js - Production seed: admin user + divisions + competition types only - Development seed: everything + test users + events + heats - Admin account: admin@spotlight.cam (COMFORT tier, isAdmin flag) - Test users: john/sarah/mike@spotlight.cam (SUPPORTER tier, no wsdcId) - Makefile commands: `make seed-dev`, `make seed-prod` - Files: `backend/prisma/seed.development.js`, `backend/prisma/seed.production.js`, `backend/package.json`, `Makefile` **6. Production Resource Limits** - Configured docker-compose.yml production profile for 4 CPU / 8GB server - nginx-prod: 0.5 CPU / 512M (limits), 0.25 CPU / 256M (reserved) - frontend-prod: 0.5 CPU / 512M (limits), 0.25 CPU / 256M (reserved) - backend-prod: 1.5 CPU / 2G (limits), 1.0 CPU / 1G (reserved) - db-prod: 1.0 CPU / 3G (limits), 0.75 CPU / 2G (reserved) - Total: 3.5 CPU / 6GB limits, leaves ~0.5 CPU / 2GB for host - File: `docker-compose.yml` --- ## Recent Changes (2025-12-03) ### Chat Enhancements - Complete ✅ **Real-time updates, message validation, and spam protection** **Commits:** `dd31761` (real-time users), `4a91a10` (message limits), `ace3311` (spam protection) **1. Real-time Active Users Fix (dd31761)** - Fixed bug where active users list didn't update when new users joined chat - Root cause: Used static `checkedInUsers` as base instead of real-time `activeUsers` - Solution: Rewrote `getAllDisplayUsers()` to prioritize Socket.IO data - Files: `frontend/src/pages/EventChatPage.jsx`, `frontend/src/hooks/useEventChat.js` **2. Message Length Limits (4a91a10)** - Added 2000 character limit for all chat messages (event + match chat) - Backend validation in `send_event_message` and `send_match_message` handlers - Frontend: `maxLength` attribute + character counter at 80% threshold (1600+) - Visual feedback: red text when at limit, submit button disabled - Files: `backend/src/constants/index.js`, `backend/src/socket/index.js`, `frontend/src/constants/index.js`, `frontend/src/components/chat/ChatInput.jsx` **3. Spam Protection System (ace3311)** - Rate Limiting: 10 messages per minute per user - Duplicate Detection: Prevents identical messages within 1 minute window - Profanity Filter: bad-words library (v2.0.0) with English + 11 Polish words - In-memory tracking with automatic cleanup every 5 minutes - User-friendly error messages for each validation type - Files: `backend/src/middleware/messageValidation.js` (new), `backend/src/socket/index.js`, `backend/package.json` --- ### Activity Log System (Phase 3.5) - Complete ✅ (2025-12-02) **Comprehensive admin monitoring with real-time streaming dashboard** **Backend (Phases 1-5):** - `activity_logs` table with 18 action types (AUTH_*, EVENT_*, MATCH_*, ADMIN_*, CHAT_*) - `activityLog.js` service - fire-and-forget logging, never blocks requests - `requireAdmin` middleware - fresh DB check for admin status - 3 API endpoints: query logs, get action types, get statistics - Socket.IO streaming - `admin_activity_logs` room with permission check - 14 integration points across auth, events, matches, socket handlers **Frontend (Phases 6-7):** - `ActivityLogsPage.jsx` (600+ lines) - full admin dashboard - Stats dashboard: total logs, unique users, failures, 24h activity - Advanced filtering: date range, category, action type, username, success/failure - Paginated table (50 per page) with color-coded action badges - Real-time streaming toggle (Socket.IO integration) - Admin-only route `/admin/activity-logs` with Shield icon in navbar **Files Created/Modified:** - Backend: `schema.prisma`, `activityLog.js`, `admin.js`, `request.js`, admin routes - Frontend: `ActivityLogsPage.jsx`, `api.js`, `App.jsx`, `Navbar.jsx` - Integration: 14 logging points in auth, events, matches, socket handlers **Admin User:** spotlight@radziel.com / Dance123! --- ## Quick Commands ```bash # Start development make dev-up # Or: docker compose --profile dev up make dev-down # Stop development # Database seeding make seed-dev # Seed with development data (admin + test users + events) make seed-prod # Seed with production data (admin + basic data only) # Testing make test # Run all backend tests make test-watch # Run tests in watch mode make test-coverage # Run tests with coverage report # Admin CLI make dev-cli # Interactive REPL docker compose exec backend npm run cli -- users:list --limit 20 # Access # Frontend: http://localhost:8080 # API: http://localhost:8080/api # Health: http://localhost:8080/api/health ``` --- ## Development Guidelines - **Code language:** All code, strings, comments in ENGLISH - **Communication:** POLISH with developer - **Git commits:** Standard format, NO AI mentions - **Port:** 8080 (not 80) - **Tailwind:** v3.4.0 (v4 has breaking changes) --- ## Key Constants ```javascript // frontend/src/constants/ & backend/src/constants/ MATCH_STATUS: pending | accepted | rejected | completed SUGGESTION_STATUS: pending | accepted | rejected | not_found CONNECTION_STATE: disconnected | connecting | connected | failed ACCOUNT_TIER: BASIC | SUPPORTER | COMFORT // Tier fairness penalties FAIRNESS_SUPPORTER_PENALTY: 10 FAIRNESS_COMFORT_PENALTY: 50 // Matching config MAX_RECORDINGS_PER_PERSON: 3 PREP_BUFFER_MINUTES: 30 REST_BUFFER_MINUTES: 60 ``` --- ## Test Accounts (Seeded) **Admin:** - admin@spotlight.cam / [password set during seed] (COMFORT tier, isAdmin) **Test Users:** | Username | Email | Password | Tier | |----------|-------|----------|------| | john_dancer | john@spotlight.cam | Dance123! | SUPPORTER | | sarah_swings | sarah@spotlight.cam | Swing456! | SUPPORTER | | mike_blues | mike@spotlight.cam | Blues789! | SUPPORTER | --- ## Test Coverage Summary **Total:** 342/342 tests passing (100% ✅) - **Matching Algorithm:** 19 tests (TC1-TC19) - Fundamentals, collision detection, limits, fairness, edge cases - **Ratings & Stats:** 9 tests - Atomic updates, race prevention, idempotency - **Matching Runs Audit:** 6 tests - origin_run_id tracking, sequential runs, filtering - **Incremental Matching:** 5 tests - **Recording Stats Integration:** 6 tests - **WebRTC Signaling:** 12 tests - **Socket.IO:** 12 tests - **API Routes:** Full CRUD coverage (auth, events, matches, dashboard) **Code Coverage:** - matching.js: 94.71% statements, 91.5% branches - routes/matches.js: 76.11% statements - routes/events.js: 78.2% statements --- ## For More Details - `docs/TODO.md` - Active tasks, security audit, future improvements - `docs/ARCHITECTURE.md` - Technical implementation details - `docs/TESTING_MATCHING_RATINGS.md` - Comprehensive test documentation - `docs/DEPLOYMENT.md` - Production deployment guide - `docs/MONITORING.md` - Operations and monitoring - `docs/archive/COMPLETED.md` - Full history of completed features --- **Last Updated:** 2025-12-06