spotlightcam/docs/TODO.md

# TODO - spotlight.cam

Lista zadań do realizacji projektu spotlight.cam - aplikacji do matchmaking i wymiany nagrań wideo na eventach tanecznych.

## 📋 Status realizacji
- ⏳ Do zrobienia
- 🔄 W trakcie
- ✅ Zrobione

---

## 🎯 AKTUALNY STATUS PROJEKTU

### ✅ Ukończone (Faza 0: Frontend Mockup)
- Frontend mockup z pełną funkcjonalnością UI
- Docker Compose setup (nginx + frontend)
- Dokumentacja projektu
- **Gotowe do prezentacji i testowania UX**

### 🔄 W trakcie
- Przygotowanie do backend development

### ⏳ Następne kroki
**Priorytet:** Backend setup → Database → API → WebSocket

---

## 📌 SUGEROWANE KOLEJNE KROKI

### 🚀 Krok 1: Backend Foundation (zalecane TERAZ)
Cel: Uruchomić backend Node.js z podstawowym API

**Co zrobić:**
1. Dodaj kontener `backend` do docker-compose.yml
2. Zainicjalizuj projekt Node.js + Express
3. Skonfiguruj strukturę folderów backend
4. Dodaj podstawowy endpoint healthcheck (`GET /api/health`)
5. Zaktualizuj nginx config aby proxy'ował `/api/*` do backendu

**Czas realizacji:** 1-2 godziny
**Benefit:** Podstawa dla dalszego rozwoju API

---

### 🗄️ Krok 2: PostgreSQL Setup (po Kroku 1)
Cel: Uruchomić bazę danych i stworzyć schemat

**Co zrobić:**
1. Dodaj kontener `db` (PostgreSQL 15) do docker-compose.yml
2. Skonfiguruj volumes dla persystencji danych
3. Wybierz tool do migracji (Prisma / node-pg-migrate / Knex)
4. Stwórz schemat bazy (6 tabel: users, events, chat_rooms, messages, matches, ratings)
5. Dodaj seed data dla eventów testowych

**Czas realizacji:** 2-3 godziny
**Benefit:** Prawdziwe dane zamiast mocków

---

### 🔐 Krok 3: Authentication API (po Kroku 2)
Cel: Prawdziwa autentykacja JWT

**Co zrobić:**
1. Implementacja bcrypt do hashowania haseł
2. JWT token generation i verification
3. Endpointy: POST /api/auth/register, POST /api/auth/login
4. Middleware do weryfikacji tokena
5. Podłączenie frontendu do prawdziwego API

**Czas realizacji:** 3-4 godziny
**Benefit:** Koniec z mock auth, prawdziwe konta użytkowników

---

### 💬 Krok 4: WebSocket Chat (po Kroku 3)
Cel: Real-time czat eventowy

**Co zrobić:**
1. Setup Socket.IO na backendzie
2. Implementacja room management (event rooms)
3. Broadcast messages
4. Lista aktywnych użytkowników
5. Podłączenie frontendu do Socket.IO

**Czas realizacji:** 4-5 godzin
**Benefit:** Prawdziwy czat zamiast mocka

---

## 🐳 1. Setup projektu i infrastruktura

### Docker Compose
- [x] ✅ Utworzenie `docker-compose.yml` z serwisem nginx
- [x] ✅ Konfiguracja kontenera frontend (React/Vite)
- [ ] ⏳ Konfiguracja kontenera backend (Node.js)
- [ ] ⏳ Konfiguracja kontenera PostgreSQL 15
- [ ] ⏳ Konfiguracja volumes dla persystencji danych
- [x] ✅ Konfiguracja sieci między kontenerami

### Struktura projektu
- [x] ✅ Inicjalizacja projektu frontend (React + Vite + Tailwind)
- [x] ✅ Utworzenie `.gitignore`
- [x] ✅ Konfiguracja ESLint (frontend)
- [ ] ⏳ Inicjalizacja projektu backend (Node.js + Express)
- [ ] ⏳ Konfiguracja ESLint i Prettier (backend)
- [ ] ⏳ Konfiguracja TypeScript (opcjonalnie)
- [ ] ⏳ Utworzenie `.env` i `.env.example`

---

## 🗄️ 2. Baza danych PostgreSQL

