docs: streamline README and update SESSION_CONTEXT, archive outdated docs
- Streamline README.md from 645 to 365 lines (43% reduction) - Remove duplicate content with other documentation files - Focus README on quick start, features overview, and links to detailed docs - Update SESSION_CONTEXT.md with recent changes (342/342 tests, matching runs audit) - Archive outdated documentation: - CONTEXT.md (duplicated in README) - QUICKSTART.md (mentions mock auth, outdated) - QUICK_TEST.md (outdated) - Keep SESSION_CONTEXT.md active for context restoration
This commit is contained in:
Radosław Gierwiało
183
docs/archive/CONTEXT.md
Normal file
183
docs/archive/CONTEXT.md
Normal file
@@ -0,0 +1,183 @@
|
||||
# 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
|
||||
- Account tiers: `accountTier` (BASIC/SUPPORTER/COMFORT), `recordingsDone`, `recordingsReceived`
|
||||
- `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
|
||||
- Recording opt-out, competitor numbers, `accountTierOverride` (event-specific tier upgrades)
|
||||
- `event_checkin_tokens`: QR code check-in system
|
||||
- `recording_suggestions`: auto-matching results with collision detection
|
||||
|
||||
---
|
||||
|
||||
## 🔁 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 (285/286 tests passing - 99.7%, 73% coverage)
|
||||
|
||||
### 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
|
||||
```jsx
|
||||
// ✅ 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/DEPLOYMENT.md` - Production deployment guide
|
||||
- `docs/MONITORING.md` - Monitoring and operations
|
||||
- `docs/archive/COMPLETED.md` - Archiwum ukończonych zadań
|
||||
- `docs/archive/RESOURCES.md` - Linki do dokumentacji i zasobów edukacyjnych
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-11-29
|
||||
|
||||
**Status:** ✅ MVP Complete - All core features implemented and tested
|
||||
92
docs/archive/QUICKSTART.md
Normal file
92
docs/archive/QUICKSTART.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# Quick Start - spotlight.cam 🚀
|
||||
|
||||
## Uruchomienie (1 minuta!)
|
||||
|
||||
```bash
|
||||
# 1. Uruchom Docker Compose
|
||||
docker-compose up -d
|
||||
|
||||
# 2. Otwórz przeglądarkę
|
||||
http://localhost:8080
|
||||
```
|
||||
|
||||
## Demo Flow (2 minuty)
|
||||
|
||||
### 1. Zaloguj się
|
||||
- URL: http://localhost:8080/login
|
||||
- Wpisz **dowolny** email i hasło (np. `test@test.com` / `test123`)
|
||||
- Mock auth - natychmiast zaloguje
|
||||
|
||||
### 2. Wybierz event
|
||||
- Kliknij na "Warsaw Dance Festival 2025"
|
||||
- Przycisk "Dołącz do czatu"
|
||||
|
||||
### 3. Czat eventowy - Matchmaking
|
||||
- Zobacz mockowane wiadomości
|
||||
- Po prawej lista użytkowników
|
||||
- Kliknij **➕** przy "sarah_swing"
|
||||
- Zostaniesz przekierowany do czatu 1:1
|
||||
|
||||
### 4. 🔥 Główna funkcjonalność - Wysyłanie filmu WebRTC
|
||||
- Kliknij **"Wyślij film (WebRTC)"**
|
||||
- Wybierz dowolny plik wideo z dysku
|
||||
- Kliknij **"Wyślij film (P2P)"**
|
||||
- Zobacz:
|
||||
- ✅ Status WebRTC: disconnected → connecting → connected
|
||||
- ✅ Progress bar: 0% → 100%
|
||||
- ✅ Info o szyfrrowaniu E2E (DTLS/SRTP)
|
||||
- ✅ Wiadomość o przesłanym pliku w czacie
|
||||
|
||||
### 5. Fallback - Wysyłanie linku
|
||||
- Kliknij **"Link"**
|
||||
- Wklej URL (np. https://drive.google.com/file/d/abc123)
|
||||
- Kliknij "Wyślij link"
|
||||
|
||||
### 6. Oceń partnera
|
||||
- Kliknij **"Zakończ i oceń"**
|
||||
- Wybierz 5 gwiazdek ⭐⭐⭐⭐⭐
|
||||
- Dodaj komentarz: "Świetna współpraca!"
|
||||
- Zaznacz "Chcę współpracować ponownie"
|
||||
- Kliknij "Zapisz ocenę"
|
||||
|
||||
### 7. Historia
|
||||
- URL: http://localhost:8080/history
|
||||
- Zobacz wszystkie matche
|
||||
- Zobacz otrzymane oceny
|
||||
- Zobacz statystyki
|
||||
|
||||
## Co to jest?
|
||||
|
||||
**spotlight.cam** to mockup aplikacji PWA dla społeczności tanecznej. Główna funkcjonalność to **peer-to-peer przesyłanie filmów przez WebRTC**.
|
||||
|
||||
### ✅ Zrobione (Mockup)
|
||||
- Autoryzacja (mock)
|
||||
- Wybór eventów
|
||||
- Czat eventowy (matchmaking)
|
||||
- Czat 1:1
|
||||
- **🔥 Mockup WebRTC P2P transfer** (symulacja transferu plików)
|
||||
- System ocen
|
||||
- Historia współprac
|
||||
|
||||
### 🔜 Do zrobienia
|
||||
- Backend (Node.js + Express + PostgreSQL)
|
||||
- WebSocket (Socket.IO) - real-time
|
||||
- **Prawdziwy WebRTC P2P** (RTCDataChannel, chunking, progress monitoring)
|
||||
- JWT autoryzacja
|
||||
- Deployment
|
||||
|
||||
## Zatrzymanie
|
||||
|
||||
```bash
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
## Pomoc
|
||||
|
||||
- Pełna dokumentacja: `README.md`
|
||||
- Architektura: `docs/CONTEXT.md`
|
||||
- Roadmap: `docs/TODO.md`
|
||||
|
||||
---
|
||||
|
||||
**Mockup jest w pełni funkcjonalny!** WebRTC transfer jest symulowany, prawdziwa implementacja będzie w kolejnym etapie.
|
||||
71
docs/archive/QUICK_TEST.md
Normal file
71
docs/archive/QUICK_TEST.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# Quick WebRTC Test Checklist
|
||||
|
||||
## Setup (2 browser windows)
|
||||
|
||||
**Window 1:** Login as `john@example.com` / `Dance123!`
|
||||
**Window 2:** Login as `sarah@example.com` / `Swing456!`
|
||||
|
||||
## Test Steps
|
||||
|
||||
### 1. Create Match
|
||||
- [ ] User A: Go to event → Request match with User B
|
||||
- [ ] User B: Accept match
|
||||
- [ ] Both: Navigate to match chat
|
||||
|
||||
### 2. Establish WebRTC Connection
|
||||
- [ ] User A: Click "Send video (WebRTC)"
|
||||
- [ ] User A: Select a small video file (~5-10MB)
|
||||
- [ ] User A: Click "Send video (P2P)"
|
||||
- [ ] Both: Status shows "Connecting..." → "Connected (P2P)" ✅
|
||||
|
||||
### 3. File Transfer
|
||||
- [ ] User A: See progress bar 0% → 100%
|
||||
- [ ] User B: See "📥 Receiving: [filename]"
|
||||
- [ ] User B: File downloads automatically when complete
|
||||
- [ ] Both: Chat message appears: "📹 Video sent: [filename]"
|
||||
|
||||
## Console Logs to Check (F12)
|
||||
|
||||
**User A:**
|
||||
```
|
||||
📤 Sent WebRTC offer
|
||||
📤 Sent ICE candidate
|
||||
✅ DataChannel opened
|
||||
📤 Sent file metadata
|
||||
📤 Sent chunk 1/X
|
||||
✅ File transfer complete
|
||||
```
|
||||
|
||||
**User B:**
|
||||
```
|
||||
📥 Received WebRTC offer
|
||||
✅ DataChannel received
|
||||
📥 Receiving file
|
||||
📥 Received chunk 1/X
|
||||
✅ File received and downloaded
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ Connection state: "Connected (P2P)" with green dot
|
||||
✅ Transfer completes: 100% on both sides
|
||||
✅ File downloads on receiver side
|
||||
✅ File size matches original
|
||||
✅ No errors in console
|
||||
|
||||
## If Something Fails
|
||||
|
||||
1. Check both users are in same match chat
|
||||
2. Check Socket.IO is connected (message input not disabled)
|
||||
3. Check browser console for errors
|
||||
4. Try refreshing both windows
|
||||
5. See docs/WEBRTC_TESTING_GUIDE.md for detailed troubleshooting
|
||||
|
||||
## Start Testing
|
||||
|
||||
```bash
|
||||
docker compose up --build
|
||||
# Then open http://localhost:8080 in two browser windows
|
||||
```
|
||||
|
||||
🚀 **Ready to test!**
|
||||
Reference in New Issue
Block a user