spotlightcam/docs/CONTEXT.md

# spotlight.cam

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.

Stworzyć aplikację umożliwiającą peer-to-peer przesyłanie nagrań wideo między użytkownikami, nawet gdy znajdują się na różnych platformach (Android/iOS), z szyfrowaniem end-to-end, minimalnym udziałem backendu i opcjonalnym czatem tekstowym.

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

🧱 ETAPY WDROŻENIA
1. 🔍 Analiza technologii i wymagań

 Zidentyfikuj ograniczenia platform: Android, iOS (szczególnie iOS WebView vs Safari).

 Sprawdź kompatybilność WebRTC na poziomie przeglądarki (getUserMedia, RTCPeerConnection, RTCDataChannel).

 Określ typy danych do przesyłania: pliki wideo (MP4), wiadomości tekstowe, metadane.

 Zdecyduj, czy to aplikacja webowa (PWA) czy natywna (Flutter/React Native).

 Oszacuj maksymalny rozmiar plików i czas transferu.
 
2. 🧠 Projekt architektury systemu
🔗 Połączenie WebRTC

 Użyj RTCPeerConnection + RTCDataChannel do przesyłania wideo.

 Zaimplementuj STUN i opcjonalnie TURN (np. Google STUN, własny TURN przy złych NAT-ach).

☁️ Serwer sygnalizacyjny (Signaling)

 Stwórz prosty backend (np. Node.js + Express + WebSocket) do wymiany SDP/ICE.

 Alternatywnie: pozwól użytkownikom przekazywać dane ręcznie (przez QR/link/komunikator).

📤 Przesyłanie danych

 Skorzystaj z RTCDataChannel do przesyłania plików binarnych (Blob/FileReader).

 Podziel pliki na fragmenty (chunking), monitoruj postęp.

3. 🔐 Bezpieczeństwo i prywatność
🔒 Szyfrowanie

 Potwierdź, że WebRTC już szyfruje (DTLS/SRTP).

 Zaszyfruj czat tekstowy: np. z użyciem libsodium, Signal Protocol lub WebCrypto.

 Nie przechowuj żadnych plików na serwerze — tylko wymiana sygnalizacyjna.
 
🔄 Wymiana danych sygnalizacyjnych

 Dodaj 2 tryby:

QR code + ręczne skanowanie

Link generowany przez jedną stronę i wklejany przez drugą

Kodowanie

 Zserializuj offer (SDP) do JSON → Base64 → QR/link.

 Po stronie odbiorcy: parsuj i odpowiadaj answer przez podobny kanał.

6. 🧪 UX i potwierdzenia

 Pokaż komunikaty typu:

„Czekam na połączenie…”

„Połączenie nawiązane z użytkownikiem”

„Trwa przesyłanie: 87%”

 Po zakończeniu przesyłania: „Plik otrzymany”, przycisk „Zapisz”.
 
## 🧠 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).
- 💬 Czat + matchmaking: użytkownicy rejestrują się, wybierają event, trafiają na czat eventowy, łączą się w pary.
- 🤝 1:1: po potwierdzeniu – para znika z czatu publicznego i przechodzi do prywatnego.
- 📦 Docker Compose: całość uruchamiana w kontenerach.
- 📱 Frontend: PWA – działa mobilnie i na desktopie.

## 🧱 Architektura systemu

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

## 🐳 Docker Compose – komponenty

Zestaw trzech kontenerów:
- `frontend`: PWA (React/Vite/Tailwind)
- `backend`: Node.js/Express/Socket.IO
- `db`: PostgreSQL 15

## 🗃️ Modele bazy danych

- `users`: identyfikacja, event, dostępność
- `events`: lista eventów z worldsdc.com
- `chat_rooms`: publiczne i prywatne pokoje
- `messages`: wiadomości tekstowe/linki
- `matches`: relacja między dwoma użytkownikami
- `ratings`: oceny po wymianie nagraniami

## 🔁 Flow użytkownika

1. Rejestracja użytkownika
2. Wybór eventu (lista z worldsdc.com) na którym użytkownik jest.
3. Czat ogólny dla eventu – matchmaking.
4. Potwierdzenie: przejście do prywatnego czatu 1:1.
5. **Wybór pliku wideo z galerii urządzenia** (nagranie odbywa się poza aplikacją).
6. **Przesłanie filmu bezpośrednio przez WebRTC** (peer-to-peer, bez serwera). Opcjonalnie: wymiana linków (np. Google Drive).
7. Po wymianie nagraniami – ocena partnera (1–5, komentarz, chęć ponownej współpracy).

## 💬 Frontend (PWA)

Zbudowany np. w:
- React + Vite + Tailwind
- lub SvelteKit / SolidStart

Widoki:
- Logowanie / Rejestracja
- Wybór eventu
- Czat eventowy
- Profil partnera
- Czat 1:1
- Ocena partnera
- Historia współprac

## 🔐 Bezpieczeństwo

- Hasła haszowane (bcrypt).
- **WebRTC zapewnia natywne szyfrowanie** (DTLS/SRTP) dla transferu P2P.
- **Opcjonalne dodatkowe szyfrowanie czatu** tekstowego (WebCrypto/libsodium).
- Brak przechowywania nagrań na serwerze – tylko sygnalizacja WebRTC.
- Możliwość zgłaszania użytkownika.

## 📹 WebRTC P2P Transfer Filmów (główna funkcjonalność)

### Komponenty:
- **RTCPeerConnection**: nawiązanie połączenia P2P między użytkownikami
- **RTCDataChannel**: kanał do transferu danych binarnych (pliki wideo)
- **Chunking**: podział dużych plików wideo na fragmenty (np. 16KB chunks)
- **Progress monitoring**: śledzenie postępu wysyłania/odbierania (pasek postępu)
- **STUN/TURN**: serwery do przejścia przez NAT/firewall

### Flow transferu:
1. Użytkownik wybiera plik wideo z galerii urządzenia (`<input type="file">`)
2. Nawiązanie połączenia WebRTC między parą użytkowników (przez serwer sygnalizacyjny WebSocket)
3. Otwarcie RTCDataChannel
4. Wysłanie metadanych: nazwa pliku, rozmiar, typ MIME
5. Podział pliku na chunki i przesłanie przez DataChannel
6. Odbieranie chunków i składanie w całość (Blob)
7. Po zakończeniu: zapis pliku w pamięci urządzenia odbiorcy

### Fallback:
- Jeśli WebRTC nie zadziała (problemy z NAT, firewall), użytkownik może wymienić się linkami do filmów (Google Drive, Dropbox, itp.)

## ➕ Opcjonalne rozszerzenia

- System oznaczeń zaufania (badge).
- Blokowanie użytkowników.
- Publiczne profile z opiniami.
- Powiadomienia push.

---

## 📝 Zasady rozwoju projektu (Development Guidelines)

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

### Komunikacja
- **Komunikacja z zespołem/developerem**: **polski**
- **Dokumentacja projektowa (CONTEXT.md, README.md)**: **polski** (może być mieszana z angielskim dla części technicznych)

### Git commits
- **Commit messages**: standardowy format bez wzmianek o AI/automatycznym generowaniu kodu
- Przykład dobrego commita: `feat: add WebRTC P2P video transfer mockup`
- Przykład złego commita: ~~`feat: add video transfer (generated by AI)`~~
- Commituj zmiany logicznie (feature by feature, bugfix by bugfix)

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

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