radziel/spotlightcam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
21ba899f9871e0159f8922d547915f34605dcff2
spotlightcam/README.md
Radosław Gierwiało 21ba899f98 docs: update README and docs to reflect Phase 1.5 completion 
Update documentation to accurately reflect all features implemented in Phase 1.5:

README.md updates:
- Replace outdated "mockup" references with real implementation status
- Add comprehensive feature list with Phase 1.5 additions
- Document 7 database tables (added event_participants)
- Add user profile features (social media, location, public profiles)
- Add event security features (unique slugs)
- Update tech stack versions and test coverage (81%+)
- Add detailed setup instructions for dev and prod profiles
- Update roadmap to show Phase 1.5 as completed

SESSION_CONTEXT.md updates:
- Update current status to Phase 1.5 completed (65% overall)
- Add new features to "What Works Now" section
- Update database schema to 7 tables with all Phase 1.5 fields
- Add new migrations (event slugs)
- Update key files list with Phase 1.5 changes
- Update frontend routes to use slugs (/events/:slug/chat)

TODO.md updates:
- Mark Phase 1.5 as completed with full feature list
- Update progress tracking table (65% overall completion)
- Update last modified date to 2025-11-13

Phase 1.5 features documented:
- Email verification (AWS SES with link + PIN code)
- Password reset workflow
- WSDC API integration
- User profiles (social media links: YouTube, Instagram, Facebook, TikTok)
- User location (country dropdown with 195 countries, city)
- Public profiles accessible at /{username}
- Event participation tracking (auto-save joined events)
- Event security (12-char unique slugs, prevent ID enumeration)
2025-11-13 21:51:11 +01:00

458 lines
15 KiB
Markdown
Raw Blame History

# 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:
```bash
git clone <repo-url>
cd spotlightcam
```
2. Skopiuj przykładowy plik .env:
```bash
cp backend/.env.example backend/.env
```
3. Uruchom Docker Compose z profilem dev:
```bash
docker compose --profile dev up
```
4. Otwórz przeglądarkę:
```
http://localhost:8080
```
### Production Mode
```bash
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
```bash
# Development
docker compose --profile dev down
# Production
docker compose --profile prod down
```
### Rebuild po zmianach
```bash
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
```bash
# 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
```bash
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
```bash
# 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:
```bash
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
Reference in New Issue View Git Blame Copy Permalink