### Schema i migracje
- [ ] ⏳ Setup narzędzia do migracji (np. node-pg-migrate, Knex, Prisma)
- [ ] ⏳ Utworzenie tabeli `users`
  - id, username, email, password_hash, created_at, updated_at
- [ ] ⏳ Utworzenie tabeli `events`
  - id, name, location, start_date, end_date, worldsdc_id
- [ ] ⏳ Utworzenie tabeli `chat_rooms`
  - id, event_id, type (event/private), created_at
- [ ] ⏳ Utworzenie tabeli `messages`
  - id, room_id, user_id, content, type (text/link), created_at
- [ ] ⏳ Utworzenie tabeli `matches`
  - id, user1_id, user2_id, event_id, status, room_id, created_at
- [ ] ⏳ Utworzenie tabeli `ratings`
  - id, match_id, rater_id, rated_id, score (1-5), comment, would_collaborate_again
- [ ] ⏳ Utworzenie indeksów dla optymalizacji zapytań
- [ ] ⏳ Seed danych testowych (events z worldsdc.com)

---

## 🔧 3. Backend - REST API

### Autentykacja i autoryzacja
- [ ] ⏳ Endpoint: `POST /api/auth/register` - rejestracja użytkownika
- [ ] ⏳ Endpoint: `POST /api/auth/login` - logowanie użytkownika
- [ ] ⏳ Endpoint: `POST /api/auth/logout` - wylogowanie
- [ ] ⏳ Implementacja bcrypt do hashowania haseł
- [ ] ⏳ Implementacja JWT/session dla autoryzacji
- [ ] ⏳ Middleware do weryfikacji tokena

### Users API
- [ ] ⏳ Endpoint: `GET /api/users/me` - pobranie profilu użytkownika
- [ ] ⏳ Endpoint: `PATCH /api/users/me` - aktualizacja profilu
- [ ] ⏳ Endpoint: `GET /api/users/:id` - pobranie profilu innego użytkownika

### Events API
- [ ] ⏳ Endpoint: `GET /api/events` - lista wszystkich eventów
- [ ] ⏳ Endpoint: `GET /api/events/:id` - szczegóły eventu
- [ ] ⏳ Endpoint: `POST /api/events/:id/join` - dołączenie do eventu
- [ ] ⏳ Integracja z worldsdc.com API (jeśli dostępne)

### Matches API
- [ ] ⏳ Endpoint: `GET /api/matches` - historia matchów użytkownika
- [ ] ⏳ Endpoint: `POST /api/matches` - utworzenie matcha
- [ ] ⏳ Endpoint: `PATCH /api/matches/:id` - aktualizacja statusu matcha

### Ratings API
- [ ] ⏳ Endpoint: `POST /api/ratings` - dodanie oceny partnera
- [ ] ⏳ Endpoint: `GET /api/ratings/user/:id` - oceny danego użytkownika
- [ ] ⏳ Endpoint: `GET /api/ratings/stats/:id` - statystyki użytkownika

### Reports API
- [ ] ⏳ Endpoint: `POST /api/reports` - zgłoszenie użytkownika

---

## 💬 4. Backend - WebSocket (Socket.IO)

### Czat eventowy (publiczny)
- [ ] ⏳ Setup Socket.IO na backendzie
- [ ] ⏳ Obsługa połączenia/rozłączenia użytkownika
- [ ] ⏳ Dołączenie użytkownika do pokoju eventowego
- [ ] ⏳ Wysyłanie wiadomości tekstowych do pokoju
- [ ] ⏳ Broadcast wiadomości do wszystkich w pokoju
- [ ] ⏳ Lista aktywnych użytkowników w pokoju

### Czat 1:1 (prywatny)
- [ ] ⏳ Utworzenie prywatnego pokoju dla pary
- [ ] ⏳ Wysyłanie wiadomości prywatnych
- [ ] ⏳ Powiadomienia o nowych wiadomościach

### WebRTC Signaling
- [ ] ⏳ Obsługa wymiany SDP offer/answer
- [ ] ⏳ Obsługa wymiany ICE candidates
- [ ] ⏳ Sygnalizacja statusu połączenia WebRTC
- [ ] ⏳ Error handling dla failed connections

---

