# 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:** 0 (Frontend Mockup) - ✅ COMPLETED
**Progress:** ~25%
**Next Goal:** Phase 1 - Backend Foundation (Node.js + PostgreSQL + Auth + WebSocket)

### What Works Now
- ✅ Docker Compose (nginx:8080 + frontend)
- ✅ All frontend views with mockups
- ✅ Mock authentication (localStorage)
- ✅ WebRTC P2P transfer UI mockup

### What's Missing
- ⏳ Backend API (Node.js + Express)
- ⏳ PostgreSQL database + schema
- ⏳ Real authentication (JWT)
- ⏳ Real-time chat (Socket.IO)
- ⏳ Actual WebRTC implementation

---

## Tech Stack

**Infrastructure:**
- Docker Compose (nginx, frontend, backend planned, db planned)
- nginx reverse proxy on port 8080

**Frontend:**
- React 18 + Vite
- Tailwind CSS v3.4.0 (NOT v4 - compatibility issues)
- React Router
- Context API for state

**Backend (planned):**
- Node.js + Express
- Socket.IO for WebSocket
- PostgreSQL 15
- bcrypt + JWT

**WebRTC:**
- RTCPeerConnection
- RTCDataChannel (file transfer)
- Chunking (16KB chunks)
- STUN/TURN servers

---

## Project Structure

```
/spotlightcam
├── docker-compose.yml          # nginx + frontend (backend + db planned)
├── nginx/                      # Proxy config
├── frontend/                   # React PWA
│   ├── src/
│   │   ├── pages/             # All views (Login, Register, Events, Chat, Match, Rate, History)
│   │   ├── contexts/          # AuthContext (mock)
│   │   ├── components/        # Layout, Navbar
│   │   └── mocks/             # Mock data (users, events, messages, matches)
├── backend/                    # NOT CREATED YET
└── 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/MatchChatPage.jsx` - Main WebRTC mockup (file select, transfer progress)
- `frontend/src/contexts/AuthContext.jsx` - Mock auth with localStorage
- `frontend/src/mocks/` - All mock data

**Config:**
- `docker-compose.yml` - nginx on 8080, frontend on 5173 (internal)
- `nginx/conf.d/default.conf` - Proxy config, WebSocket support for Vite HMR
- `frontend/tailwind.config.js` - Tailwind v3.4.0 config

---

## Database Schema (Planned)

6 tables:
- `users` - id, username, email, password_hash, created_at
- `events` - id, name, location, start_date, end_date, worldsdc_id
- `chat_rooms` - id, event_id, type (event/private)
- `messages` - id, room_id, user_id, content, type
- `matches` - id, user1_id, user2_id, event_id, status, room_id
- `ratings` - id, match_id, rater_id, rated_id, score, comment

---

## 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 1 - Backend Foundation)

**Priority:** HIGH
**Estimated Time:** 11-14 hours

### Step 1: Backend Setup (1-2h)
- Add `backend` container to docker-compose.yml
- Initialize Node.js + Express
- Basic folder structure
- Healthcheck endpoint: `GET /api/health`
- Update nginx to proxy `/api/*` to backend

### Step 2: PostgreSQL Setup (2-3h)
- Add `db` container (PostgreSQL 15)
- Configure volumes
- Choose migration tool (Prisma/Knex/node-pg-migrate)
- Create 6 tables schema
- Seed test data

### Step 3: Authentication API (3-4h)
- bcrypt for password hashing
- JWT token generation
- Endpoints: `POST /api/auth/register`, `POST /api/auth/login`
- Auth middleware
- Connect frontend to real API

### Step 4: WebSocket Chat (4-5h)
- Socket.IO setup
- Event room management
- Broadcast messages
- Active users list
- Connect frontend to Socket.IO

---

## Common Commands

**Start project:**
```bash
docker compose up --build
```

**Access:**
- Frontend: http://localhost:8080
- Backend (planned): http://localhost:8080/api

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

---

## 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` - Registration page
- `/events` - Event list
- `/events/:id/chat` - Event chat (public)
- `/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-12
**Session Started:** Frontend Mockup completed, ready for Backend Foundation