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

---

## ⚠️ PRODUCTION ENVIRONMENT

**Status:** ✅ **LIVE IN PRODUCTION**
**URL:** https://spotlight.cam
**Deployed:** 2025-12-09
**Users:** Real users with real data

### Critical Development Guidelines

#### Database Safety
- ⚠️ **NEVER** run migrations without testing in development first
- Always backup production database before schema changes
- Use `npx prisma migrate dev --create-only` to preview SQL
- Test data operations in dev environment before production
- Use transactions for multi-step operations

#### Deployment Process
1. Test thoroughly in development (`docker compose --profile dev up`)
2. Run full test suite (`make test` - all 351 tests must pass)
3. Review changes: `git diff origin/master`
4. Deploy during low-traffic periods
5. Monitor logs after deployment: `docker compose logs -f backend-prod`

#### Emergency Rollback
- Keep previous Docker images: `docker images | grep app-`
- Rollback command: `docker compose --profile prod down && docker tag OLD_IMAGE NEW_IMAGE && docker compose --profile prod up -d`
- Have database backup ready at all times

#### What to NEVER Do
- ❌ Drop tables or columns without migration plan
- ❌ Change primary keys or foreign key relationships
- ❌ Deploy without running tests
- ❌ Push directly to master without review
- ❌ Test experimental features on production data

#### Recent Bug Fixes (Phase 3.8 - Dec 2025)
1. Admin dropdown persistence (session fields)
2. Mobile chat scroll behavior
3. Polish characters in name validation
4. WSDC ID type conversion
5. Match chat message display
6. Socket.IO reconnection handling
7. Docker production build scripts

All fixes deployed successfully with zero downtime.