## 🎥 5. WebRTC - Peer-to-Peer Transfer Filmów (GŁÓWNA FUNKCJONALNOŚĆ)

### Setup WebRTC
- [ ] ⏳ Konfiguracja STUN servers (Google STUN)
- [ ] ⏳ Konfiguracja TURN server (opcjonalnie, dla trudnych NAT)
- [ ] ⏳ Utworzenie RTCPeerConnection
- [ ] ⏳ Utworzenie RTCDataChannel dla transferu plików

### Nawiązanie połączenia
- [ ] ⏳ Inicjacja połączenia przez wysyłającego (createOffer)
- [ ] ⏳ Odpowiedź odbierającego (createAnswer)
- [ ] ⏳ Wymiana ICE candidates
- [ ] ⏳ Monitoring statusu połączenia (connecting, connected, failed)

### Transfer plików
- [ ] ⏳ Wybór pliku z galerii (`<input type="file" accept="video/*">`)
- [ ] ⏳ Walidacja pliku (typ, rozmiar max)
- [ ] ⏳ Wysłanie metadanych (nazwa, rozmiar, MIME type)
- [ ] ⏳ Implementacja chunkingu (podział na fragmenty 16KB)
- [ ] ⏳ Wysyłanie chunków przez DataChannel
- [ ] ⏳ Odbieranie chunków i składanie w Blob
- [ ] ⏳ Progress monitoring (pasek postępu % dla wysyłającego i odbierającego)
- [ ] ⏳ Obsługa błędów transferu
- [ ] ⏳ Możliwość anulowania transferu
- [ ] ⏳ Zapis pliku do pamięci urządzenia (download)

### Fallback - wymiana linków
- [x] ✅ UI do wklejenia linku do filmu (Google Drive, Dropbox, itp.)
- [x] ✅ Walidacja URL
- [x] ✅ Wysłanie linku przez czat (mockup)

### Optymalizacje
- [ ] ⏳ Dostosowanie rozmiaru chunka do bandwidth
- [ ] ⏳ Buffer management (kontrola przepełnienia bufora)
- [ ] ⏳ Reconnection logic przy utracie połączenia

---

## 🎨 6. Frontend - PWA (React + Vite + Tailwind)

### Setup PWA
- [x] ✅ Konfiguracja Vite
- [x] ✅ Konfiguracja Tailwind CSS
- [ ] ⏳ Konfiguracja Vite PWA plugin
- [ ] ⏳ Utworzenie `manifest.json`
- [ ] ⏳ Utworzenie service worker
- [ ] ⏳ Ikony aplikacji (różne rozmiary)
- [ ] ⏳ Splash screen

### Routing
- [x] ✅ Setup React Router
- [x] ✅ Ochrona tras (require authentication)

### Widoki/Komponenty
- [x] ✅ **Logowanie** (`/login`) - Formularz email + hasło, link do rejestracji
- [x] ✅ **Rejestracja** (`/register`) - Formularz username, email, hasło, walidacja
- [x] ✅ **Wybór eventu** (`/events`) - Lista eventów, wyszukiwanie, przycisk "Join chat"
- [x] ✅ **Czat eventowy** (`/events/:id/chat`) - Lista wiadomości, aktywni użytkownicy, matchmaking
- [x] ✅ **Czat 1:1** (`/matches/:id/chat`) - Profil partnera, czat, **mockup WebRTC transfer**
- [x] ✅ **Ocena partnera** (`/matches/:id/rate`) - Gwiazdki 1-5, komentarz, checkbox
- [x] ✅ **Historia współprac** (`/history`) - Lista matchów, oceny, statystyki

### Komponenty reużywalne
- [x] ✅ `<Navbar>` - nawigacja
- [x] ✅ `<Layout>` - wrapper dla stron
- [ ] ⏳ `<MessageBubble>` - wiadomość w czacie (do wydzielenia z page)
- [ ] ⏳ `<UserCard>` - karta użytkownika (do wydzielenia)
- [ ] ⏳ `<EventCard>` - karta eventu (do wydzielenia)
- [ ] ⏳ `<RatingStars>` - gwiazdki oceny (do wydzielenia)
- [ ] ⏳ `<VideoUploader>` - komponent do wyboru i wysyłania filmu
- [ ] ⏳ `<ProgressBar>` - pasek postępu transferu (do wydzielenia)
- [ ] ⏳ `<WebRTCStatus>` - status połączenia WebRTC (do wydzielenia)

