spotlightcam/docs/CONTEXT.md

# spotlight.cam - Project Context

**Peer-to-peer video exchange app for dance event participants**

---

## 📝 Quick Description

Aplikacja umożliwiająca użytkownikom łączenie się w pary, czatowanie, **przesyłanie filmów bezpośrednio peer-to-peer przez WebRTC** i ocenianie współpracy – bez przechowywania danych na serwerze.

Główna funkcjonalność: **WebRTC P2P video file transfer** (nie wymiana linków - to tylko fallback).

✅ Pełne wsparcie dla Android/iOS (przez przeglądarkę), bez hostowania plików, z backendem i frontendem działającym w ramach Docker Compose.

---

## 🧠 Główne założenia

- 🔒 **Prywatność:** Przesyłanie filmów bezpośrednio peer-to-peer przez WebRTC – żadnych plików wideo na serwerze. Opcjonalnie możliwość wymiany linków (np. Google Drive) jako fallback.
- 💬 **Czat + matchmaking:** Użytkownicy rejestrują się, wybierają event, trafiają na czat eventowy, łączą się w pary.
- 🤝 **1:1 collaboration:** Po potwierdzeniu – para znika z czatu publicznego i przechodzi do prywatnego.
- 📦 **Docker Compose:** Całość uruchamiana w kontenerach.
- 📱 **PWA:** Działa mobilnie i na desktopie.

---

## 🧱 Architektura systemu

```
Web client (PWA) ↔ Backend (Node.js + WebSocket + REST API) ↔ PostgreSQL

WebRTC P2P Connection:
Browser A ←──────────────────────→ Browser B
          (Direct file transfer)
```

---

## 🐳 Docker Compose – komponenty

**Current (All Implemented):**
- `nginx`: Reverse proxy (port 8080)
- `frontend`: React/Vite/Tailwind PWA (port 5173 internal)
- `backend`: Node.js/Express/Socket.IO (port 3000 internal)
- `db`: PostgreSQL 15 with Prisma ORM

---

## 🗃️ Modele bazy danych (Implemented)

- `users`: identyfikacja, email, hasło (bcrypt), avatar, profile data
- `events`: lista eventów (z worldsdc.com + manual entries)
- `divisions`: competition divisions (Novice, Intermediate, Advanced, etc.)
- `competition_types`: Jack & Jill, Strictly
- `event_user_heats`: declared competition heats per user per event
- `chat_rooms`: publiczne (event) i prywatne (match) pokoje
- `messages`: wiadomości tekstowe/linki (persisted)
- `matches`: relacja między dwoma użytkownikami (CUID slugs for security)
- `ratings`: oceny po wymianie nagraniami (1-5, komentarz, collaboration preference)
- `event_participants`: tracking event participation
- `event_checkin_tokens`: QR code check-in system

---

## 🔁 Flow użytkownika

1. **Rejestracja/Logowanie** użytkownika
2. **Wybór eventu** (lista z worldsdc.com) na którym użytkownik jest
3. **Czat eventowy** – matchmaking (lista aktywnych użytkowników)
4. **Potwierdzenie matcha** → przejście do prywatnego czatu 1:1
5. **Wybór pliku wideo z galerii** (nagranie odbywa się poza aplikacją)
6. **Przesłanie filmu przez WebRTC** (P2P, bez serwera) LUB wymiana linków (fallback)
7. **Ocena partnera** (1–5 ⭐, komentarz, chęć ponownej współpracy)

---

## 💬 Tech Stack

### Frontend
- React 18 + Vite
- Tailwind CSS v3.4.0 (NOT v4)
- React Router
- Context API for state
- PWA (vite-plugin-pwa, Workbox service worker)
- socket.io-client for real-time

### Backend
- Node.js 20 + Express 4.18.2
- Socket.IO 4.8.1 (WebSocket)
- PostgreSQL 15 with Prisma ORM 5.8.0
- bcrypt + JWT authentication
- Jest + Supertest (286/286 tests passing, 73% coverage)

### WebRTC
- RTCPeerConnection (implemented)
- RTCDataChannel (file transfer)
- 16KB chunking (tested up to 700MB)
- STUN servers for NAT traversal
- E2E encryption (DTLS)

---

## 🔐 Bezpieczeństwo

**Backend:**
- Hasła haszowane (bcrypt)
- JWT authentication
- Rate limiting, CORS, Helmet.js
- Input validation & sanitization

**Frontend:**
- XSS prevention
- Secure token storage
- HTTPS required

**WebRTC:**
- Natywne szyfrowanie (DTLS/SRTP)
- Brak przechowywania nagrań na serwerze
- Opcjonalne dodatkowe szyfrowanie czatu

---

## 📝 Zasady rozwoju projektu (Development Guidelines)

### Język w kodzie
- **Wszystkie stringi, komunikaty, UI text, komentarze w kodzie**: **ENGLISH**
- **Nazwy zmiennych, funkcji, klas**: **ENGLISH**
- **Dokumentacja techniczna w kodzie (JSDoc, docstrings)**: **ENGLISH**

### Komunikacja
- **Komunikacja z zespołem/developerem**: **POLISH**
- **Dokumentacja projektowa (CONTEXT.md, README.md)**: **POLISH** (może być mieszana z angielskim)

### Git commits
- **Commit messages**: standardowy format BEZ wzmianek o AI/automatycznym generowaniu kodu
- ✅ Przykład dobry: `feat: add WebRTC P2P video transfer`
- ❌ Przykład zły: ~~`feat: add video transfer (generated by AI)`~~
- Commituj zmiany logicznie (feature by feature, bugfix by bugfix)

### Przykład kodu
```jsx
// ✅ Poprawnie - kod po angielsku
const sendMessage = (message) => {
  if (!message.trim()) {
    alert('Please enter a message');
    return;
  }
  socket.emit('message', message);
};

// ❌ Niepoprawnie - kod po polsku
const wyslijWiadomosc = (wiadomosc) => {
  if (!wiadomosc.trim()) {
    alert('Proszę wpisać wiadomość');
    return;
  }
  socket.emit('wiadomosc', wiadomosc);
};
```

---

## 📚 Dodatkowe dokumenty

**For quick context (minimal tokens):**
- `docs/SESSION_CONTEXT.md` - Ultra-zwięzły kontekst dla nowych sesji (~300-500 linii)

**For full details:**
- `docs/ARCHITECTURE.md` - Szczegóły techniczne, implementacja, WebRTC flow
- `docs/TODO.md` - Lista zadań i roadmap
- `docs/DEPLOYMENT.md` - Production deployment guide
- `docs/MONITORING.md` - Monitoring and operations
- `docs/archive/COMPLETED.md` - Archiwum ukończonych zadań
- `docs/archive/RESOURCES.md` - Linki do dokumentacji i zasobów edukacyjnych

---

**Last Updated:** 2025-11-23

**Status:** ✅ MVP Complete - All core features implemented and tested