spotlightcam/README.md

# spotlight.cam 🎥

Web application (PWA) for the dance community enabling matchmaking, chat, and video file exchange directly via WebRTC (peer-to-peer).

## 🚀 Features

### ✅ Implemented

**Authentication & Security:**
- ✅ **JWT Authentication** - real authentication with bcrypt password hashing
- ✅ **Email Verification** - email verification via AWS SES (link + PIN code)
- ✅ **Password Reset** - complete password reset workflow
- ✅ **WSDC Integration** - auto-fill data from worldsdc.com during registration
- ✅ **Event Slugs** - unique alphanumeric identifiers preventing ID enumeration attacks

**User Profiles:**
- ✅ **User Profiles** - profile editing (first name, last name, WSDC ID)
- ✅ **Social Media Links** - YouTube, Instagram, Facebook, TikTok
- ✅ **Location** - country (dropdown with 195 countries) and city
- ✅ **Public Profiles** - visible to other logged-in users at /{username}
- ✅ **Profile Statistics** - number of matches, average rating, number of reviews

**Events & Chat:**
- ✅ **Event List** - browse dance events from worldsdc.com
- ✅ **Event Participation Tracking** - automatic saving of joined events
- ✅ **Real-time Event Chat** - Socket.IO chat for event participants
- ✅ **Active Users Sidebar** - list of online users in the event
- ✅ **Message History** - message persistence in database
- ✅ **Infinite Scroll** - loading older messages

**Matchmaking & Private Chat:**
- ✅ **Match Requests** - send and accept match requests with real-time notifications
- ✅ **Match Management** - view pending/active matches, accept/reject requests
- ✅ **Private 1:1 Chat** - private chat for matched users with Socket.IO and message history
- ✅ **Match Slugs** - secure random slugs (CUID) preventing ID enumeration

**Ratings & Reviews:**
- ✅ **Partner Ratings** - rate collaboration partners (1-5 stars, comments)
- ✅ **Collaboration Preferences** - "would collaborate again" indicator
- ✅ **Public Rating Display** - ratings visible on public user profiles
- ✅ **Duplicate Prevention** - users can only rate each match once
- ✅ **Auto-completion** - matches auto-complete when both partners have rated

**WebRTC P2P File Transfer:**
- ✅ **WebRTC Signaling** - SDP/ICE exchange via Socket.IO
- ✅ **P2P File Transfer** - RTCDataChannel with 16KB chunking (tested up to 700MB)
- ✅ **WebRTC Detection** - automatic detection of browser capabilities
- ✅ **Fallback UX** - user-friendly warnings when WebRTC blocked
- ✅ **Real-time Progress** - transfer progress monitoring for sender/receiver
- ✅ **E2E Encryption** - DTLS encryption (native WebRTC)
- ✅ **Auto Download** - automatic file download on receiver side

**Landing Page:**
- ✅ **Homepage** - professional landing page with hero section, features showcase, and CTAs
- ✅ **Public Access** - accessible to non-logged users with links to register/login
- ✅ **Responsive Design** - mobile-friendly with gradient backgrounds

**Backend & Infrastructure:**
- ✅ **PostgreSQL Database** - 7 tables with relations (Prisma ORM)
- ✅ **RESTful API** - Express.js backend with validation
- ✅ **WebSocket** - Socket.IO for real-time communication
- ✅ **Docker Compose** - full orchestration (nginx, frontend, backend, PostgreSQL)
- ✅ **Test Coverage** - comprehensive test suite for WebRTC, Auth, Events, Matches
- ✅ **WebRTC Tests** - full Socket.IO signaling and detection tests (7 tests passing)

### 🔜 Next Up

- ⏳ **Competition Heats** - complete UI integration and real-time updates
- ⏳ **PWA Features** - manifest, service worker, offline support
- ⏳ **Security Hardening** - CORS, CSRF, Helmet.js, CSP

## 🛠️ Tech Stack

### Frontend
- **React 18** - UI framework
- **Vite** - build tool and dev server
- **Tailwind CSS v3.4.0** - styling
- **React Router** - routing
- **Lucide React** - icons
- **Context API** - state management (auth)
- **Socket.IO Client** - real-time WebSocket communication
- **WebRTC** - P2P file transfer (RTCPeerConnection, RTCDataChannel)

