spotlightcam/docs/SESSION_CONTEXT.md

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 Tests: 342/342 backend tests passing - 100% ✅ (72.5% coverage) Recent Work: Matching runs audit, ratings & stats system, comprehensive test suite

Core Features (All Implemented)

• JWT authentication with email verification (AWS SES)
• Real-time chat (Socket.IO) - event rooms + private 1:1
• WebRTC P2P file transfer (RTCDataChannel, up to 700MB tested)
• 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 with @ prefix, country flags
• Matches & ratings API
• QR code event check-in
• PWA (offline support, iOS compatible)
• Security: CSRF, rate limiting, account lockout
• Test bot for automated testing

---

Project Structure (Key Paths)

/spotlightcam
├── docker-compose.yml       # nginx:8080 + frontend + backend + db
├── frontend/src/
│   ├── pages/               # React pages
│   ├── components/          # Reusable components
│   ├── contexts/            # AuthContext
│   ├── services/            # api.js, socket.js
│   ├── hooks/               # useWebRTC.js
│   └── constants/           # MATCH_STATUS, SUGGESTION_STATUS, etc.
├── backend/src/
│   ├── routes/              # API endpoints (events.js, matches.js, admin.js)
│   ├── controllers/         # Business logic
│   ├── services/            # matching.js (auto-matching algorithm)
│   ├── socket/              # Socket.IO handlers
│   ├── constants/           # Status constants
│   └── __tests__/           # Jest tests (342 tests - 100% passing)
│       ├── matching-algorithm.test.js      # 19 tests
│       ├── ratings-stats-flow.test.js      # 9 tests
│       ├── matching-runs-audit.test.js     # 6 tests
│       ├── matching-incremental.test.js    # 5 tests
│       └── socket.test.js                  # 12 tests
└── 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
    ├── TESTING_MATCHING_RATINGS.md  # Comprehensive test documentation (45 tests)
    ├── WEBRTC_TESTING_GUIDE.md      # WebRTC testing guide
    └── archive/             # Archived documentation

---

Database Schema (11 tables)

Key models:

• users - Auth, profile, social links, location, lockout fields
  • 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

---

Recent Changes (Last 2 Days)

Matching Runs Audit System

• File: backend/src/__tests__/matching-runs-audit.test.js (6 tests)
• Features:
  • origin_run_id assignment and tracking
  • Sequential runs create separate audit records
  • Accepted suggestions preserve origin_run_id across re-runs
  • Admin endpoints with filtering (onlyAssigned, includeNotFound)
  • Manual vs scheduler trigger differentiation

Ratings & Stats Integration

• File: backend/src/__tests__/ratings-stats-flow.test.js (9 tests)
• Features:
  • Atomic stats updates (recordingsDone, recordingsReceived)
  • Race condition prevention with statsApplied flag
  • Source filtering (only auto matches update stats)
  • Idempotency (double-rating prevention)
  • E2E double-rating completion flow

Documentation

• Updated: README.md with current test statistics (342/342)
• New: docs/TESTING_MATCHING_RATINGS.md (comprehensive 45-test overview)
• Archived: Outdated quick start guides

---

Quick Commands

# Start development
docker compose --profile dev up

# Run all backend tests
docker compose exec backend npm test

# Run specific test suite
docker compose exec backend npm test -- matching-runs-audit.test.js

# Coverage report
docker compose exec backend npm run test:coverage

# Admin CLI
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

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

Username	Email	Password
john_dancer	john@example.com	Dance123!
sarah_swings	sarah@example.com	Swing456!
mike_blues	mike@example.com	Blues789!

---

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-11-30