spotlightcam/README.md

spotlight.cam 🎥

Aplikacja webowa (PWA) dla społeczności tanecznej umożliwiająca matchmaking, czatowanie i wymianę nagrań wideo bezpośrednio przez WebRTC (peer-to-peer).

🚀 Funkcjonalności

✅ Zaimplementowane

Autoryzacja & Bezpieczeństwo:

• ✅ JWT Authentication - prawdziwa autoryzacja z bcrypt password hashing
• ✅ Email Verification - weryfikacja email przez AWS SES (link + PIN code)
• ✅ Password Reset - pełny workflow resetowania hasła
• ✅ WSDC Integration - auto-fill danych z worldsdc.com podczas rejestracji
• ✅ Event Slugs - unikalne alfanumeryczne identyfikatory zapobiegające ID enumeration attacks

Profile użytkowników:

• ✅ User Profiles - edycja profilu (imię, nazwisko, WSDC ID)
• ✅ Social Media Links - YouTube, Instagram, Facebook, TikTok
• ✅ Location - kraj (dropdown z 195 krajami) i miasto
• ✅ Public Profiles - widoczne dla innych zalogowanych pod /{username}
• ✅ Profile Statistics - liczba matchów, średnia ocena, liczba recenzji

Eventy & Chat:

• ✅ Event List - przeglądanie eventów tanecznych z worldsdc.com
• ✅ Event Participation Tracking - automatyczne zapisywanie dołączonych eventów
• ✅ Real-time Event Chat - Socket.IO chat dla uczestników eventu
• ✅ Active Users Sidebar - lista użytkowników online w evencie
• ✅ Message History - persistencja wiadomości w bazie danych
• ✅ Infinite Scroll - ładowanie starszych wiadomości

Matchmaking & Private Chat:

• ✅ Matchmaking - łączenie się w pary bezpośrednio z czatu eventowego
• ✅ Private 1:1 Chat - prywatny czat dla sparowanych użytkowników z Socket.IO

Backend & Infrastructure:

• ✅ PostgreSQL Database - 7 tabel z relacjami (Prisma ORM)
• ✅ RESTful API - Express.js backend z walidacją
• ✅ WebSocket - Socket.IO dla real-time communication
• ✅ Docker Compose - pełna orkiestracja (nginx, frontend, backend, PostgreSQL)
• ✅ Test Coverage - 81%+ coverage (Jest + Supertest)

🔜 W trakcie implementacji

• ⏳ Matches API - create/accept match requests
• ⏳ Ratings API - ocenianie partnera po współpracy (1-5 gwiazdek)
• ⏳ WebRTC Signaling - SDP/ICE exchange via Socket.IO
• ⏳ WebRTC P2P Transfer - prawdziwy transfer plików przez RTCDataChannel

🛠️ Stack Technologiczny

Frontend

• React 18 - framework UI
• Vite - build tool i dev server
• Tailwind CSS v3.4.0 - stylowanie
• React Router - routing
• Lucide React - ikony
• Context API - zarządzanie stanem (auth)
• Socket.IO Client - real-time WebSocket communication

Backend

• Node.js 20 - runtime
• Express 4.18 - web framework
• PostgreSQL 15 - relational database
• Prisma ORM 5.22 - type-safe database client
• Socket.IO 4.8 - WebSocket server
• bcrypt - password hashing
• JWT - token-based authentication
• AWS SES - email service
• Jest + Supertest - testing (81%+ coverage)

Infrastructure

• Docker Compose - container orchestration (dev + prod profiles)
• Nginx - reverse proxy & static file serving
• Alpine Linux - lightweight container base images

📁 Struktura projektu

