spotlightcam/README.md

# spotlight.cam 🎥

**P2P video exchange app for the dance community** - matchmaking, chat, and WebRTC file transfer directly between users.

---

## 🎯 What is this?

Web application (PWA) enabling dance event participants to:
- Find recording partners via smart auto-matching
- Exchange competition videos peer-to-peer using WebRTC
- Rate collaborations and track partnership history
- Chat in real-time (event rooms + private 1:1 messages)

**Key Feature:** Direct browser-to-browser video file transfer using WebRTC DataChannel - no files stored on server, end-to-end encrypted (DTLS), tested up to 700MB+.

---

## ✅ Core Features

### Authentication & Security
- JWT authentication with bcrypt password hashing
- Email verification via AWS SES (link + PIN code)
- Password reset workflow
- WSDC integration (auto-fill profile data from worldsdc.com)
- Event slugs (alphanumeric IDs preventing enumeration attacks)
- Security: CORS, CSRF, Helmet.js, rate limiting, account lockout

### Events & Chat
- Event list from worldsdc.com
- Real-time event chat (Socket.IO) with active users sidebar
- Infinite scroll message history
- Clickable usernames (/@{username}) with country flags
- Competitor numbers (bib numbers) display

### Auto-matching & Fairness System
- Smart recording assignment for competition heats
- 3-tier account system (BASIC/SUPPORTER/COMFORT) with fairness algorithm
- Karma tracking (recordingsDone vs recordingsReceived)
- Dual buffer system (prep time before + rest time after dancing)
- Collision detection (schedule conflicts, max recordings limit)
- Matching runs audit with origin_run_id tracking
- Incremental matching (preserves accepted/completed suggestions)
- Automated scheduler (cron-based)

### Matchmaking & Private Chat
- Manual match requests with real-time notifications
- Private 1:1 chat for matched users
- Match slugs (CUID) preventing ID enumeration

### WebRTC P2P File Transfer
- Browser-to-browser video file exchange (RTCDataChannel)
- 16KB chunking with progress monitoring
- STUN servers for NAT traversal
- E2E encryption (DTLS/SRTP)
- WebRTC capability detection
- User-friendly fallback when WebRTC blocked
- Tested up to 700MB+ file transfers

### Ratings & Stats
- Partner ratings (1-5 stars, comments)
- "Would collaborate again" indicator
- Public rating display on user profiles
- Atomic stats updates (race condition prevention)
- Source filtering (auto vs manual matches)
- Auto-completion when both partners rated

### User Profiles
- Public profiles (/@{username}) visible to logged-in users
- Social media links (YouTube, Instagram, Facebook, TikTok)
- Location (country + city with 195 countries)
- Profile statistics (matches, average rating, reviews)

### Admin & Monitoring
- Activity Log System with real-time streaming dashboard
- Comprehensive audit trail (auth, events, matches, chat, admin actions)
- Filter logs by date range, action type, category, username, success/failure
- Real-time Socket.IO streaming (like `tail -f`)
- Admin-only access with requireAdmin middleware
- Statistics dashboard (total logs, failures, 24h activity)

### PWA & Infrastructure
- Progressive Web App (offline support, iOS compatible)
- Docker Compose orchestration (nginx, frontend, backend, PostgreSQL)
- PostgreSQL 15 with Prisma ORM (12 tables)
- Admin CLI with REPL for operations

---

## 🛠️ Tech Stack

**Frontend:** React 18 + Vite + Tailwind CSS v3.4.0 + Socket.IO Client + WebRTC
**Backend:** Node.js 20 + Express 4.18 + Socket.IO 4.8 + JWT + bcrypt
**Database:** PostgreSQL 15 + Prisma ORM 5.22
**Infrastructure:** Docker Compose + Nginx + Alpine Linux
**Testing:** Jest + Supertest (342 tests, 72.5% coverage, 100% passing ✅)

---

## 🚀 Quick Start

### Prerequisites
- Docker and Docker Compose

### 1. Start the application

```bash
# Clone repository
git clone <repo-url>
cd spotlightcam

# Copy environment file
cp backend/.env.example backend/.env

# Start development mode
docker compose --profile dev up

# Open browser
http://localhost:8080
```

### 2. Test the application

