a1357393e8
- Add SESSION_CONTEXT.md: ultra-compact context for new sessions (~500 lines) - Add ARCHITECTURE.md: detailed technical specs and implementation details - Add COMPLETED.md: archive of completed tasks (Phase 0) - Add RESOURCES.md: learning resources and documentation links - Refactor CONTEXT.md: keep only core project info and guidelines - Refactor TODO.md: keep only active tasks and next steps - Update README.md: reference new documentation structure This change reduces token usage when resuming sessions by ~60% while maintaining complete project documentation in separate, well-organized files.
170 lines
4.8 KiB
Markdown
170 lines
4.8 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:**
|
||
- `nginx`: Reverse proxy (port 8080)
|
||
- `frontend`: React/Vite/Tailwind (port 5173 internal)
|
||
|
||
**Planned:**
|
||
- `backend`: Node.js/Express/Socket.IO (port 3000 internal)
|
||
- `db`: PostgreSQL 15
|
||
|
||
---
|
||
|
||
## 🗃️ Modele bazy danych (Planned)
|
||
|
||
- `users`: identyfikacja, email, hasło, avatar
|
||
- `events`: lista eventów (z worldsdc.com)
|
||
- `chat_rooms`: publiczne (event) i prywatne (match) pokoje
|
||
- `messages`: wiadomości tekstowe/linki
|
||
- `matches`: relacja między dwoma użytkownikami
|
||
- `ratings`: oceny po wymianie nagraniami (1-5, komentarz)
|
||
|
||
---
|
||
|
||
## 🔁 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 (Current)
|
||
- React 18 + Vite
|
||
- Tailwind CSS v3.4.0 (NOT v4)
|
||
- React Router
|
||
- Context API
|
||
|
||
### Backend (Planned)
|
||
- Node.js + Express
|
||
- Socket.IO (WebSocket)
|
||
- PostgreSQL 15
|
||
- bcrypt + JWT
|
||
|
||
### WebRTC (Planned)
|
||
- RTCPeerConnection
|
||
- RTCDataChannel
|
||
- Chunking (16KB chunks)
|
||
- STUN/TURN servers
|
||
|
||
---
|
||
|
||
## 🔐 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/COMPLETED.md` - Archiwum ukończonych zadań
|
||
- `docs/RESOURCES.md` - Linki do dokumentacji i zasobów edukacyjnych
|
||
|
||
---
|
||
|
||
**Last Updated:** 2025-11-12
|