radziel/spotlightcam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
61f504fa72c674cfa31d26897123db2f9824da1d
spotlightcam/docs/SESSION_CONTEXT.md
Radosław Gierwiało 61f504fa72 docs: update documentation for QR code check-in system
2025-11-14 14:43:33 +01:00

377 lines
14 KiB
Markdown
Raw Blame History

# Session Context - spotlight.cam
**Quick reference for resuming development sessions - optimized for minimal token usage**
---
## 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:** 1.5 (Email Verification & WSDC Integration + User Profiles + Security) - ✅ COMPLETED
**Progress:** ~65%
**Next Goal:** Phase 2 - Core Features (Matches API, Ratings, WebRTC signaling)
### What Works Now
- ✅ Docker Compose (nginx:8080 + frontend + backend + PostgreSQL)
- ✅ All frontend views with real API integration
- ✅ Backend API (Node.js + Express)
- ✅ PostgreSQL database with 8 tables (Prisma ORM)
- ✅ Real authentication (JWT + bcrypt)
- ✅ **Email verification (AWS SES with link + PIN code) - Phase 1.5**
- ✅ **Password reset workflow - Phase 1.5**
- ✅ **WSDC ID integration for auto-fill registration - Phase 1.5**
- ✅ **User profiles with social media & location - Phase 1.5**
- ✅ **Public profiles (/{username}) - Phase 1.5**
- ✅ **Event participation tracking - Phase 1.5**
- ✅ **Event security (unique slugs, no ID enumeration) - Phase 1.5**
- ✅ **QR code event check-in system - Phase 1.5** (requires physical presence at venue)
- ✅ Real-time chat (Socket.IO for event & match rooms)
- ✅ WebRTC P2P transfer UI mockup
### What's Missing
- ⏳ Matches API (create/accept/list matches)
- ⏳ Ratings API (rate partner after collaboration)
- ⏳ WebRTC signaling (SDP/ICE exchange via Socket.IO)
- ⏳ Actual WebRTC P2P file transfer implementation
---
## Tech Stack
**Infrastructure:**
- Docker Compose (nginx, frontend, backend, PostgreSQL db)
- nginx reverse proxy on port 8080 (API + WebSocket)
**Frontend:**
- React 18 + Vite
- Tailwind CSS v3.4.0 (NOT v4 - compatibility issues)
- React Router
- Context API for state
- socket.io-client for real-time chat
**Backend:**
- Node.js 20 + Express 4.18.2
- Socket.IO 4.8.1 for WebSocket (real-time chat)
- PostgreSQL 15 with Prisma ORM 5.8.0
- bcrypt + JWT authentication
- Jest + supertest for testing (81%+ coverage)
**WebRTC:**
- RTCPeerConnection
- RTCDataChannel (file transfer)
- Chunking (16KB chunks)
- STUN/TURN servers
---
## Project Structure
```
/spotlightcam
├── docker-compose.yml # nginx + frontend + backend + PostgreSQL
├── nginx/ # Proxy config (API + WebSocket)
├── frontend/ # React PWA
│ ├── src/
│ │ ├── pages/ # All views (Login, Register, Events, Chat, Match, Rate, History)
│ │ ├── contexts/ # AuthContext (JWT integration)
│ │ ├── components/ # Layout, Navbar
│ │ ├── services/ # API client, Socket.IO client
│ │ └── mocks/ # Mock data (events, users for UI)
├── backend/ # Node.js + Express API
│ ├── src/
│ │ ├── controllers/ # Auth, users, events
│ │ ├── middleware/ # Authentication middleware
│ │ ├── routes/ # API routes
│ │ ├── socket/ # Socket.IO server
│ │ ├── utils/ # Auth utils, DB connection
│ │ └── __tests__/ # Jest unit tests
│ └── prisma/ # Database schema, migrations, seed
└── docs/
├── SESSION_CONTEXT.md # This file
├── CONTEXT.md # Full project description
├── TODO.md # Task list
├── ARCHITECTURE.md # Technical details
├── COMPLETED.md # Completed tasks archive
└── RESOURCES.md # Learning resources
```
---
## Key Files
**Frontend:**
- `frontend/src/pages/RegisterPage.jsx` - Two-step registration (WSDC lookup + form)
- `frontend/src/pages/VerifyEmailPage.jsx` - Email verification (link + code)
- `frontend/src/pages/ForgotPasswordPage.jsx` - Request password reset
- `frontend/src/pages/ResetPasswordPage.jsx` - Reset password with token
- `frontend/src/pages/ProfilePage.jsx` - **UPDATED: Edit profile (social media, location) - Phase 1.5**
- `frontend/src/pages/PublicProfilePage.jsx` - **NEW: View other user profiles - Phase 1.5**
- `frontend/src/pages/EventsPage.jsx` - **UPDATED: Shows check-in requirement, dev-only QR access - Phase 1.5**
- `frontend/src/pages/EventChatPage.jsx` - **UPDATED: Access control with check-in verification, Leave Event - Phase 1.5**
- `frontend/src/pages/EventDetailsPage.jsx` - **NEW: QR code display, participant list - Phase 1.5**
- `frontend/src/pages/EventCheckinPage.jsx` - **NEW: Check-in confirmation page - Phase 1.5**
- `frontend/src/pages/MatchChatPage.jsx` - Private chat + WebRTC mockup
- `frontend/src/components/common/PasswordStrengthIndicator.jsx` - Password strength indicator
- `frontend/src/components/common/VerificationBanner.jsx` - Email verification banner
- `frontend/src/contexts/AuthContext.jsx` - JWT authentication integration
- `frontend/src/services/api.js` - **UPDATED: QR check-in methods (checkin, getDetails, leave) - Phase 1.5**
- `frontend/src/services/socket.js` - Socket.IO client connection manager
- `frontend/src/data/countries.js` - **NEW: List of 195 countries - Phase 1.5**
**Backend:**
- `backend/src/controllers/auth.js` - Register, login, email verification, password reset
- `backend/src/controllers/user.js` - **UPDATED: Profile updates (social, location) - Phase 1.5**
- `backend/src/controllers/wsdc.js` - WSDC API proxy for dancer lookup
- `backend/src/routes/events.js` - **UPDATED: QR check-in endpoints (checkin, details, leave), participant verification - Phase 1.5**
- `backend/src/routes/users.js` - **UPDATED: Public profile endpoint - Phase 1.5**
- `backend/src/socket/index.js` - **UPDATED: Participant verification before room join, security fix - Phase 1.5**
- `backend/src/utils/email.js` - AWS SES email service with HTML templates
- `backend/src/utils/auth.js` - Token generation utilities
- `backend/src/middleware/auth.js` - Email verification middleware
- `backend/src/middleware/validators.js` - **UPDATED: Social media URL validation - Phase 1.5**
- `backend/src/server.js` - Express server with Socket.IO integration
- `backend/prisma/schema.prisma` - **UPDATED: 8 tables (EventCheckinToken added) - Phase 1.5**
- `backend/prisma/migrations/20251113151534_add_wsdc_and_email_verification/` - Phase 1.5 migration
- `backend/prisma/migrations/20251113202500_add_event_slug/` - **NEW: Event slugs migration - Phase 1.5**
- `backend/prisma/migrations/20251114125544_add_event_checkin_tokens/` - **NEW: QR check-in tokens - Phase 1.5**
**Config:**
- `docker-compose.yml` - nginx, frontend, backend, PostgreSQL
- `nginx/conf.d/default.conf` - Proxy for /api and /socket.io
- `backend/.env` - **UPDATED: AWS SES credentials, email settings - Phase 1.5**
---
## Database Schema (Implemented - Prisma)
8 tables with relations:
- `users` - **EXTENDED in Phase 1.5:**
- Base: id, username, email, password_hash, avatar, created_at, updated_at
- **WSDC:** first_name, last_name, wsdc_id
- **Email Verification:** email_verified, verification_token, verification_code, verification_token_expiry
- **Password Reset:** reset_token, reset_token_expiry
- **Social Media:** youtube_url, instagram_url, facebook_url, tiktok_url
- **Location:** country, city
- `events` - id, **slug (unique)**, name, location, start_date, end_date, description, worldsdc_id, participants_count
- `event_participants` - **NEW in Phase 1.5:** id, user_id, event_id, joined_at (many-to-many)
- `event_checkin_tokens` - **NEW in Phase 1.5:** id, event_id (unique), token (cuid, unique), created_at
- `chat_rooms` - id, event_id, match_id, type (event/private), created_at
- `messages` - id, room_id, user_id, content, type, created_at
- `matches` - id, user1_id, user2_id, event_id, room_id, status, created_at
- `ratings` - id, match_id, rater_id, rated_id, score, comment, would_collaborate_again, created_at
**Migrations:**
- `20251112205214_init` - Initial schema
- `20251113151534_add_wsdc_and_email_verification` - Phase 1.5 (email, WSDC, social, location)
- `20251113202500_add_event_slug` - **Phase 1.5 (event security - unique slugs)**
- `20251114125544_add_event_checkin_tokens` - **Phase 1.5 (QR code check-in system)**
**Seed data:** 3 events, 2 users, event chat rooms
---
## User Flow
1. Register/Login
2. Choose event (from worldsdc.com list)
3. Event chat - matchmaking
4. Match confirmation → private 1:1 chat
5. **Select video from gallery** (recorded outside app)
6. **WebRTC P2P transfer** (direct, no server storage) OR link sharing fallback
7. Rate partner (1-5 stars, comment)
---
## Development Guidelines
### Code Language
- **All code, strings, UI text, comments:** ENGLISH
- **Variable/function names:** ENGLISH
- **Communication with developer:** POLISH
### Git Commits
- Standard format, NO mentions of AI/automatic generation
- ✅ Good: `feat: add WebRTC P2P video transfer`
- ❌ Bad: `feat: add video transfer (generated by AI)`
### Important Decisions
- Port 8080 (port 80 was occupied)
- Tailwind CSS v3.4.0 (v4 has breaking changes with Vite)
- Mock authentication uses localStorage
- All UI text in English
---
## Next Steps (Phase 2 - Core Features)
**Priority:** HIGH
**Estimated Time:** 12-15 hours
### Step 1: Matches API (3-4h)
- `POST /api/matches` - Create match request
- `POST /api/matches/:id/accept` - Accept match
- `GET /api/matches` - List user's matches
- Frontend integration (match request flow)
- Tests
### Step 2: Ratings API (2-3h)
- `POST /api/ratings` - Submit rating after collaboration
- `GET /api/users/:id/ratings` - Get user's ratings
- Frontend integration (rating form)
- Tests
### Step 3: WebRTC Signaling (3-4h)
- Socket.IO events for SDP/ICE exchange
- Signaling flow (offer/answer/ice-candidate)
- Frontend WebRTC setup (RTCPeerConnection)
- Connection establishment tests
### Step 4: WebRTC File Transfer (4-5h)
- RTCDataChannel setup
- File chunking (16KB chunks)
- Progress monitoring (sender & receiver)
- Error handling & reconnection
- Complete P2P video transfer flow
---
## Common Commands
**Start project:**
```bash
docker compose up --build
```
**Access:**
- Frontend: http://localhost:8080
- Backend API: http://localhost:8080/api
- Socket.IO: ws://localhost:8080/socket.io
- Health check: http://localhost:8080/api/health
**Rebuild after changes:**
```bash
docker compose down
docker compose up --build
```
**Git:**
```bash
git status
git add .
git commit -m "feat: description"
```
---
## Known Issues & Solutions
### Issue: Tailwind v4 compatibility error
**Solution:** Downgraded to Tailwind v3.4.0
```bash
npm install -D tailwindcss@^3.4.0
```
### Issue: Port 80 already allocated
**Solution:** Changed nginx port to 8080 in docker-compose.yml
### Issue: Prisma OpenSSL error in Alpine Linux
**Solution:** Added OpenSSL to Dockerfile
```dockerfile
RUN apk add --no-cache openssl
```
---
## WebRTC Implementation Notes (Future)
**Main functionality - P2P file transfer:**
- RTCPeerConnection for connection establishment
- RTCDataChannel for binary data transfer
- File chunking (16KB chunks recommended)
- Progress monitoring (both sender and receiver)
- Metadata exchange (filename, size, MIME type)
- Error handling and reconnection logic
- Fallback: link sharing (Google Drive, Dropbox)
**Signaling:**
- WebSocket (Socket.IO) for SDP/ICE exchange
- Server only for signaling, NOT for file storage
**Security:**
- WebRTC native encryption (DTLS/SRTP)
- Optional: additional chat encryption (WebCrypto API)
---
## Quick Reference - Frontend Routes
- `/login` - Login page
- `/register` - Two-step registration (WSDC lookup + form)
- `/verify-email` - Email verification (link + PIN code)
- `/forgot-password` - Request password reset
- `/reset-password/:token` - Reset password with token
- `/profile` - Edit user profile (social media, location)
- `/:username` - Public profile view
- `/events` - Event list (joined events first, check-in requirement notice)
- `/events/:slug/chat` - Event chat (requires check-in, real-time Socket.IO)
- `/events/:slug/details` - **NEW:** Event details with QR code, participant list
- `/events/checkin/:token` - **NEW:** QR code check-in confirmation page
- `/matches/:id/chat` - Private 1:1 chat + WebRTC mockup
- `/matches/:id/rate` - Rate partner
- `/history` - Match history
---
## Quick Reference - Mock Data
**Mock User (logged in):**
- ID: 1
- Username: john_doe
- Email: john@example.com
**Mock Events:**
- ID: 1 - Warsaw Dance Festival 2025
- ID: 2 - Swing Camp Barcelona 2025
- ID: 3 - Blues Week Herräng 2025
---
## Files to Read for Full Context
**Minimal (for quick start):**
- `docs/SESSION_CONTEXT.md` (this file)
- `docker-compose.yml`
- `frontend/src/pages/MatchChatPage.jsx` (WebRTC mockup)
**Full context:**
- `docs/CONTEXT.md` (project description)
- `docs/TODO.md` (task list)
- `docs/ARCHITECTURE.md` (technical details)
**Archives:**
- `docs/COMPLETED.md` (completed tasks)
- `docs/RESOURCES.md` (learning resources)
---
**Last Updated:** 2025-11-14
**Phase 1 Status:** ✅ COMPLETED - Backend Foundation (Express + PostgreSQL + JWT + Socket.IO)
**Phase 1.5 Status:** ✅ COMPLETED - Email Verification & WSDC Integration & User Profiles & Security
- AWS SES email verification (link + PIN)
- Password reset workflow
- WSDC API integration
- User profiles (social media, location)
- Public profiles (/{username})
- Event participation tracking
- Event security (unique slugs, no ID enumeration)
- **QR code event check-in system** (physical presence required, dev mode bypass)
**Next Phase:** Phase 2 - Core Features (Matches API + Ratings + WebRTC)
Reference in New Issue View Git Blame Copy Permalink