Use seeded accounts:
- john@example.com / Dance123!
- sarah@example.com / Swing456!
- mike@example.com / Blues789!

**Flow:**
1. Login → Select event → Join chat
2. Request match with another user → Accept
3. Send video via WebRTC (P2P transfer)
4. Rate partner after exchange

### Commands

```bash
# Stop services
docker compose --profile dev down

# Rebuild after changes
docker compose --profile dev up --build

# Run tests
docker compose exec backend npm test

# Run specific test suite
docker compose exec backend npm test -- matching-algorithm.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
```

---

## 📊 Test Coverage

**Backend: 342/342 tests passing - 100% ✅** (72.5% overall coverage)

### Test Suites
- **Matching Algorithm**: 19/19 integration tests
  - Fundamentals, collision detection, limits, fairness, edge cases
- **Ratings & Stats Flow**: 9/9 E2E tests
  - Atomic updates, race prevention, idempotency
- **Matching Runs Audit**: 6/6 tests
  - origin_run_id tracking, sequential runs, filtering
- **Incremental Matching**: 5/5 tests
- **Recording Stats Integration**: 6/6 tests
- **WebRTC Signaling**: 12/12 tests
- **Socket.IO**: 12/12 tests
- **API Routes**: Full CRUD coverage (auth, events, matches, dashboard)

### Code Coverage Highlights
- matching.js: 94.71% statements, 91.5% branches
- routes/matches.js: 76.11% statements
- routes/events.js: 78.2% statements

**Comprehensive test documentation:** See `docs/TESTING_MATCHING_RATINGS.md` for detailed breakdown of all 45 matching/ratings tests.

---

## 📁 Project Structure

```
spotlightcam/
├── docker-compose.yml          # Container orchestration (dev + prod profiles)
├── nginx/                      # Nginx reverse proxy config
├── frontend/                   # React PWA
│   ├── src/
│   │   ├── components/        # React components
│   │   ├── pages/             # Application pages
│   │   │   └── admin/         # Admin pages (ActivityLogsPage)
│   │   ├── hooks/             # Custom hooks (useWebRTC)
│   │   ├── contexts/          # AuthContext
│   │   ├── services/          # API client, Socket.IO client
│   │   └── constants/         # Status constants
│   ├── Dockerfile             # Development container
│   └── Dockerfile.prod        # Production build
├── backend/                    # Node.js + Express API
│   ├── src/
│   │   ├── controllers/       # Auth, users, events, WSDC
│   │   ├── routes/            # API routes (events, matches, admin)
│   │   ├── services/          # Matching algorithm, activity logging
│   │   ├── middleware/        # Auth, admin access control
│   │   ├── socket/            # Socket.IO handlers (chat, WebRTC signaling, admin logs)
│   │   └── __tests__/         # Jest tests (342 tests)
│   ├── prisma/
│   │   ├── schema.prisma      # Database schema (12 tables)
│   │   └── migrations/        # Database migrations
│   ├── Dockerfile             # Development container
│   └── Dockerfile.prod        # Production build
└── docs/                       # Documentation
    ├── SESSION_CONTEXT.md     # Quick session context (for resuming work)
    ├── TODO.md                # Active tasks & roadmap
    ├── ARCHITECTURE.md        # Technical implementation details
    ├── DEPLOYMENT.md          # Production deployment guide
    ├── MONITORING.md          # Operations & monitoring
    ├── TESTING_MATCHING_RATINGS.md  # Comprehensive test documentation
    ├── WEBRTC_TESTING_GUIDE.md      # WebRTC testing guide
    └── archive/               # Archived documentation
```

---

## 🗄️ Database Schema

12 tables with relations (Prisma ORM):

**Core Tables:**
- `users` - Authentication, profile, social links, location, account tiers, isAdmin flag
- `events` - Dance events with unique slugs
- `event_participants` - User-event relationship, competitor numbers
- `matches` - User pairings with CUID slugs
- `ratings` - 1-5 stars, comments, statsApplied flag
- `chat_rooms` / `messages` - Real-time chat persistence

**Matching System:**
- `divisions` / `competition_types` / `event_user_heats` - Competition heats
- `recording_suggestions` - Auto-matching results with collision detection, originRunId
- `matching_runs` - Audit trail (manual/scheduler, status, stats)

