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 (223/223 tests passing)

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

// ✅ 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/COMPLETED.md - Archiwum ukończonych zadań
• docs/RESOURCES.md - Linki do dokumentacji i zasobów edukacyjnych

---

Last Updated: 2025-11-20

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