spotlightcam/
├── docker-compose.yml          # Container orchestration (dev + prod profiles)
├── nginx/                      # Nginx reverse proxy config
│   ├── nginx.conf
│   └── conf.d/default.conf    # Proxy /api & /socket.io to backend
├── frontend/                   # React PWA
│   ├── src/
│   │   ├── components/        # React components
│   │   │   ├── common/        # Shared components, PasswordStrength, VerificationBanner
│   │   │   ├── chat/          # Chat components
│   │   │   ├── video/         # WebRTC video transfer (mockup)
│   │   │   └── layout/        # Navbar, Layout
│   │   ├── pages/             # Application pages
│   │   │   ├── LoginPage.jsx
│   │   │   ├── RegisterPage.jsx         # Two-step registration with WSDC lookup
│   │   │   ├── VerifyEmailPage.jsx      # Email verification (link + PIN)
│   │   │   ├── ForgotPasswordPage.jsx   # Request password reset
│   │   │   ├── ResetPasswordPage.jsx    # Reset password with token
│   │   │   ├── ProfilePage.jsx          # Edit profile (social media, location)
│   │   │   ├── PublicProfilePage.jsx    # View other user's profile
│   │   │   ├── EventsPage.jsx           # Event list with real API
│   │   │   ├── EventChatPage.jsx        # Real-time event chat
│   │   │   ├── MatchChatPage.jsx        # Private chat + WebRTC mockup
│   │   │   ├── RatePartnerPage.jsx      # Rate partner after collaboration
│   │   │   └── HistoryPage.jsx          # Match history
│   │   ├── contexts/          # AuthContext (JWT integration)
│   │   ├── services/          # API client, Socket.IO client
│   │   ├── data/              # Static data (countries list)
│   │   └── mocks/             # Mock data (for UI development)
│   ├── Dockerfile             # Development container
│   ├── Dockerfile.prod        # Production build
│   └── package.json
├── backend/                    # Node.js + Express API
│   ├── src/
│   │   ├── controllers/       # Auth, users, events, WSDC
│   │   ├── middleware/        # Auth, validation, error handling
│   │   ├── routes/            # API routes
│   │   ├── socket/            # Socket.IO server (event/match rooms)
│   │   ├── utils/             # Auth utils, DB, email service (AWS SES)
│   │   └── __tests__/         # Jest unit tests (81%+ coverage)
│   ├── prisma/
│   │   ├── schema.prisma      # Database schema (7 tables)
│   │   ├── migrations/        # Database migrations
│   │   └── seed.js            # Seed data
│   ├── Dockerfile             # Development container
│   ├── Dockerfile.prod        # Production build
│   └── package.json
└── docs/                       # Documentation
    ├── SESSION_CONTEXT.md     # Quick session context (minimal tokens)
    ├── CONTEXT.md             # Full project description
    ├── TODO.md                # Task list & roadmap
    ├── ARCHITECTURE.md        # Technical details
    ├── COMPLETED.md           # Completed tasks archive
    ├── PHASE_1.5.md           # Phase 1.5 documentation
    ├── SECURITY_AUDIT.md      # Security audit & fixes
    ├── DEPLOYMENT.md          # Deployment guide
    └── RESOURCES.md           # Learning resources

🚀 Uruchomienie projektu

Wymagania

• Docker i Docker Compose
• (Opcjonalnie) Node.js 20+ dla developmentu bez Dockera

Development Mode

1. Sklonuj repozytorium:

git clone <repo-url>
cd spotlightcam

2. Skopiuj przykładowy plik .env:

cp backend/.env.example backend/.env

3. Uruchom Docker Compose z profilem dev:

docker compose --profile dev up

4. Otwórz przeglądarkę:

http://localhost:8080

Production Mode

docker compose --profile prod up -d

Dostęp do usług

Development:

• Frontend: http://localhost:8080
• Backend API: http://localhost:8080/api
• WebSocket: ws://localhost:8080/socket.io
• Health check: http://localhost:8080/api/health
• PostgreSQL: localhost:5432 (exposed for dev tools)

Production:

• Application: http://localhost (port 80)
• HTTPS: https://localhost (port 443, requires SSL certificates)
• PostgreSQL: internal only (not exposed)

Zatrzymanie

# Development
docker compose --profile dev down

# Production
docker compose --profile prod down

Rebuild po zmianach

docker compose --profile dev down
docker compose --profile dev up --build

🗄️ Database Schema

7 tables z relacjami (Prisma ORM):