### Backend
- **Node.js 20** - runtime
- **Express 4.18** - web framework
- **PostgreSQL 15** - relational database
- **Prisma ORM 5.22** - type-safe database client
- **Socket.IO 4.8** - WebSocket server
- **bcrypt** - password hashing
- **JWT** - token-based authentication
- **AWS SES** - email service
- **Jest + Supertest** - testing (81%+ coverage)

### Infrastructure
- **Docker Compose** - container orchestration (dev + prod profiles)
- **Nginx** - reverse proxy & static file serving
- **Alpine Linux** - lightweight container base images

## 📁 Project Structure

```
spotlightcam/
├── docker-compose.yml          # Container orchestration (dev + prod profiles)
├── nginx/                      # Nginx reverse proxy config
│   ├── nginx.conf
│   └── conf.d/default.conf    # Proxy /api & /socket.io to backend
├── frontend/                   # React PWA
│   ├── src/
│   │   ├── components/        # React components
│   │   │   ├── common/        # Shared components, PasswordStrength, VerificationBanner
│   │   │   ├── chat/          # Chat components
│   │   │   ├── video/         # WebRTC components (WebRTCWarning)
│   │   │   ├── layout/        # Navbar, Layout
│   │   │   └── __tests__/     # Component tests (WebRTCWarning)
│   │   ├── pages/             # Application pages
│   │   │   ├── HomePage.jsx             # Landing page with hero & features
│   │   │   ├── LoginPage.jsx
│   │   │   ├── RegisterPage.jsx         # Two-step registration with WSDC lookup
│   │   │   ├── VerifyEmailPage.jsx      # Email verification (link + PIN)
│   │   │   ├── ForgotPasswordPage.jsx   # Request password reset
│   │   │   ├── ResetPasswordPage.jsx    # Reset password with token
│   │   │   ├── ProfilePage.jsx          # Edit profile (social media, location)
│   │   │   ├── PublicProfilePage.jsx    # View other user's profile
│   │   │   ├── EventsPage.jsx           # Event list with real API
│   │   │   ├── EventChatPage.jsx        # Real-time event chat
│   │   │   ├── MatchChatPage.jsx        # Private chat + WebRTC P2P transfer
│   │   │   ├── RatePartnerPage.jsx      # Rate partner after collaboration
│   │   │   └── HistoryPage.jsx          # Match history
│   │   ├── hooks/             # Custom hooks (useWebRTC)
│   │   ├── utils/             # Utilities (webrtcDetection)
│   │   │   └── __tests__/     # Utility tests (webrtcDetection)
│   │   ├── contexts/          # AuthContext (JWT integration)
│   │   ├── services/          # API client, Socket.IO client
│   │   ├── data/              # Static data (countries list)
│   │   └── mocks/             # Mock data (for UI development)
│   ├── Dockerfile             # Development container
│   ├── Dockerfile.prod        # Production build
│   └── package.json
├── backend/                    # Node.js + Express API
│   ├── src/
│   │   ├── controllers/       # Auth, users, events, WSDC
│   │   ├── middleware/        # Auth, validation, error handling
│   │   ├── routes/            # API routes
│   │   ├── socket/            # Socket.IO server (event/match rooms, WebRTC signaling)
│   │   ├── utils/             # Auth utils, DB, email service (AWS SES)
│   │   └── __tests__/         # Jest unit tests
│   │   │   ├── socket-webrtc.test.js  # WebRTC signaling tests (7 tests)
│   │   │   ├── auth.test.js           # Authentication tests
│   │   │   ├── events.test.js         # Events API tests
│   │   │   ├── matches.test.js        # Matches API tests
│   │   │   └── ...                    # Other test suites
│   ├── prisma/
│   │   ├── schema.prisma      # Database schema (7 tables)
│   │   ├── migrations/        # Database migrations
│   │   └── seed.js            # Seed data
│   ├── Dockerfile             # Development container
│   ├── Dockerfile.prod        # Production build
│   └── package.json
└── docs/                       # Documentation
    ├── SESSION_CONTEXT.md     # Quick session context (minimal tokens)
    ├── CONTEXT.md             # Full project description
    ├── TODO.md                # Task list & roadmap
    ├── ARCHITECTURE.md        # Technical details
    ├── COMPLETED.md           # Completed tasks archive
    ├── PHASE_1.5.md           # Phase 1.5 documentation
    ├── SECURITY_AUDIT.md      # Security audit & fixes
    ├── DEPLOYMENT.md          # Deployment guide
    └── RESOURCES.md           # Learning resources
```

