From 913d685721c8883aa2e510e5158b775d5c4a2121 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rados=C5=82aw=20Gierwia=C5=82o?= <github@radziel.com>
Date: Sun, 30 Nov 2025 20:17:27 +0100
Subject: [PATCH] docs: streamline README and update SESSION_CONTEXT, archive
 outdated docs

- Streamline README.md from 645 to 365 lines (43% reduction)
- Remove duplicate content with other documentation files
- Focus README on quick start, features overview, and links to detailed docs
- Update SESSION_CONTEXT.md with recent changes (342/342 tests, matching runs audit)
- Archive outdated documentation:
  - CONTEXT.md (duplicated in README)
  - QUICKSTART.md (mentions mock auth, outdated)
  - QUICK_TEST.md (outdated)
- Keep SESSION_CONTEXT.md active for context restoration
---
 README.md                        | 829 ++++++++++---------------------
 docs/SESSION_CONTEXT.md          | 108 +++-
 docs/{ => archive}/CONTEXT.md    |   0
 docs/{ => archive}/QUICKSTART.md |   0
 docs/{ => archive}/QUICK_TEST.md |   0
 5 files changed, 370 insertions(+), 567 deletions(-)
 rename docs/{ => archive}/CONTEXT.md (100%)
 rename docs/{ => archive}/QUICKSTART.md (100%)
 rename docs/{ => archive}/QUICK_TEST.md (100%)

diff --git a/README.md b/README.md
index 7241bdd..80ba7a4 100644
--- a/README.md
+++ b/README.md
@@ -1,130 +1,178 @@
 # spotlight.cam 🎥
 
-Web application (PWA) for the dance community enabling matchmaking, chat, and video file exchange directly via WebRTC (peer-to-peer).
+**P2P video exchange app for the dance community** - matchmaking, chat, and WebRTC file transfer directly between users.
 
-## 🚀 Features
+---
 
-### ✅ Implemented
+## 🎯 What is this?
 
-**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
+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)
 
-**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 with flags) and city
-- ✅ **Public Profiles** - visible to other logged-in users at /@{username}
-- ✅ **Profile Statistics** - number of matches, average rating, number of reviews
-- ✅ **Clickable Usernames** - usernames in chat are clickable links to public profiles
+**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+.
 
-**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 with country flags
-- ✅ **Active Users Sidebar** - list of online users in the event
-- ✅ **Message History** - message persistence in database
-- ✅ **Infinite Scroll** - loading older messages
-- ✅ **Competitor Numbers** - bib number display in event chat
+---
 
-**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
+## ✅ Core Features
 
-**Ratings & Stats System:**
-- ✅ **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
-- ✅ **Stats Updates** - atomic recording stats updates (recordingsDone, recordingsReceived)
-- ✅ **Source Filtering** - only auto-matches update fairness stats (manual matches excluded)
-- ✅ **Race Condition Prevention** - statsApplied flag with atomic check-and-set
-- ✅ **Idempotency** - double-rating prevention ensures stats update exactly once
+### 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
 
-**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
+### 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
 
-**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
+### 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)
 
-**Backend & Infrastructure:**
-- ✅ **PostgreSQL Database** - 11 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)
+### Matchmaking & Private Chat
+- Manual match requests with real-time notifications
+- Private 1:1 chat for matched users
+- Match slugs (CUID) preventing ID enumeration
 
-**Dashboard & Real-time:**
-- ✅ **Dashboard** - centralized landing page with active events, matches, requests
-- ✅ **Online Count** - real-time users in event chat
-- ✅ **Unread Count** - unread message badges per match
-- ✅ **Mobile-first Design** - responsive chat layout with page titles on mobile
+### 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
 
