radziel/spotlightcam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: streamline README and update SESSION_CONTEXT, archive outdated docs

Browse Source 
- 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
This commit is contained in:
Radosław Gierwiało
2025-11-30 20:17:27 +01:00
parent 9af4447e1d
commit 913d685721
5 changed files with 370 additions and 567 deletions
Download Patch File Download Diff File Expand all files Collapse all files

829
README.md
View File

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

108
docs/SESSION_CONTEXT.md
View File

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

0
docs/CONTEXT.md → docs/archive/CONTEXT.md
View File

0
docs/QUICKSTART.md → docs/archive/QUICKSTART.md
View File

0
docs/QUICK_TEST.md → docs/archive/QUICK_TEST.md
View File