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 (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