-**Auto-matching & Account Tiers:**
-- ✅ **Smart Recording Matching** - auto-assign recorders for competition heats with collision detection
-- ✅ **3-Tier Account System** - BASIC (free), SUPPORTER, COMFORT tiers with fairness-based assignment
-- ✅ **Fairness Algorithm** - karma tracking (recordingsDone vs recordingsReceived) for balanced workload
-- ✅ **Dual Buffer System** - prep time before and rest time after dancing (no buffer for recording)
-- ✅ **Tier Penalties** - SUPPORTER (-10 fairness), COMFORT (-50 fairness) for reduced recording frequency
-- ✅ **Event-specific Upgrades** - accountTierOverride for temporary tier boosts (e.g., Comfort Pass)
-- ✅ **Multi-criteria Sorting** - Location > Fairness > Load balancing priority
-- ✅ **Competitor Numbers** - bib number support for events
-- ✅ **Matching Runs Audit** - complete audit trail with origin_run_id tracking
-- ✅ **Incremental Matching** - preserves accepted/completed suggestions across re-runs
-- ✅ **Scheduler Integration** - automated matching with cron-based scheduling
-- ✅ **Admin Endpoints** - per-run statistics and suggestion filtering
+### 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
 
-**Security & PWA (All Implemented):**
-- ✅ **Security Hardening** - CORS, CSRF, Helmet.js, account lockout, rate limiting
-- ✅ **PWA Features** - manifest, service worker, offline support, iOS compatible
+### 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)
 
-### 🔜 Future Extensions
-- ⏳ **User Badges** - trust system and reputation badges
-- ⏳ **Push Notifications** - real-time alerts for matches and messages
-- ⏳ **Video Compression** - client-side compression before transfer
+### PWA & Infrastructure
+- Progressive Web App (offline support, iOS compatible)
+- Docker Compose orchestration (nginx, frontend, backend, PostgreSQL)
+- PostgreSQL 15 with Prisma ORM (11 tables)
+- Admin CLI with REPL for operations
+
+---
 
 ## 🛠️ 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)
+**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 ✅)
 
-### 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 (342 tests, 72.5% coverage, 100% passing)
+---
 
-### Infrastructure
-- **Docker Compose** - container orchestration (dev + prod profiles)
-- **Nginx** - reverse proxy & static file serving
-- **Alpine Linux** - lightweight container base images
+## 🚀 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
 
@@ -132,506 +180,180 @@ Web application (PWA) for the dance community enabling matchmaking, chat, and vi
 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)
+│   │   ├── contexts/          # AuthContext
 │   │   ├── services/          # API client, Socket.IO client
-│   │   ├── data/              # Static data (countries list)
-│   │   └── mocks/             # Mock data (for UI development)
+│   │   └── constants/         # Status constants
 │   ├── Dockerfile             # Development container
-│   ├── Dockerfile.prod        # Production build
-│   └── package.json
+│   └── Dockerfile.prod        # Production build
 ├── 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
+│   │   ├── routes/            # API routes (events, matches, admin)
+│   │   ├── services/          # Matching algorithm
+│   │   ├── socket/            # Socket.IO handlers (chat, WebRTC signaling)
+│   │   └── __tests__/         # Jest tests (342 tests)
 │   ├── prisma/
-│   │   ├── schema.prisma      # Database schema (7 tables)
-│   │   ├── migrations/        # Database migrations
-│   │   └── seed.js            # Seed data
+│   │   ├── schema.prisma      # Database schema (11 tables)
+│   │   └── migrations/        # Database migrations
 │   ├── Dockerfile             # Development container
-│   ├── Dockerfile.prod        # Production build
-│   └── package.json
+│   └── Dockerfile.prod        # Production build
 └── docs/                       # Documentation
-    ├── SESSION_CONTEXT.md     # Quick session context (minimal tokens)
-    ├── CONTEXT.md             # Full project description
-    ├── TODO.md                # Task list & roadmap
-    ├── ARCHITECTURE.md        # Technical details
-    ├── DEPLOYMENT.md          # Deployment guide
-    ├── MONITORING.md          # Monitoring & operations
-    ├── QUICKSTART.md          # Quick start guide
-    ├── QUICK_TEST.md          # Quick test instructions
-    ├── WEBRTC_TESTING_GUIDE.md # WebRTC testing guide
+    ├── 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
-        ├── COMPLETED.md       # Completed tasks archive
-        ├── PHASE_1.5.md       # Phase 1.5 documentation
-        ├── SECURITY_AUDIT.md  # Security audit & fixes
-        ├── RESOURCES.md       # Learning resources
-        └── ADMIN_CLI.md       # Admin CLI documentation
 ```
 
-## 🚀 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
 
 11 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
-   - Account Tiers: account_tier (BASIC/SUPPORTER/COMFORT), recordings_done, recordings_received
+**Core Tables:**
+- `users` - Authentication, profile, social links, location, account tiers
+- `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
 