## 🚀 Getting Started

### Requirements
- Docker and Docker Compose
- (Optional) Node.js 20+ for development without Docker

### Development Mode

1. Clone the repository:
```bash
git clone <repo-url>
cd spotlightcam
```

2. Copy example .env file:
```bash
cp backend/.env.example backend/.env
```

3. Start Docker Compose with dev profile:
```bash
docker compose --profile dev up
```

4. Open browser:
```
http://localhost:8080
```

### Production Mode

```bash
docker compose --profile prod up -d
```

### Service Access

**Development:**
- Frontend: http://localhost:8080
- Backend API: http://localhost:8080/api
- WebSocket: ws://localhost:8080/socket.io
- Health check: http://localhost:8080/api/health
- PostgreSQL: localhost:5432 (exposed for dev tools)

**Production:**
- Application: http://localhost (port 80)
- HTTPS: https://localhost (port 443, requires SSL certificates)
- PostgreSQL: internal only (not exposed)

### Stopping Services

```bash
# Development
docker compose --profile dev down

# Production
docker compose --profile prod down
```

### Rebuild After Changes

```bash
docker compose --profile dev down
docker compose --profile dev up --build
```

## 🗄️ Database Schema

7 tables with relations (Prisma ORM):

1. **users** - users
   - Base: id, username, email, password_hash, avatar, created_at, updated_at
   - WSDC: first_name, last_name, wsdc_id
   - Email: email_verified, verification_token, verification_code, verification_token_expiry
   - Password Reset: reset_token, reset_token_expiry
   - Social: youtube_url, instagram_url, facebook_url, tiktok_url
   - Location: country, city

2. **events** - dance events
   - id, slug (unique), name, location, start_date, end_date, description, worldsdc_id, participants_count

3. **event_participants** - event participants (many-to-many)
   - id, user_id, event_id, joined_at

4. **chat_rooms** - chat rooms
   - id, event_id, type (event/private), created_at

5. **messages** - messages
   - id, room_id, user_id, content, type (text/link/video), created_at

6. **matches** - user pairs
   - id, slug (unique cuid), user1_id, user2_id, event_id, room_id, status (pending/accepted/completed), created_at

7. **ratings** - ratings
   - id, match_id, rater_id, rated_id, score (1-5), comment, would_collaborate_again, created_at
   - Unique constraint: (match_id, rater_id, rated_id) - prevents duplicate ratings

### Migrations

```bash
# Development (inside backend container)
docker compose exec backend npx prisma migrate dev

# Production
docker compose exec backend-prod npx prisma migrate deploy

# Generate Prisma Client
docker compose exec backend npx prisma generate
```

### Seed Data

```bash
docker compose exec backend npx prisma db seed
```

Adds:
- 3 events (Warsaw, Barcelona, Herräng)
- 2 users (john_doe, jane_smith)
- Event chat rooms

## 🧪 Testing the Application

### Test Flow:

1. **Landing Page** (http://localhost:8080/)
   - View professional landing page with hero section
   - Explore features showcase and how-it-works section
   - Click "Get Started" to register or "Sign in" to login

2. **Registration with WSDC** (http://localhost:8080/register)
   - Optional: provide WSDC ID (e.g., 12345) for auto-fill
   - Complete registration form
   - You'll receive verification email (check AWS SES sandbox)

3. **Email Verification** (http://localhost:8080/verify-email)
   - Click link from email OR enter 6-digit PIN code
   - Email will be verified

4. **Login** (http://localhost:8080/login)
   - Email: john@example.com
   - Password: password123

5. **Profile Editing** (http://localhost:8080/profile)
   - Add social media links (Instagram, YouTube, etc.)
   - Select country from list of 195 countries
   - Enter city
   - Edit WSDC ID, first name, last name

6. **Event Selection** (http://localhost:8080/events)
   - View event list (joined events appear at top)
   - Select event (e.g., "Warsaw Dance Festival 2025")
   - Click "Join chat" or "Open chat" (if already joined)

7. **Event Chat**
   - Real-time chat with Socket.IO
   - Active users list on the right side
   - Click "+" icon next to user to connect
   - You'll be redirected to private 1:1 chat

8. **1:1 Chat - WebRTC P2P File Transfer** 🔥
   - See partner's profile at top (click username to view public profile)
   - WebRTC connection status (disconnected/connecting/connected)
   - **Sending video via WebRTC:**
     - Click "Send video (WebRTC)"
     - Select video file from disk
     - Real P2P transfer via RTCDataChannel with STUN servers for NAT traversal
     - Supports files up to 700MB+ tested successfully
     - See real-time progress bar (16KB chunking)
     - Receiver automatically downloads the file
     - End-to-end encryption via DTLS (native WebRTC)
   - **WebRTC Detection:**
     - Automatic detection if WebRTC is blocked
     - User-friendly warning with fix suggestions
     - Button disabled when WebRTC unavailable
   - **Fallback - link sharing:**
     - Click "Link"
     - Paste video URL (Google Drive, Dropbox, etc.)
     - Alternative when WebRTC blocked (Opera, VPNs, privacy settings)

9. **Rate Partner**
   - Click "Finish and rate"
   - Select rating (1-5 stars)
   - Add comment
   - Mark if you want to collaborate again

10. **Collaboration History** (http://localhost:8080/history)
    - See list of matches
    - See received ratings
    - See statistics

11. **Public Profiles**
    - Click on another user's username
    - View profile: avatar, location, social media, statistics

## 🧰 Admin CLI

Use an in-container admin console for quick maintenance.

- Start REPL (default): `docker compose exec backend npm run cli`
- Explicit REPL: `docker compose exec backend npm run cli -- repl`
- 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 (calendar/list) dry-run: `docker compose exec backend npm run cli -- events:import:wsdc --dry-run --since 2024-01-01 --until 2024-12-31`
- Import with location from list: `docker compose exec backend npm run cli -- events:import:wsdc --source list --limit 50`
- Enrich missing location: `docker compose exec backend npm run cli -- events:import:wsdc --source list --update-missing-location`
- Event details by slug: `docker compose exec backend npm run cli -- events:details --slug warsaw-dance-2025 [--participants 25]`
- Event participants: `docker compose exec backend npm run cli -- events:participants --slug warsaw-dance-2025 --limit 100`
- Event participants CSV: `docker compose exec backend npm run cli -- events:participants --slug warsaw-dance-2025 --limit 200 --csv > participants.csv`
- List matches: `docker compose exec backend npm run cli -- matches:list --limit 20 [--status accepted|pending|completed]`
- Check-in user to event (simulate QR): `docker compose exec backend npm run cli -- events:checkin --username john_doe --slug warsaw-dance-2025`
- App logs (if LOG_FILE configured): `docker compose exec backend npm run cli -- logs:app --lines 200`
- Recent chat messages: `docker compose exec backend npm run cli -- logs:messages --limit 50`

Production equivalents use `backend-prod` instead of `backend`.

REPL specifics:
- Inside REPL use `run('users:list --limit 20')` or `.cli users:list --limit 20`.
- Top-level await works for Prisma: `await prisma.user.findMany({ take: 5 })`.
- CLI errors in REPL do not exit the session; the error is printed so you can correct and retry.

## 🔐 Security

### Implemented Security Features:

✅ **Authentication:**
- bcrypt password hashing (10 salt rounds)
- JWT tokens (httpOnly cookies in production)
- Protected routes with auth middleware
- Email verification required

✅ **Input Validation:**
- express-validator for all inputs
- Custom validators for URLs (domain checking)
- SQL injection prevention (Prisma parameterized queries)
- XSS protection (input sanitization)

✅ **Rate Limiting:**
- Login attempts: 5 per 15 minutes
- Registration: 3 per hour
- Email sending: 3 per hour

✅ **Database:**
- Unique constraints on emails, usernames
- Indexed fields for performance
- Cascading deletes for data integrity

✅ **Event Security:**
- Unique alphanumeric slugs (12 chars, MD5-based)
- Prevents ID enumeration attacks
- URLs: /events/{slug}/chat instead of /events/{id}/chat

✅ **Socket.IO:**
- JWT authentication for WebSocket connections
- Room-based access control
- User verification before joining rooms

### Planned Security Features (Phase 3):

⏳ CORS configuration
⏳ CSRF protection (cookies)
⏳ Helmet.js security headers
⏳ Content Security Policy
⏳ HTTPS enforcement (production)

## 📊 Test Coverage

**Backend: ~43% overall coverage** (116 tests passing)
- **WebRTC Signaling**: 7/7 tests passing (offer/answer/ICE relay, authorization)
- **Auth Controllers**: 82.9% coverage
- **Events API**: Comprehensive tests
- **Matches API**: Full CRUD tests
- **Socket.IO**: 42.4% coverage (WebRTC + chat)

**Frontend: Test files ready** (requires test runner setup)
- WebRTC detection utility tests
- WebRTC warning component tests

**Coverage gaps** (priority areas):
- Routes: events.js (8.98%), matches.js (8.22%), users.js (43%)
- Controllers: user.js (8.19%)
- Utils: sanitize.js (31.81%)

```bash
# Run all backend tests
docker compose exec backend npm test

# Run specific test suite
docker compose exec backend npm test -- socket-webrtc.test.js

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

## 🎯 Roadmap

### ✅ Phase 0: Frontend Mockup (COMPLETED)
- All views with mock data
- WebRTC UI mockup
- Routing & navigation

### ✅ Phase 1: Backend Foundation (COMPLETED)
- Node.js + Express + PostgreSQL
- JWT authentication
- Socket.IO real-time chat
- Test coverage 81%+

### ✅ Phase 1.5: Email & WSDC Integration (COMPLETED)
- Email verification (AWS SES)
- Password reset workflow
- WSDC API integration
- User profiles with social media & location
- Public profiles
- Event participation tracking
- Event security (slugs)

### ✅ Phase 2: Matches & Ratings API (COMPLETED)
- Matches API (create/accept match requests with slugs)
- Real-time match notifications via Socket.IO
- Ratings API (1-5 stars, comments, collaboration preferences)
- Public profile ratings display
- Profile links from chat and matches pages
- Message history for matches
- Duplicate rating prevention

### ✅ Phase 2.5: WebRTC P2P File Transfer (COMPLETED)
- WebRTC signaling (SDP/ICE exchange via Socket.IO)
- P2P file transfer via RTCDataChannel (16KB chunking)
- STUN servers for NAT traversal (production-ready)
- WebRTC capability detection (browser/network compatibility)
- User-friendly fallback UX when WebRTC blocked
- Tested up to 700MB file transfers
- E2E encryption (DTLS)
- Comprehensive test suite (7 backend tests passing)
- Professional landing page with hero section

### ⏳ Phase 3: MVP Finalization (IN PROGRESS)
- ✅ Landing page (completed)
- ✅ WebRTC tests (completed)
- ⏳ Security hardening (CORS, CSRF, Helmet.js, CSP)
- ⏳ Integration & E2E tests
- ⏳ PWA features (manifest, service worker)
- ⏳ Production deployment
- ⏳ Monitoring & logging

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

## 📖 Documentation

**Quick Start:**
- `docs/SESSION_CONTEXT.md` - Quick context for resuming sessions (minimal tokens)

**Main Documentation:**
- `docs/CONTEXT.md` - Main project description and assumptions
- `docs/TODO.md` - Active tasks and roadmap

**Detailed Documentation:**
- `docs/ARCHITECTURE.md` - Technical details and implementation
- `docs/PHASE_1.5.md` - Phase 1.5 documentation (Email & WSDC)
- `docs/SECURITY_AUDIT.md` - Security audit & fixes
- `docs/DEPLOYMENT.md` - Deployment guide
- `docs/ADMIN_CLI.md` - Admin CLI & REPL usage
- `docs/COMPLETED.md` - Completed tasks archive
- `docs/RESOURCES.md` - Links to documentation and learning resources

## 🤝 Contributing

Project is in development phase. Currently implementing Phase 2 (Matches & Ratings API, WebRTC P2P transfer).

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

**Note:** Commit messages without mentions of AI/automatic generation.

## 📄 License

TBD

---

**Current Status:** Phase 2.5 (WebRTC) ✅ Completed | Phase 3 (MVP) ⏳ In Progress | Progress: ~80% overall

**Last Updated:** 2025-11-15