**Admin & Monitoring:**
- `activity_logs` - Comprehensive audit trail with 18 action types, indexed for performance

**Other:**
- `event_checkin_tokens` - QR code check-in

See `docs/ARCHITECTURE.md` for detailed schema documentation.

---

## 🧰 Admin CLI

Quick operations via REPL or command mode:

```bash
# Start REPL
docker compose exec backend npm run cli

# List users
docker compose exec backend npm run cli -- users:list --limit 20

# Create user
docker compose exec backend npm run cli -- users:create --email admin@example.com --username admin --password 'Secret123!'

# Verify email
docker compose exec backend npm run cli -- users:verify --email admin@example.com

# List events
docker compose exec backend npm run cli -- events:list --limit 10

# Import WSDC events
docker compose exec backend npm run cli -- events:import:wsdc --dry-run --since 2024-01-01 --until 2024-12-31

# Event details
docker compose exec backend npm run cli -- events:details --slug warsaw-dance-2025

# Check-in user to event
docker compose exec backend npm run cli -- events:checkin --username john_doe --slug warsaw-dance-2025

# List matches
docker compose exec backend npm run cli -- matches:list --limit 20 --status accepted
```

**REPL mode:** Top-level await works for Prisma queries, e.g., `await prisma.user.findMany({ take: 5 })`

---

## 🔐 Security Features

**Implemented:**
- bcrypt password hashing (10 salt rounds)
- JWT authentication (httpOnly cookies in production)
- Email verification required
- Input validation (express-validator)
- SQL injection prevention (Prisma parameterized queries)
- XSS protection (input sanitization)
- Rate limiting (login: 5/15min, registration: 3/hour, email: 3/hour)
- CORS configuration
- CSRF protection
- Helmet.js security headers
- Account lockout after failed attempts
- Content Security Policy
- Unique slugs preventing ID enumeration

---

## 📖 Documentation

**For quick start:**
- `docs/SESSION_CONTEXT.md` - Quick context for resuming sessions (recommended for AI assistants)

**Main documentation:**
- `docs/TODO.md` - Active tasks, security audit, roadmap
- `docs/ARCHITECTURE.md` - Technical details, WebRTC flow, API endpoints
- `docs/TESTING_MATCHING_RATINGS.md` - Comprehensive test documentation (45 tests)
- `docs/DEPLOYMENT.md` - Production deployment guide
- `docs/MONITORING.md` - Operations and monitoring

**Testing guides:**
- `docs/WEBRTC_TESTING_GUIDE.md` - WebRTC P2P testing

**Archived:**
- `docs/archive/COMPLETED.md` - Full history of completed features
- `docs/archive/PHASE_1.5.md` - Phase 1.5 documentation
- `docs/archive/SECURITY_AUDIT.md` - Security audit & fixes

---

## 🎯 Roadmap

### ✅ Completed Phases

**Phase 0:** Frontend mockup with routing
**Phase 1:** Backend foundation (Node.js, Express, PostgreSQL, Socket.IO)
**Phase 1.5:** Email verification (AWS SES), WSDC integration, profiles
**Phase 2:** Matches & ratings API, message history
**Phase 2.5:** WebRTC P2P file transfer with fallback UX
**Phase 3:** MVP finalization (landing page, dashboard, security hardening, PWA, auto-matching)
**Phase 3.5:** Activity Log System (admin monitoring, real-time streaming dashboard, 18 action types)

### ⏳ Future Extensions (Phase 4)
- User badges & trust system
- Push notifications
- Video compression
- Multi-file transfer
- Block users

---

## 🤝 Contributing

**Development Guidelines:**
- **Code language:** All code, strings, comments in ENGLISH
- **Communication:** POLISH with team
- **Git commits:** Standard format WITHOUT AI mentions
- **Port:** 8080 (not 80 in dev)
- **Tailwind:** v3.4.0 (NOT v4 - breaking changes)

**Git workflow:**
```bash
git status
git add .
git commit -m "feat: description"
```

---

## 📄 License

TBD

---

**Status:** MVP Complete ✅ | 342/342 tests passing (100%) | Production Ready
**Last Updated:** 2025-12-02