-2. **events** - dance events
-   - id, slug (unique), name, location, start_date, end_date, description, worldsdc_id, participants_count
+**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)
 
-3. **event_participants** - event participants (many-to-many)
-   - id, user_id, event_id, joined_at, recorder_opt_out, competitor_number
-   - account_tier_override (optional event-specific tier upgrade)
+**Other:**
+- `event_checkin_tokens` - QR code check-in
 
-4. **chat_rooms** - chat rooms
-   - id, event_id, type (event/private), created_at
+See `docs/ARCHITECTURE.md` for detailed schema documentation.
 
-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
-
-8. **event_checkin_tokens** - QR code tokens for event access
-   - id, event_id, token (cuid), created_at
-
-9. **divisions** - competition divisions (Newcomer, Novice, Intermediate, etc.)
-   - id, name, abbreviation, display_order
-
-10. **competition_types** - competition types (Jack & Jill, Strictly, etc.)
-    - id, name, abbreviation
-
-11. **event_user_heats** - user's declared heats for matchmaking
-    - id, user_id, event_id, division_id, competition_type_id, heat_number (1-9), role (Leader/Follower), created_at, updated_at
-    - Unique constraint: (user_id, event_id, division_id, competition_type_id, role)
-
-### 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
-
-### Additional Security (Phase 3 - Implemented):
-
-✅ CORS configuration
-✅ CSRF protection (cookies)
-✅ Helmet.js security headers
-✅ Account lockout (after failed attempts)
-✅ Content Security Policy
-⏳ HTTPS enforcement (requires production SSL setup)
-
-## 📊 Test Coverage
-
-**Backend: 72.5% overall coverage** (342/342 tests passing - 100% ✅)
-- **Matching Algorithm**: 19/19 integration tests passing
-  - Phase 1: Fundamentals (TC1-3) - basic flow, NOT_FOUND scenarios
-  - Phase 2: Collision Detection (TC4-9) - buffers, slot mapping, schedule conflicts
-  - Phase 3: Limits & Workload (TC10-11) - MAX_RECORDINGS, recording-recording collisions
-  - Phase 4: Fairness & Tiers (TC12-16) - debt calculation, tier penalties
-  - Phase 5: Edge Cases (TC17-19) - multiple heats, incremental matching
-- **Ratings & Stats Flow**: 9/9 E2E tests passing
-  - Double-rating completion flow
-  - Atomic stats updates (recordingsDone, recordingsReceived)
-  - Race condition prevention (statsApplied flag)
-  - Manual vs auto match differentiation
-  - Idempotency testing
-- **Matching Runs Audit**: 6/6 tests passing
-  - origin_run_id assignment and tracking
-  - Sequential runs with separate IDs
-  - Accepted suggestions preservation
-  - Filter parameters (onlyAssigned, includeNotFound)
-  - Manual vs scheduler trigger differentiation
-- **Incremental Matching**: 5/5 tests passing
-- **Recording Stats Integration**: 6/6 tests passing
-- **WebRTC Signaling**: 12/12 tests passing (offer/answer/ICE relay, authorization)
-- **Auth Controllers**: Comprehensive coverage
-- **Events API**: Full test suite
-- **Matches API**: Full CRUD tests
-- **Dashboard API**: 12 tests passing
-- **Socket.IO**: Full WebRTC + chat coverage (12/12 passing)
-- **Test Isolation**: Fixed with unique test data per suite
-- **Code Coverage Highlights**:
-  - matching.js: 94.71% statements, 91.5% branches
-  - routes/matches.js: 76.11% statements
-  - routes/events.js: 78.2% statements
-
-**Frontend: Test files ready** (requires test runner setup)
-- WebRTC detection utility tests
-- WebRTC warning component tests
+Quick operations via REPL or command mode:
 
 ```bash
-# Run all backend tests
-docker compose exec backend npm test
+# Start REPL
+docker compose exec backend npm run cli
 
-# Run specific test suite
-docker compose exec backend npm test -- socket-webrtc.test.js
+# List users
+docker compose exec backend npm run cli -- users:list --limit 20
 
-# Coverage report
-docker compose exec backend npm run test:coverage
+# 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
 ```
 