### Stylowanie (Tailwind)
- [x] ✅ Konfiguracja motywu kolorystycznego
- [x] ✅ Responsive design (mobile-first)
- [ ] ⏳ Dark mode (opcjonalnie)

### State Management
- [x] ✅ Auth state (Context API - current user, mock login/logout)
- [ ] ⏳ Zamiana na prawdziwe API (po backend setup)
- [ ] ⏳ Chat state (messages, active users) - połączenie z Socket.IO
- [ ] ⏳ WebRTC state (connection status, transfer progress) - prawdziwy WebRTC

### Integracja Socket.IO (client)
- [ ] ⏳ Setup socket.io-client
- [ ] ⏳ Połączenie z backendem
- [ ] ⏳ Obsługa eventów czatu
- [ ] ⏳ Obsługa eventów WebRTC signaling
- [ ] ⏳ Reconnection logic

---

## 🔐 7. Bezpieczeństwo

### Backend
- [ ] ⏳ Rate limiting (np. express-rate-limit)
- [ ] ⏳ Helmet.js dla security headers
- [ ] ⏳ CORS configuration
- [ ] ⏳ Input sanitization (XSS prevention)
- [ ] ⏳ SQL injection prevention (prepared statements)
- [ ] ⏳ Walidacja wszystkich inputów (express-validator)

### Frontend
- [ ] ⏳ XSS prevention (sanitize user input)
- [ ] ⏳ CSRF protection
- [ ] ⏳ Secure token storage (httpOnly cookies lub secure localStorage)

### WebRTC
- [ ] ⏳ Potwierdzenie, że WebRTC używa DTLS/SRTP (natywne szyfrowanie)
- [ ] ⏳ Opcjonalne: dodatkowe szyfrowanie czatu (WebCrypto API)

---

## 🧪 8. Testowanie

### Backend
- [ ] ⏳ Setup Jest + Supertest
- [ ] ⏳ Testy jednostkowe endpoints API
- [ ] ⏳ Testy integracyjne z bazą danych
- [ ] ⏳ Testy WebSocket (Socket.IO)

### Frontend
- [ ] ⏳ Setup Vitest + React Testing Library
- [ ] ⏳ Testy jednostkowe komponentów
- [ ] ⏳ Testy integracyjne widoków
- [ ] ⏳ E2E testy (Playwright / Cypress)

### WebRTC
- [ ] ⏳ Testy manualne transferu plików (różne rozmiary)
- [ ] ⏳ Testy na różnych urządzeniach (Android/iOS)
- [ ] ⏳ Testy w różnych warunkach sieciowych

---

## 📚 9. Dokumentacja

- [x] ✅ README.md - instrukcja uruchomienia projektu
- [x] ✅ QUICKSTART.md - szybki start (2 minuty)
- [x] ✅ CONTEXT.md - architektura i założenia projektu
- [x] ✅ TODO.md - roadmap projektu
- [ ] ⏳ API documentation (Swagger/OpenAPI)
- [ ] ⏳ Architektura systemu (diagram)
- [ ] ⏳ WebRTC flow diagram
- [ ] ⏳ User flow diagrams

---

## 🚀 10. Deployment i DevOps

