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 - Ready for Production Deployment
**Tests:** 285/286 backend tests passing - 99.7% (73% coverage)
**Next Goal:** Infrastructure setup (server, domain, SSL)

### 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)
- 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
│   ├── controllers/         # Business logic
│   ├── services/            # matching.js (auto-matching algorithm)
│   ├── socket/              # Socket.IO handlers
│   ├── constants/           # Status constants
│   └── __tests__/           # Jest tests
└── docs/
    ├── TODO.md              # Current tasks & security audit
    ├── ARCHITECTURE.md      # Technical details
    └── archive/COMPLETED.md # Historical reference
```

---

## 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
- `recording_suggestions` - Auto-matching results with collision detection
- `chat_rooms` / `messages` - Real-time chat persistence

---

## Quick Commands

```bash
# Start development
docker compose up --build

# Run backend tests
docker compose exec backend npm test

# 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
```

---

## Test Accounts (Seeded)

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

---

## For More Details

- `docs/TODO.md` - Security audit, future improvements
- `docs/ARCHITECTURE.md` - Technical implementation details
- `docs/archive/COMPLETED.md` - Full history of completed features

---

**Last Updated:** 2025-11-29