-## 🎯 Roadmap
+**REPL mode:** Top-level await works for Prisma queries, e.g., `await prisma.user.findMany({ take: 5 })`
 
-### ✅ 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%+
+## 🔐 Security Features
 
-### ✅ 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)
+**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
 
-### ✅ 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 (COMPLETED)
-- ✅ Landing page
-- ✅ Dashboard with online/unread counts
-- ✅ Recording matching system (auto-assign recorders)
-- ✅ Security hardening (CSRF, account lockout, rate limiting)
-- ✅ PWA features (manifest, service worker, iOS support)
-- ✅ All backend tests passing (286/286 - 100%)
-- ✅ Production operations scripts (backup, restore, health check)
-- ✅ Documentation cleanup and reorganization
-
-### ⏳ 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)
+**For quick start:**
+- `docs/SESSION_CONTEXT.md` - Quick context for resuming sessions (recommended for AI assistants)
 
-**Main Documentation:**
-- `docs/CONTEXT.md` - Main project description and assumptions
-- `docs/TODO.md` - Active tasks and roadmap
-- `docs/ARCHITECTURE.md` - Technical details and implementation
-- `docs/DEPLOYMENT.md` - Deployment and production setup guide
-- `docs/MONITORING.md` - Monitoring and operations guide
+**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
 
-**Quick Guides:**
-- `docs/QUICKSTART.md` - Quick start guide (2 minutes)
-- `docs/QUICK_TEST.md` - Quick testing instructions
-- `docs/WEBRTC_TESTING_GUIDE.md` - WebRTC testing guide
+**Testing guides:**
+- `docs/WEBRTC_TESTING_GUIDE.md` - WebRTC P2P testing
 
-**Archived Documentation:**
-- `docs/archive/PHASE_1.5.md` - Phase 1.5 documentation (Email & WSDC)
+**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
-- `docs/archive/ADMIN_CLI.md` - Admin CLI & REPL usage
-- `docs/archive/COMPLETED.md` - Completed tasks archive
-- `docs/archive/RESOURCES.md` - Links to documentation and learning resources
+
+---
+
+## 🎯 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)
+
+### ⏳ Future Extensions (Phase 4)
+- User badges & trust system
+- Push notifications
+- Video compression
+- Multi-file transfer
+- Block users
+
+---
 
 ## 🤝 Contributing
 
-Project is in development phase. Currently implementing Phase 2 (Matches & Ratings API, WebRTC P2P transfer).
+**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:
+**Git workflow:**
 ```bash
 git status
 git add .
 git commit -m "feat: description"
 ```
 
-**Note:** Commit messages without mentions of AI/automatic generation.
+---
 
 ## 📄 License
 
@@ -639,6 +361,5 @@ TBD
 
 ---
 
-**Current Status:** MVP Complete ✅ | 285/286 tests passing (99.7%) | Ready for Production Deployment
-
-**Last Updated:** 2025-11-29
+**Status:** MVP Complete ✅ | 342/342 tests passing (100%) | Production Ready
+**Last Updated:** 2025-11-30
diff --git a/docs/SESSION_CONTEXT.md b/docs/SESSION_CONTEXT.md
index 559ffda..a045345 100644
--- a/docs/SESSION_CONTEXT.md
+++ b/docs/SESSION_CONTEXT.md
@@ -15,9 +15,9 @@
 
 ## 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)
+**Phase:** MVP Complete - Production Ready
+**Tests:** 342/342 backend tests passing - 100% ✅ (72.5% coverage)
+**Recent Work:** Matching runs audit, ratings & stats system, comprehensive test suite
 
 ### Core Features (All Implemented)
 - JWT authentication with email verification (AWS SES)
@@ -27,6 +27,10 @@
 - 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 with @ prefix, country flags
 - Matches & ratings API
 - QR code event check-in