1. users - użytkownicy

   • Base: id, username, email, password_hash, avatar, created_at, updated_at
   • WSDC: first_name, last_name, wsdc_id
   • Email: email_verified, verification_token, verification_code, verification_token_expiry
   • Password Reset: reset_token, reset_token_expiry
   • Social: youtube_url, instagram_url, facebook_url, tiktok_url
   • Location: country, city

2. events - eventy taneczne

   • id, slug (unique), name, location, start_date, end_date, description, worldsdc_id, participants_count

3. event_participants - uczestnicy eventów (many-to-many)

   • id, user_id, event_id, joined_at

4. chat_rooms - pokoje czatu

   • id, event_id, type (event/private), created_at

5. messages - wiadomości

   • id, room_id, user_id, content, type (text/link/video), created_at

6. matches - pary użytkowników

   • id, user1_id, user2_id, event_id, room_id, status (pending/accepted/completed), created_at

7. ratings - oceny

   • id, match_id, rater_id, rated_id, score (1-5), comment, would_collaborate_again, created_at

Migracje

# Rozwój (w kontenerze backend)
docker compose exec backend npx prisma migrate dev

# Produkcja
docker compose exec backend-prod npx prisma migrate deploy

# Generowanie Prisma Client
docker compose exec backend npx prisma generate

Seed data

docker compose exec backend npx prisma db seed

Dodaje:

• 3 eventy (Warsaw, Barcelona, Herräng)
• 2 użytkowników (john_doe, jane_smith)
• Event chat rooms

🧪 Testowanie aplikacji

Flow testowy:

1. Rejestracja z WSDC (http://localhost:8080/register)

   • Opcjonalnie: podaj WSDC ID (np. 12345) dla auto-fill danych
   • Wypełnij formularz rejestracji
   • Otrzymasz email weryfikacyjny (sprawdź AWS SES sandbox)

2. Weryfikacja Email (http://localhost:8080/verify-email)

   • Kliknij link z emaila LUB wpisz 6-cyfrowy kod PIN
   • Email zostanie zweryfikowany

3. Logowanie (http://localhost:8080/login)

   • Email: john@example.com
   • Password: password123

4. Edycja profilu (http://localhost:8080/profile)

   • Uzupełnij social media links (Instagram, YouTube, etc.)
   • Wybierz kraj z listy 195 krajów
   • Podaj miasto
   • Edytuj WSDC ID, imię, nazwisko

5. Wybór eventu (http://localhost:8080/events)

   • Zobacz listę eventów (dołączone wyświetlają się na górze)
   • Wybierz event (np. "Warsaw Dance Festival 2025")
   • Kliknij "Join chat" lub "Open chat" (jeśli już dołączyłeś)

6. Czat eventowy

   • Real-time chat z Socket.IO
   • Po prawej stronie lista aktywnych użytkowników online
   • Kliknij ikonę "+" przy użytkowniku aby się z nim połączyć
   • Zostaniesz przekierowany do prywatnego czatu 1:1

7. Czat 1:1 - WebRTC (mockup) 🔥

   • Zobacz profil partnera na górze (kliknij username aby zobaczyć public profile)
   • Status WebRTC połączenia (disconnected/connecting/connected)
   • Wysyłanie filmu przez WebRTC (mockup):
     • Kliknij "Wyślij film (WebRTC)"
     • Wybierz plik wideo z dysku
     • Zobacz symulację transferu P2P
   • Fallback - wysyłanie linku:
     • Kliknij "Link"
     • Wklej URL do filmu (Google Drive, Dropbox, etc.)

8. Ocena partnera (coming soon - Matches & Ratings API)

   • Kliknij "Zakończ i oceń"
   • Wybierz ocenę (1-5 gwiazdek)
   • Dodaj komentarz
   • Zaznacz czy chcesz współpracować ponownie

9. Historia współprac (http://localhost:8080/history)

   • Zobacz listę matchów
   • Zobacz otrzymane oceny
   • Zobacz statystyki

10. Public Profiles

    • Kliknij na username innego użytkownika
    • Zobacz profil: avatar, lokalizacja, social media, statystyki

🔐 Bezpieczeństwo

Zaimplementowane zabezpieczenia:

✅ Authentication:

• bcrypt password hashing (10 salt rounds)
• JWT tokens (httpOnly cookies in production)
• Protected routes with auth middleware
• Email verification required

✅ Input Validation:

• express-validator for all inputs
• Custom validators for URLs (domain checking)
• SQL injection prevention (Prisma parameterized queries)
• XSS protection (input sanitization)

✅ Rate Limiting:

• Login attempts: 5 per 15 minutes
• Registration: 3 per hour
• Email sending: 3 per hour

✅ Database:

• Unique constraints on emails, usernames
• Indexed fields for performance
• Cascading deletes for data integrity

✅ Event Security:

• Unique alphanumeric slugs (12 chars, MD5-based)
• Prevents ID enumeration attacks
• URLs: /events/{slug}/chat instead of /events/{id}/chat

✅ Socket.IO:

• JWT authentication for WebSocket connections
• Room-based access control
• User verification before joining rooms

Planowane zabezpieczenia (Phase 3):

⏳ CORS configuration ⏳ CSRF protection (cookies) ⏳ Helmet.js security headers ⏳ Content Security Policy ⏳ HTTPS enforcement (production)

📊 Test Coverage

Backend: 81%+ coverage

• Auth controllers: 78%
• Socket.IO module: 89%
• Jest + Supertest

# Run tests
docker compose exec backend npm test

# Coverage report
docker compose exec backend npm run test:coverage

🎯 Roadmap

✅ Phase 0: Frontend Mockup (COMPLETED)

• All views with mock data
• WebRTC UI mockup
• Routing & navigation

✅ Phase 1: Backend Foundation (COMPLETED)

• Node.js + Express + PostgreSQL
• JWT authentication
• Socket.IO real-time chat
• Test coverage 81%+

✅ Phase 1.5: Email & WSDC Integration (COMPLETED)

• Email verification (AWS SES)
• Password reset workflow
• WSDC API integration
• User profiles with social media & location
• Public profiles
• Event participation tracking
• Event security (slugs)

⏳ Phase 2: Core Features (IN PROGRESS)

• Matches API (create/accept match requests)
• Ratings API (rate partner after collaboration)
• WebRTC signaling (SDP/ICE exchange)
• WebRTC P2P file transfer (RTCDataChannel)

⏳ Phase 3: MVP Finalization (PLANNED)

• Security hardening
• Integration & E2E tests
• PWA features (manifest, service worker)
• Production deployment
• Monitoring & logging

⏳ Phase 4: Extensions (FUTURE)

• User badges & trust system
• Block users
• Push notifications
• Video compression
• Multi-file transfer

📖 Dokumentacja

Quick Start:

• docs/SESSION_CONTEXT.md - Szybki kontekst dla wznowienia sesji (minimal tokens)

Main Documentation:

• docs/CONTEXT.md - Główny opis projektu i założeń
• docs/TODO.md - Aktywne zadania i roadmap

Detailed Documentation:

• docs/ARCHITECTURE.md - Szczegóły techniczne i implementacyjne
• docs/PHASE_1.5.md - Dokumentacja Phase 1.5 (Email & WSDC)
• docs/SECURITY_AUDIT.md - Security audit & fixes
• docs/DEPLOYMENT.md - Deployment guide
• docs/COMPLETED.md - Archiwum ukończonych zadań
• docs/RESOURCES.md - Linki do dokumentacji i zasobów edukacyjnych

🤝 Contributing

Projekt jest w fazie rozwoju. Aktualnie implementujemy Phase 2 (Matches & Ratings API, WebRTC P2P transfer).

Git workflow:

git status
git add .
git commit -m "feat: description"

Uwaga: Commit messages bez wzmianek o AI/automatycznym generowaniu.

📄 License

TBD

---

Current Status: Phase 1.5 ✅ Completed | Phase 2 ⏳ In Progress (60% overall)

Last Updated: 2025-11-13