913d685721
- 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
184 lines
5.9 KiB
Markdown
184 lines
5.9 KiB
Markdown
# 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
|