@@ -49,16 +53,26 @@
 │   ├── hooks/               # useWebRTC.js
 │   └── constants/           # MATCH_STATUS, SUGGESTION_STATUS, etc.
 ├── backend/src/
-│   ├── routes/              # API endpoints
+│   ├── routes/              # API endpoints (events.js, matches.js, admin.js)
 │   ├── controllers/         # Business logic
 │   ├── services/            # matching.js (auto-matching algorithm)
 │   ├── socket/              # Socket.IO handlers
 │   ├── constants/           # Status constants
-│   └── __tests__/           # Jest tests
+│   └── __tests__/           # Jest tests (342 tests - 100% passing)
+│       ├── matching-algorithm.test.js      # 19 tests
+│       ├── ratings-stats-flow.test.js      # 9 tests
+│       ├── matching-runs-audit.test.js     # 6 tests
+│       ├── matching-incremental.test.js    # 5 tests
+│       └── socket.test.js                  # 12 tests
 └── docs/
-    ├── TODO.md              # Current tasks & security audit
+    ├── SESSION_CONTEXT.md   # This file - quick context
+    ├── TODO.md              # Current tasks & roadmap
     ├── ARCHITECTURE.md      # Technical details
-    └── archive/COMPLETED.md # Historical reference
+    ├── DEPLOYMENT.md        # Deployment guide
+    ├── MONITORING.md        # Operations guide
+    ├── TESTING_MATCHING_RATINGS.md  # Comprehensive test documentation (45 tests)
+    ├── WEBRTC_TESTING_GUIDE.md      # WebRTC testing guide
+    └── archive/             # Archived documentation
 ```
 
 ---
@@ -72,21 +86,58 @@ Key models:
 - `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
+- `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
 
 ---
 
+## Recent Changes (Last 2 Days)
+
+### Matching Runs Audit System
+- **File:** `backend/src/__tests__/matching-runs-audit.test.js` (6 tests)
+- **Features:**
+  - origin_run_id assignment and tracking
+  - Sequential runs create separate audit records
+  - Accepted suggestions preserve origin_run_id across re-runs
+  - Admin endpoints with filtering (onlyAssigned, includeNotFound)
+  - Manual vs scheduler trigger differentiation
+
+### Ratings & Stats Integration
+- **File:** `backend/src/__tests__/ratings-stats-flow.test.js` (9 tests)
+- **Features:**
+  - Atomic stats updates (recordingsDone, recordingsReceived)
+  - Race condition prevention with `statsApplied` flag
+  - Source filtering (only auto matches update stats)
+  - Idempotency (double-rating prevention)
+  - E2E double-rating completion flow
+
+### Documentation
+- **Updated:** README.md with current test statistics (342/342)
+- **New:** docs/TESTING_MATCHING_RATINGS.md (comprehensive 45-test overview)
+- **Archived:** Outdated quick start guides
+
+---
+
 ## Quick Commands
 
 ```bash
 # Start development
-docker compose up --build
+docker compose --profile dev up
 
-# Run backend tests
+# Run all backend tests
 docker compose exec backend npm test
 
+# Run specific test suite
+docker compose exec backend npm test -- matching-runs-audit.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
+
 # Access
 # Frontend: http://localhost:8080
 # API: http://localhost:8080/api
@@ -117,6 +168,11 @@ 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
 ```
 
 ---
@@ -131,12 +187,38 @@ FAIRNESS_COMFORT_PENALTY: 50
 
 ---
 
+## 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` - Security audit, future improvements
+- `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-11-29
+**Last Updated:** 2025-11-30
diff --git a/docs/CONTEXT.md b/docs/archive/CONTEXT.md
similarity index 100%
rename from docs/CONTEXT.md
rename to docs/archive/CONTEXT.md
diff --git a/docs/QUICKSTART.md b/docs/archive/QUICKSTART.md
similarity index 100%
rename from docs/QUICKSTART.md
rename to docs/archive/QUICKSTART.md
diff --git a/docs/QUICK_TEST.md b/docs/archive/QUICK_TEST.md
similarity index 100%
rename from docs/QUICK_TEST.md
rename to docs/archive/QUICK_TEST.md