- [ ] ⏳ Konfiguracja CI/CD (GitHub Actions)
- [ ] ⏳ Automated tests w CI
- [ ] ⏳ Docker image optimization (multi-stage builds)
- [ ] ⏳ Konfiguracja production environment variables
- [ ] ⏳ Setup HTTPS (Let's Encrypt)
- [ ] ⏳ Deployment backendu (VPS / Cloud)
- [ ] ⏳ Deployment frontendu (Vercel / Netlify / własny serwer)
- [ ] ⏳ Setup PostgreSQL backup strategy
- [ ] ⏳ Monitoring (logs, errors, performance)

---

## ➕ 11. Opcjonalne rozszerzenia (po MVP)

- [ ] ⏳ System oznaczeń zaufania (badges dla zweryfikowanych użytkowników)
- [ ] ⏳ Blokowanie użytkowników
- [ ] ⏳ Publiczne profile z opiniami
- [ ] ⏳ Powiadomienia push (Web Push API)
- [ ] ⏳ Kompresja wideo przed wysłaniem (opcjonalnie)
- [ ] ⏳ Podgląd thumbnail filmu przed wysłaniem
- [ ] ⏳ Multi-file transfer (wysyłanie wielu filmów naraz)
- [ ] ⏳ Integracja z worldsdc.com API (automatyczne pobieranie eventów)
- [ ] ⏳ Statystyki użycia aplikacji (analytics)
- [ ] ⏳ Admin panel

---

## 🎯 Priorytet realizacji (zaktualizowany)

### ✅ Faza 0: Frontend Mockup (UKOŃCZONA)
- ✅ Docker Compose (nginx + frontend)
- ✅ React + Vite + Tailwind setup
- ✅ Wszystkie widoki z mockupami
- ✅ Mock data i routing
- ✅ Dokumentacja

**Status:** Gotowe do prezentacji i testowania UX

---

### 🔄 Faza 1: MVP Backend Foundation (1-2 tygodnie) - **AKTUALNY CEL**
**Priorytet: WYSOKI** - Następna faza do realizacji

1. ✨ **Backend setup** (1-2 godziny)
   - Kontener backend w docker-compose
   - Node.js + Express + podstawowa struktura
   - Healthcheck endpoint

2. 🗄️ **PostgreSQL setup** (2-3 godziny)
   - Kontener PostgreSQL
   - Schema bazy (6 tabel)
   - Narzędzie do migracji (Prisma/Knex)
   - Seed data

3. 🔐 **Authentication API** (3-4 godziny)
   - bcrypt + JWT
   - Register/Login endpoints
   - Auth middleware
   - Podłączenie frontendu

4. 💬 **WebSocket Chat** (4-5 godzin)
   - Socket.IO setup
   - Event rooms
   - Real-time messaging
   - Active users list

**Łączny czas:** ~11-14 godzin (1-2 tygodnie przy spokojnym tempie)

---

### Faza 2: Core Features (2-3 tygodnie)
1. Matches API (tworzenie par)
2. Private chat 1:1 (Socket.IO rooms)
3. WebRTC signaling server
4. Ratings API

---

### Faza 3: Główna funkcjonalność WebRTC (3-4 tygodnie)
1. **WebRTC P2P connection**
2. **File transfer via DataChannel** (chunking, progress)
3. Error handling i reconnection
4. Optymalizacje

---

### Faza 4: Finalizacja MVP (2-3 tygodnie)
1. Bezpieczeństwo (rate limiting, validation, CORS)
2. Testy (unit, integration, E2E)
3. PWA features (manifest, service worker)
4. Deployment

---

### Faza 5: Opcjonalne rozszerzenia (ongoing)
- Features z sekcji 11

---

## 📊 Postęp projektu

**Ukończone:** ~25% (frontend mockup + dokumentacja)
**W trakcie:** 0% (przygotowanie do backend)
**Do zrobienia:** ~75% (backend, WebRTC, deployment)

---

## 📝 Notatki
- ✅ Frontend mockup gotowy - można prezentować UX
- 🎯 Następny krok: **Backend setup** (Node.js + Express + PostgreSQL)
- 💡 Wszystkie widoki działają z mock data - łatwo podłączyć prawdziwe API
- 🔥 Główna funkcjonalność (WebRTC P2P) jest mockupem - wymaga implementacji
- 📌 Regularnie aktualizuj status zadań (⏳ → 🔄 → ✅)
- 🚀 WebRTC file transfer to najważniejsza i najtrudniejsza część projektu

---

## 🎓 Dodatkowe zasoby

### Backend (Node.js + Express)
- Express best practices: https://expressjs.com/en/advanced/best-practice-performance.html
- JWT authentication: https://jwt.io/introduction
- Socket.IO docs: https://socket.io/docs/v4/

### WebRTC
- WebRTC for beginners: https://webrtc.org/getting-started/overview
- RTCDataChannel guide: https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel
- File transfer via WebRTC: https://webrtc.github.io/samples/src/content/datachannel/filetransfer/

### Database
- Prisma docs: https://www.prisma.io/docs
- PostgreSQL best practices: https://wiki.postgresql.org/wiki/Don't_Do_This