From a1357393e8fe531c0a912802a553be2934b6e75a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rados=C5=82aw=20Gierwia=C5=82o?= Date: Wed, 12 Nov 2025 18:07:42 +0100 Subject: [PATCH] docs: optimize documentation structure for token efficiency - 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. --- README.md | 13 +- docs/ARCHITECTURE.md | 652 ++++++++++++++++++++++++++++++++++++++++ docs/COMPLETED.md | 225 ++++++++++++++ docs/CONTEXT.md | 250 +++++++-------- docs/RESOURCES.md | 294 ++++++++++++++++++ docs/SESSION_CONTEXT.md | 285 ++++++++++++++++++ docs/TODO.md | 577 +++++++++-------------------------- 7 files changed, 1723 insertions(+), 573 deletions(-) create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/COMPLETED.md create mode 100644 docs/RESOURCES.md create mode 100644 docs/SESSION_CONTEXT.md diff --git a/README.md b/README.md index 09deb8a..b052ef3 100644 --- a/README.md +++ b/README.md @@ -237,8 +237,17 @@ Zobacz `docs/TODO.md` dla pełnej listy zadań. Najważniejsze: ## 📖 Dokumentacja -- `docs/CONTEXT.md` - Szczegółowy opis projektu i architektury -- `docs/TODO.md` - Lista zadań do zrobienia +**Quick Start:** +- `docs/SESSION_CONTEXT.md` - **Ultra-zwięzły 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/COMPLETED.md` - Archiwum ukończonych zadań +- `docs/RESOURCES.md` - Linki do dokumentacji i zasobów edukacyjnych ## 🤝 Contributing diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..4450583 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,652 @@ +# Architecture - spotlight.cam + +**Technical architecture and implementation details** + +--- + +## System Architecture + +``` +┌─────────────────┐ +│ Web Browser │ (PWA - React + Vite + Tailwind) +│ (Android/iOS) │ +└────────┬────────┘ + │ HTTPS + ▼ +┌─────────────────┐ +│ nginx │ (Reverse Proxy, Port 8080) +│ (Port 8080) │ +└────────┬────────┘ + │ + ┌────┴────┐ + │ │ + ▼ ▼ +┌────────┐ ┌────────────┐ +│Frontend│ │ Backend │ (Node.js + Express + Socket.IO) +│(Vite) │ │ (planned) │ +│:5173 │ │ :3000 │ +└────────┘ └──────┬─────┘ + │ + ▼ + ┌─────────────┐ + │ PostgreSQL │ (Database) + │ (planned) │ + └─────────────┘ + +WebRTC P2P Connection: +Browser A ←──────────────────────→ Browser B + (Direct P2P via WebRTC) + ↑ + │ (Signaling only via WebSocket) + │ + Backend +``` + +--- + +## Docker Compose Services + +### Current Setup + +**nginx:** +- Image: `nginx:alpine` +- Port: 8080 (host) → 80 (container) +- Volumes: nginx config files +- Purpose: Reverse proxy, serves frontend, will proxy `/api/*` to backend + +**frontend:** +- Build: `./frontend/Dockerfile` +- Internal port: 5173 (Vite dev server) +- Volumes: hot reload support +- Environment: `NODE_ENV=development`, `VITE_HOST=0.0.0.0` + +### Planned Services + +**backend:** +- Build: `./backend/Dockerfile` +- Internal port: 3000 +- Environment: DB credentials, JWT secret, etc. +- Depends on: `db` + +**db:** +- Image: `postgres:15-alpine` +- Port: 5432 (internal only) +- Volumes: PostgreSQL data persistence +- Environment: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB + +--- + +## nginx Configuration + +**File:** `nginx/conf.d/default.conf` + +### Upstream +```nginx +upstream frontend { + server frontend:5173; +} + +upstream backend { + server backend:3000; # planned +} +``` + +### Routes +- `/` → frontend (React app) +- `/api/*` → backend (REST API) - planned +- `/socket.io/*` → backend (WebSocket) - planned + +### Features +- WebSocket support (Upgrade headers for Vite HMR and future Socket.IO) +- Client max body size: 500M (for large video uploads via link) +- Proxy headers: X-Real-IP, X-Forwarded-For, etc. + +--- + +## Frontend Architecture + +### Tech Stack +- **React 18** - UI library +- **Vite** - Build tool, dev server +- **Tailwind CSS v3.4.0** - Styling (NOT v4 - compatibility issues) +- **React Router** - Client-side routing +- **Context API** - State management (will add Socket.IO client, WebRTC logic) + +### Folder Structure +``` +frontend/ +├── public/ # Static assets +├── src/ +│ ├── main.jsx # Entry point +│ ├── App.jsx # Router setup +│ ├── pages/ # Page components +│ │ ├── LoginPage.jsx +│ │ ├── RegisterPage.jsx +│ │ ├── EventsPage.jsx +│ │ ├── EventChatPage.jsx +│ │ ├── MatchChatPage.jsx # ← Main WebRTC mockup +│ │ ├── RatePartnerPage.jsx +│ │ └── HistoryPage.jsx +│ ├── components/ +│ │ └── layout/ +│ │ ├── Layout.jsx +│ │ └── Navbar.jsx +│ ├── contexts/ +│ │ └── AuthContext.jsx # Mock auth (will become real) +│ ├── mocks/ # Mock data (will be replaced by API calls) +│ │ ├── users.js +│ │ ├── events.js +│ │ ├── messages.js +│ │ ├── matches.js +│ │ └── ratings.js +│ └── index.css # Tailwind imports +├── tailwind.config.js # Tailwind v3.4.0 config +├── vite.config.js # Vite config +└── package.json +``` + +### State Management + +**Current (Mock):** +- AuthContext: mock login/register/logout with localStorage +- Local state in components + +**Planned:** +- Socket.IO client for real-time chat +- WebRTC connection state +- Redux/Zustand (if needed for complex state) + +--- + +## Backend Architecture (Planned) + +### Tech Stack +- **Node.js** - Runtime +- **Express** - Web framework +- **Socket.IO** - WebSocket for chat and WebRTC signaling +- **PostgreSQL** - Database +- **Prisma/Knex** - ORM/Query builder +- **bcrypt** - Password hashing +- **JWT** - Authentication tokens + +### Folder Structure (Proposed) +``` +backend/ +├── src/ +│ ├── server.js # Entry point +│ ├── app.js # Express app setup +│ ├── routes/ # REST API routes +│ │ ├── auth.js # POST /api/auth/register, /login +│ │ ├── users.js # GET /api/users/me, etc. +│ │ ├── events.js # GET /api/events, etc. +│ │ ├── matches.js # POST /api/matches, etc. +│ │ └── ratings.js # POST /api/ratings, etc. +│ ├── controllers/ # Business logic +│ ├── models/ # Database models (Prisma schema or Knex queries) +│ ├── middleware/ # Auth, validation, error handling +│ ├── socket/ # Socket.IO event handlers +│ │ ├── chat.js # Event chat, private chat +│ │ └── webrtc.js # WebRTC signaling (SDP/ICE) +│ └── utils/ # Helpers +├── prisma/ # (if using Prisma) +│ └── schema.prisma # Database schema +├── migrations/ # Database migrations +├── .env.example +└── package.json +``` + +### API Endpoints (Planned) + +**Auth:** +- `POST /api/auth/register` - Create account +- `POST /api/auth/login` - Login, get JWT +- `POST /api/auth/logout` - Logout (optional, JWT is stateless) + +**Users:** +- `GET /api/users/me` - Get current user +- `PATCH /api/users/me` - Update profile +- `GET /api/users/:id` - Get user profile + +**Events:** +- `GET /api/events` - List all events +- `GET /api/events/:id` - Event details +- `POST /api/events/:id/join` - Join event + +**Matches:** +- `GET /api/matches` - User's match history +- `POST /api/matches` - Create match +- `PATCH /api/matches/:id` - Update match status + +**Ratings:** +- `POST /api/ratings` - Rate partner +- `GET /api/ratings/user/:id` - User's ratings +- `GET /api/ratings/stats/:id` - Rating statistics + +**Reports:** +- `POST /api/reports` - Report user + +--- + +## Database Schema + +### Tables + +**users:** +```sql +CREATE TABLE users ( + id SERIAL PRIMARY KEY, + username VARCHAR(50) UNIQUE NOT NULL, + email VARCHAR(255) UNIQUE NOT NULL, + password_hash VARCHAR(255) NOT NULL, + avatar VARCHAR(255), + created_at TIMESTAMP DEFAULT NOW(), + updated_at TIMESTAMP DEFAULT NOW() +); +``` + +**events:** +```sql +CREATE TABLE events ( + id SERIAL PRIMARY KEY, + name VARCHAR(255) NOT NULL, + location VARCHAR(255) NOT NULL, + start_date DATE NOT NULL, + end_date DATE NOT NULL, + worldsdc_id VARCHAR(100) UNIQUE, + participants_count INT DEFAULT 0, + description TEXT, + created_at TIMESTAMP DEFAULT NOW() +); +``` + +**chat_rooms:** +```sql +CREATE TABLE chat_rooms ( + id SERIAL PRIMARY KEY, + event_id INT REFERENCES events(id), + type VARCHAR(20) NOT NULL, -- 'event' or 'private' + created_at TIMESTAMP DEFAULT NOW() +); +``` + +**messages:** +```sql +CREATE TABLE messages ( + id SERIAL PRIMARY KEY, + room_id INT REFERENCES chat_rooms(id) ON DELETE CASCADE, + user_id INT REFERENCES users(id), + content TEXT NOT NULL, + type VARCHAR(20) NOT NULL, -- 'text', 'link', 'video' + created_at TIMESTAMP DEFAULT NOW() +); +``` + +**matches:** +```sql +CREATE TABLE matches ( + id SERIAL PRIMARY KEY, + user1_id INT REFERENCES users(id), + user2_id INT REFERENCES users(id), + event_id INT REFERENCES events(id), + room_id INT REFERENCES chat_rooms(id), + status VARCHAR(20) DEFAULT 'pending', -- 'pending', 'accepted', 'completed' + created_at TIMESTAMP DEFAULT NOW(), + CONSTRAINT unique_match UNIQUE (user1_id, user2_id, event_id) +); +``` + +**ratings:** +```sql +CREATE TABLE ratings ( + id SERIAL PRIMARY KEY, + match_id INT REFERENCES matches(id), + rater_id INT REFERENCES users(id), + rated_id INT REFERENCES users(id), + score INT CHECK (score >= 1 AND score <= 5), + comment TEXT, + would_collaborate_again BOOLEAN DEFAULT FALSE, + created_at TIMESTAMP DEFAULT NOW(), + CONSTRAINT unique_rating UNIQUE (match_id, rater_id, rated_id) +); +``` + +### Indexes (Performance) +```sql +CREATE INDEX idx_messages_room_id ON messages(room_id); +CREATE INDEX idx_messages_created_at ON messages(created_at); +CREATE INDEX idx_matches_user1_id ON matches(user1_id); +CREATE INDEX idx_matches_user2_id ON matches(user2_id); +CREATE INDEX idx_matches_event_id ON matches(event_id); +CREATE INDEX idx_ratings_rated_id ON ratings(rated_id); +``` + +--- + +## WebSocket (Socket.IO) Events + +### Client → Server + +**Connection:** +- `connect` - Client connects +- `disconnect` - Client disconnects + +**Event Chat:** +- `join_event_room` - Join event chat room + - Payload: `{ eventId: number }` +- `leave_event_room` - Leave event chat room + - Payload: `{ eventId: number }` +- `send_event_message` - Send message to event chat + - Payload: `{ eventId: number, content: string }` + +**Private Chat:** +- `join_private_room` - Join private match room + - Payload: `{ matchId: number }` +- `send_private_message` - Send message to match partner + - Payload: `{ matchId: number, content: string }` + +**Matchmaking:** +- `send_match_request` - Request match with user + - Payload: `{ targetUserId: number, eventId: number }` +- `accept_match_request` - Accept match request + - Payload: `{ matchId: number }` + +**WebRTC Signaling:** +- `webrtc_offer` - Send SDP offer + - Payload: `{ matchId: number, offer: RTCSessionDescriptionInit }` +- `webrtc_answer` - Send SDP answer + - Payload: `{ matchId: number, answer: RTCSessionDescriptionInit }` +- `webrtc_ice_candidate` - Send ICE candidate + - Payload: `{ matchId: number, candidate: RTCIceCandidate }` + +### Server → Client + +**Event Chat:** +- `event_message` - New message in event chat + - Payload: `{ id, roomId, userId, username, avatar, content, createdAt }` +- `active_users` - List of active users in event + - Payload: `{ users: Array }` + +**Private Chat:** +- `private_message` - New message from partner + - Payload: `{ id, matchId, userId, username, content, createdAt }` + +**Matchmaking:** +- `match_request_received` - Someone wants to match + - Payload: `{ matchId, fromUser }` +- `match_accepted` - Match request accepted + - Payload: `{ matchId, partner }` + +**WebRTC Signaling:** +- `webrtc_offer` - Received SDP offer from partner +- `webrtc_answer` - Received SDP answer from partner +- `webrtc_ice_candidate` - Received ICE candidate from partner + +--- + +## WebRTC P2P Architecture + +### Components + +**RTCPeerConnection:** +- Manages P2P connection between two browsers +- Handles ICE candidate gathering +- Manages connection state (new, connecting, connected, failed) + +**RTCDataChannel:** +- Binary data transfer channel +- Ordered, reliable delivery (like TCP) +- Max message size: 16KB-64KB (browser dependent) +- Used for video file chunks + +**STUN Server:** +- Public STUN server (e.g., Google: `stun:stun.l.google.com:19302`) +- Discovers public IP address +- Helps with NAT traversal + +**TURN Server (Optional):** +- Relay server for difficult NAT/firewall scenarios +- Only ~10% of connections need TURN +- Can use free services or self-host + +### File Transfer Flow + +**1. Initiate Connection:** +```javascript +// Sender creates offer +const pc = new RTCPeerConnection({ iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] }); +const dataChannel = pc.createDataChannel('fileTransfer'); +const offer = await pc.createOffer(); +await pc.setLocalDescription(offer); +// Send offer to receiver via Socket.IO +socket.emit('webrtc_offer', { matchId, offer }); +``` + +**2. Exchange SDP/ICE:** +```javascript +// Receiver receives offer via Socket.IO +socket.on('webrtc_offer', async ({ offer }) => { + await pc.setRemoteDescription(offer); + const answer = await pc.createAnswer(); + await pc.setLocalDescription(answer); + socket.emit('webrtc_answer', { matchId, answer }); +}); + +// Both peers exchange ICE candidates +pc.onicecandidate = (event) => { + if (event.candidate) { + socket.emit('webrtc_ice_candidate', { matchId, candidate: event.candidate }); + } +}; +``` + +**3. Transfer File:** +```javascript +// Chunk file and send +const CHUNK_SIZE = 16384; // 16KB +const file = selectedFile; +const totalChunks = Math.ceil(file.size / CHUNK_SIZE); + +// Send metadata first +dataChannel.send(JSON.stringify({ + type: 'metadata', + name: file.name, + size: file.size, + mimeType: file.type, + totalChunks +})); + +// Send chunks +for (let i = 0; i < totalChunks; i++) { + const start = i * CHUNK_SIZE; + const end = Math.min(start + CHUNK_SIZE, file.size); + const chunk = file.slice(start, end); + const arrayBuffer = await chunk.arrayBuffer(); + dataChannel.send(arrayBuffer); + + // Update progress + const progress = ((i + 1) / totalChunks) * 100; + setTransferProgress(progress); +} +``` + +**4. Receive File:** +```javascript +// Receiver assembles chunks +let receivedChunks = []; +let metadata = null; + +dataChannel.onmessage = (event) => { + if (typeof event.data === 'string') { + // Metadata + metadata = JSON.parse(event.data); + } else { + // Chunk + receivedChunks.push(event.data); + + if (receivedChunks.length === metadata.totalChunks) { + // All chunks received, create file + const blob = new Blob(receivedChunks, { type: metadata.mimeType }); + const url = URL.createObjectURL(blob); + // Trigger download + const a = document.createElement('a'); + a.href = url; + a.download = metadata.name; + a.click(); + } + } +}; +``` + +### Error Handling + +**Connection Failed:** +- Fallback to link sharing (Google Drive, Dropbox) +- Show user-friendly error message +- Log error for debugging + +**Transfer Interrupted:** +- Detect connection state change +- Offer retry option +- Consider implementing resume capability (future) + +--- + +## Security + +### Backend Security + +**Authentication:** +- bcrypt for password hashing (salt rounds: 10-12) +- JWT for session management (httpOnly cookies recommended) +- Token expiration (e.g., 24 hours) +- Refresh token mechanism (optional) + +**API Security:** +- Rate limiting (express-rate-limit) +- Helmet.js for security headers +- CORS configuration (allow only frontend origin) +- Input validation (express-validator) +- SQL injection prevention (prepared statements, ORM) +- XSS prevention (sanitize user input) + +### Frontend Security + +**Storage:** +- JWT in httpOnly cookie (recommended) OR secure localStorage +- Never store passwords +- Clear sensitive data on logout + +**Input Validation:** +- Client-side validation for UX +- Server-side validation for security +- Sanitize before displaying user content + +### WebRTC Security + +**Native Encryption:** +- DTLS (Datagram Transport Layer Security) for data channels +- SRTP (Secure Real-time Transport Protocol) for media +- Enabled by default, no configuration needed + +**Additional Measures:** +- Verify signaling server (HTTPS + WSS) +- Optional: end-to-end encryption for chat (WebCrypto API, libsodium) +- No video files stored on server + +--- + +## Deployment Architecture (Future) + +### Production Stack + +**Option 1: Single VPS** +- Ubuntu/Debian server +- Docker Compose +- nginx as reverse proxy + SSL (Let's Encrypt) +- PostgreSQL on same server +- Backup strategy + +**Option 2: Cloud (Recommended)** +- Frontend: Vercel/Netlify (CDN, auto-scaling) +- Backend: AWS EC2/DigitalOcean/Render +- Database: AWS RDS/DigitalOcean Managed PostgreSQL +- nginx on backend for API +- Redis for session storage (optional) + +**Option 3: Kubernetes (Overkill for MVP)** +- GKE/EKS/AKS +- Helm charts +- Auto-scaling +- Load balancing + +### SSL/TLS + +**Let's Encrypt:** +- Free SSL certificates +- Auto-renewal with Certbot +- Required for WebRTC (getUserMedia requires HTTPS) + +### Environment Variables + +**Backend:** +```env +NODE_ENV=production +PORT=3000 +DATABASE_URL=postgresql://user:pass@host:5432/dbname +JWT_SECRET=random-secret-key +CORS_ORIGIN=https://spotlight.cam +STUN_SERVER=stun:stun.l.google.com:19302 +TURN_SERVER=turn:your-turn-server.com (optional) +``` + +**Frontend:** +```env +VITE_API_URL=https://api.spotlight.cam +VITE_WS_URL=wss://api.spotlight.cam +``` + +--- + +## Performance Considerations + +### Frontend +- Code splitting (React.lazy) +- Image optimization +- Service worker caching (PWA) +- Minimize bundle size + +### Backend +- Database connection pooling +- Query optimization (indexes) +- Caching (Redis for frequently accessed data) +- Compression (gzip/brotli) + +### WebRTC +- Adaptive chunk size based on bandwidth +- Buffer management (avoid overwhelming DataChannel) +- Connection quality monitoring +- Automatic reconnection on failure + +--- + +## Monitoring & Logging (Future) + +**Backend:** +- Winston/Pino for logging +- Log levels: error, warn, info, debug +- Structured logging (JSON format) + +**Database:** +- Query performance monitoring +- Slow query log +- Connection pool metrics + +**WebRTC:** +- Connection success rate +- Transfer speed metrics +- Failure reasons +- Browser compatibility stats + +--- + +**Last Updated:** 2025-11-12 diff --git a/docs/COMPLETED.md b/docs/COMPLETED.md new file mode 100644 index 0000000..49a9c6e --- /dev/null +++ b/docs/COMPLETED.md @@ -0,0 +1,225 @@ +# Completed Tasks - spotlight.cam + +**Archive of completed tasks - for reference only** + +--- + +## ✅ Phase 0: Frontend Mockup (COMPLETED) + +**Completed:** 2025-11-12 +**Status:** Ready for presentation and UX testing + +--- + +## 🐳 1. Setup projektu i infrastruktura + +### Docker Compose +- [x] ✅ Utworzenie `docker-compose.yml` z serwisem nginx +- [x] ✅ Konfiguracja kontenera frontend (React/Vite) +- [x] ✅ Konfiguracja sieci między kontenerami +- [x] ✅ nginx proxy config (port 8080, WebSocket support) + +### Struktura projektu +- [x] ✅ Inicjalizacja projektu frontend (React + Vite + Tailwind) +- [x] ✅ Utworzenie `.gitignore` +- [x] ✅ Konfiguracja ESLint (frontend) +- [x] ✅ Fix Tailwind CSS v4 compatibility issue (downgraded to v3.4.0) + +--- + +## 🎨 6. Frontend - PWA (React + Vite + Tailwind) + +### Setup PWA +- [x] ✅ Konfiguracja Vite +- [x] ✅ Konfiguracja Tailwind CSS v3.4.0 +- [x] ✅ Konfiguracja custom color scheme (primary-600, etc.) + +### Routing +- [x] ✅ Setup React Router +- [x] ✅ Ochrona tras (require authentication) +- [x] ✅ Redirect logic (logged in → /events, logged out → /login) + +### Widoki/Komponenty +- [x] ✅ **Logowanie** (`/login`) - Formularz email + hasło, link do rejestracji +- [x] ✅ **Rejestracja** (`/register`) - Formularz username, email, hasło, walidacja +- [x] ✅ **Wybór eventu** (`/events`) - Lista eventów, informacje (location, dates, participants), przycisk "Join chat" +- [x] ✅ **Czat eventowy** (`/events/:id/chat`) - Lista wiadomości, aktywni użytkownicy (sidebar), matchmaking (UserPlus button), auto-scroll +- [x] ✅ **Czat 1:1** (`/matches/:id/chat`) - Profil partnera (header), czat, **mockup WebRTC transfer** (file select, progress bar, status indicator), link sharing fallback, "End & rate" button +- [x] ✅ **Ocena partnera** (`/matches/:id/rate`) - Gwiazdki 1-5 (interactive), komentarz (textarea), checkbox "Would collaborate again", submit button +- [x] ✅ **Historia współprac** (`/history`) - Lista matchów (cards), partner info, rating stars, date, status badge, "View details" buttons + +### Komponenty reużywalne +- [x] ✅ `` - nawigacja (logo, links: Events, History, Logout), responsive, active link styling +- [x] ✅ `` - wrapper dla stron (container max-w-7xl, padding, Navbar integration) + +### Stylowanie (Tailwind) +- [x] ✅ Konfiguracja motywu kolorystycznego (primary, secondary, gray scale) +- [x] ✅ Responsive design (mobile-first) +- [x] ✅ Hover states, transitions, shadows +- [x] ✅ Form styling (inputs, buttons, focus states) + +### State Management +- [x] ✅ Auth state (Context API - current user, mock login/logout) +- [x] ✅ Mock authentication with localStorage persistence +- [x] ✅ Protected routes based on auth state + +--- + +## 🎥 5. WebRTC - Peer-to-Peer Transfer Filmów (MOCKUP) + +### Fallback - wymiana linków +- [x] ✅ UI do wklejenia linku do filmu (Google Drive, Dropbox, itp.) +- [x] ✅ Walidacja URL (type="url" in input) +- [x] ✅ Wysłanie linku przez czat (mockup) + +### WebRTC UI Mockup +- [x] ✅ File input for video selection (`accept="video/*"`) +- [x] ✅ File validation (video type check) +- [x] ✅ WebRTC connection status indicator (disconnected, connecting, connected, failed) +- [x] ✅ Transfer progress bar (simulated 0-100%) +- [x] ✅ File metadata display (name, size in MB) +- [x] ✅ Cancel transfer button +- [x] ✅ Send video button (P2P) +- [x] ✅ Status messages ("Connected (P2P)", "E2E Encrypted (DTLS/SRTP)") +- [x] ✅ Info box explaining WebRTC functionality + +--- + +## 📚 9. Dokumentacja + +- [x] ✅ README.md - instrukcja uruchomienia projektu (Docker commands, ports, mock login) +- [x] ✅ QUICKSTART.md - szybki start (2 minuty, step-by-step) +- [x] ✅ CONTEXT.md - architektura i założenia projektu (full description, user flow, tech stack, dev guidelines) +- [x] ✅ TODO.md - roadmap projektu (11 sections, phase breakdown, next steps) +- [x] ✅ Development Guidelines in CONTEXT.md (English code, Polish communication, Git commit format) + +--- + +## 🎯 Mock Data + +### Mock Users +- [x] ✅ john_doe (current user) +- [x] ✅ sarah_swing +- [x] ✅ mike_blues +- [x] ✅ anna_balboa +- [x] ✅ tom_lindy +- [x] ✅ All users have: id, username, email, avatar, rating, matches_count + +### Mock Events +- [x] ✅ Warsaw Dance Festival 2025 +- [x] ✅ Swing Camp Barcelona 2025 +- [x] ✅ Blues Week Herräng 2025 +- [x] ✅ All events have: id, name, location, dates, worldsdc_id, participants, description + +### Mock Messages +- [x] ✅ Event messages (public chat) +- [x] ✅ Private messages (1:1 chat) +- [x] ✅ All messages have: id, room_id, user_id, username, avatar, content, type, created_at + +### Mock Matches +- [x] ✅ Match history with different statuses +- [x] ✅ Partner info, event, date, status + +### Mock Ratings +- [x] ✅ Ratings with scores, comments, would_collaborate_again flag +- [x] ✅ Linked to matches and users + +--- + +## 🐛 Bug Fixes + +### Tailwind CSS v4 Compatibility Issue +**Problem:** +- Error: "It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin" +- Tailwind v4 has breaking changes with Vite setup + +**Solution:** +- Downgraded to Tailwind CSS v3.4.0 +- Command: `npm install -D tailwindcss@^3.4.0` +- Rebuilt Docker container without cache +- Verified working at http://localhost:8080 + +**Date:** 2025-11-12 + +### Port 80 Already Allocated +**Problem:** +- Docker error: "Bind for 0.0.0.0:80 failed: port is already allocated" + +**Solution:** +- Changed nginx port from 80 to 8080 in docker-compose.yml +- Updated all documentation to reference port 8080 +- Access: http://localhost:8080 + +**Date:** 2025-11-12 + +--- + +## 🌍 Localization + +- [x] ✅ Changed all UI text from Polish to English +- [x] ✅ Updated placeholders in forms +- [x] ✅ Updated button labels +- [x] ✅ Updated page titles and headers +- [x] ✅ Updated error messages and alerts +- [x] ✅ Updated mock data content +- [x] ✅ Changed date formatting locale from 'pl-PL' to 'en-US' +- [x] ✅ Restarted frontend container to apply changes + +**Date:** 2025-11-12 + +--- + +## 📝 Git Commits + +### Commit 1: Initial project setup +``` +feat: initial project setup with frontend mockup + +- Add Docker Compose with nginx and frontend services +- Initialize React + Vite + Tailwind CSS frontend +- Implement all pages: Login, Register, Events, Event Chat, Match Chat, Rate, History +- Add mock authentication with Context API +- Add mock data for users, events, messages, matches, ratings +- Create WebRTC P2P video transfer UI mockup +- Add project documentation (README, QUICKSTART, CONTEXT, TODO) +``` +**Date:** 2025-11-12 + +### Commit 2: Update TODO.md +``` +docs: update TODO.md with completed tasks and next steps + +- Mark Phase 0 (Frontend Mockup) as completed +- Add current project status section (25% complete) +- Add detailed next steps for Phase 1 (Backend Foundation) +- Add time estimates for each step +- Add learning resources section +``` +**Date:** 2025-11-12 + +--- + +## 📊 Statistics + +**Frontend:** +- 7 pages implemented +- 2 layout components +- 1 context (AuthContext) +- 5 mock data files +- ~1,500 lines of React code + +**Docker:** +- 2 services (nginx, frontend) +- 1 network +- 2 volume mounts + +**Documentation:** +- 4 markdown files (README, QUICKSTART, CONTEXT, TODO) +- ~1,200 lines of documentation + +**Total Development Time:** ~8-10 hours + +--- + +**Last Updated:** 2025-11-12 +**Note:** This file is an archive. For current tasks, see TODO.md diff --git a/docs/CONTEXT.md b/docs/CONTEXT.md index f58e76d..3ea83fb 100644 --- a/docs/CONTEXT.md +++ b/docs/CONTEXT.md @@ -1,188 +1,136 @@ +# spotlight.cam - Project Context -# spotlight.cam +**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. -Stworzyć aplikację umożliwiającą peer-to-peer przesyłanie nagrań wideo między użytkownikami, nawet gdy znajdują się na różnych platformach (Android/iOS), z szyfrowaniem end-to-end, minimalnym udziałem backendu i opcjonalnym czatem tekstowym. +Główna funkcjonalność: **WebRTC P2P video file transfer** (nie wymiana linków - to tylko fallback). -✅ Projekt zakłada pełne wsparcie dla Android/iOS (przez przeglądarkę), bez hostowania plików, z backendem i frontendem działającym w ramach Docker Compose. +✅ Pełne wsparcie dla Android/iOS (przez przeglądarkę), bez hostowania plików, z backendem i frontendem działającym w ramach Docker Compose. -🧱 ETAPY WDROŻENIA -1. 🔍 Analiza technologii i wymagań +--- - Zidentyfikuj ograniczenia platform: Android, iOS (szczególnie iOS WebView vs Safari). - - Sprawdź kompatybilność WebRTC na poziomie przeglądarki (getUserMedia, RTCPeerConnection, RTCDataChannel). - - Określ typy danych do przesyłania: pliki wideo (MP4), wiadomości tekstowe, metadane. - - Zdecyduj, czy to aplikacja webowa (PWA) czy natywna (Flutter/React Native). - - Oszacuj maksymalny rozmiar plików i czas transferu. - -2. 🧠 Projekt architektury systemu -🔗 Połączenie WebRTC - - Użyj RTCPeerConnection + RTCDataChannel do przesyłania wideo. - - Zaimplementuj STUN i opcjonalnie TURN (np. Google STUN, własny TURN przy złych NAT-ach). - -☁️ Serwer sygnalizacyjny (Signaling) - - Stwórz prosty backend (np. Node.js + Express + WebSocket) do wymiany SDP/ICE. - - Alternatywnie: pozwól użytkownikom przekazywać dane ręcznie (przez QR/link/komunikator). - -📤 Przesyłanie danych - - Skorzystaj z RTCDataChannel do przesyłania plików binarnych (Blob/FileReader). - - Podziel pliki na fragmenty (chunking), monitoruj postęp. - -3. 🔐 Bezpieczeństwo i prywatność -🔒 Szyfrowanie - - Potwierdź, że WebRTC już szyfruje (DTLS/SRTP). - - Zaszyfruj czat tekstowy: np. z użyciem libsodium, Signal Protocol lub WebCrypto. - - Nie przechowuj żadnych plików na serwerze — tylko wymiana sygnalizacyjna. - -🔄 Wymiana danych sygnalizacyjnych - - Dodaj 2 tryby: - -QR code + ręczne skanowanie - -Link generowany przez jedną stronę i wklejany przez drugą - -Kodowanie - - Zserializuj offer (SDP) do JSON → Base64 → QR/link. - - Po stronie odbiorcy: parsuj i odpowiadaj answer przez podobny kanał. - -6. 🧪 UX i potwierdzenia - - Pokaż komunikaty typu: - -„Czekam na połączenie…” - -„Połączenie nawiązane z użytkownikiem” - -„Trwa przesyłanie: 87%” - - Po zakończeniu przesyłania: „Plik otrzymany”, przycisk „Zapisz”. - ## 🧠 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). -- 💬 Czat + matchmaking: użytkownicy rejestrują się, wybierają event, trafiają na czat eventowy, łączą się w pary. -- 🤝 1:1: po potwierdzeniu – para znika z czatu publicznego i przechodzi do prywatnego. -- 📦 Docker Compose: całość uruchamiana w kontenerach. -- 📱 Frontend: PWA – działa mobilnie i na desktopie. +- 🔒 **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 -Zestaw trzech kontenerów: -- `frontend`: PWA (React/Vite/Tailwind) -- `backend`: Node.js/Express/Socket.IO +**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 +--- -- `users`: identyfikacja, event, dostępność -- `events`: lista eventów z worldsdc.com -- `chat_rooms`: publiczne i prywatne pokoje +## 🗃️ 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 +- `ratings`: oceny po wymianie nagraniami (1-5, komentarz) + +--- ## 🔁 Flow użytkownika -1. Rejestracja użytkownika -2. Wybór eventu (lista z worldsdc.com) na którym użytkownik jest. -3. Czat ogólny dla eventu – matchmaking. -4. Potwierdzenie: przejście do prywatnego czatu 1:1. -5. **Wybór pliku wideo z galerii urządzenia** (nagranie odbywa się poza aplikacją). -6. **Przesłanie filmu bezpośrednio przez WebRTC** (peer-to-peer, bez serwera). Opcjonalnie: wymiana linków (np. Google Drive). -7. Po wymianie nagraniami – ocena partnera (1–5, komentarz, chęć ponownej współpracy). +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) -## 💬 Frontend (PWA) +--- -Zbudowany np. w: -- React + Vite + Tailwind -- lub SvelteKit / SolidStart +## 💬 Tech Stack -Widoki: -- Logowanie / Rejestracja -- Wybór eventu -- Czat eventowy -- Profil partnera -- Czat 1:1 -- Ocena partnera -- Historia współprac +### 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 -- Hasła haszowane (bcrypt). -- **WebRTC zapewnia natywne szyfrowanie** (DTLS/SRTP) dla transferu P2P. -- **Opcjonalne dodatkowe szyfrowanie czatu** tekstowego (WebCrypto/libsodium). -- Brak przechowywania nagrań na serwerze – tylko sygnalizacja WebRTC. -- Możliwość zgłaszania użytkownika. +**Backend:** +- Hasła haszowane (bcrypt) +- JWT authentication +- Rate limiting, CORS, Helmet.js +- Input validation & sanitization -## 📹 WebRTC P2P Transfer Filmów (główna funkcjonalność) +**Frontend:** +- XSS prevention +- Secure token storage +- HTTPS required -### Komponenty: -- **RTCPeerConnection**: nawiązanie połączenia P2P między użytkownikami -- **RTCDataChannel**: kanał do transferu danych binarnych (pliki wideo) -- **Chunking**: podział dużych plików wideo na fragmenty (np. 16KB chunks) -- **Progress monitoring**: śledzenie postępu wysyłania/odbierania (pasek postępu) -- **STUN/TURN**: serwery do przejścia przez NAT/firewall - -### Flow transferu: -1. Użytkownik wybiera plik wideo z galerii urządzenia (``) -2. Nawiązanie połączenia WebRTC między parą użytkowników (przez serwer sygnalizacyjny WebSocket) -3. Otwarcie RTCDataChannel -4. Wysłanie metadanych: nazwa pliku, rozmiar, typ MIME -5. Podział pliku na chunki i przesłanie przez DataChannel -6. Odbieranie chunków i składanie w całość (Blob) -7. Po zakończeniu: zapis pliku w pamięci urządzenia odbiorcy - -### Fallback: -- Jeśli WebRTC nie zadziała (problemy z NAT, firewall), użytkownik może wymienić się linkami do filmów (Google Drive, Dropbox, itp.) - -## ➕ Opcjonalne rozszerzenia - -- System oznaczeń zaufania (badge). -- Blokowanie użytkowników. -- Publiczne profile z opiniami. -- Powiadomienia push. +**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**: **angielski** -- **Nazwy zmiennych, funkcji, klas**: **angielski** -- **Dokumentacja techniczna w kodzie (JSDoc, docstrings)**: **angielski** +- **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**: **polski** -- **Dokumentacja projektowa (CONTEXT.md, README.md)**: **polski** (może być mieszana z angielskim dla części technicznych) +- **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 dobrego commita: `feat: add WebRTC P2P video transfer mockup` -- Przykład złego commita: ~~`feat: add video transfer (generated by AI)`~~ +- **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 +### Przykład kodu ```jsx // ✅ Poprawnie - kod po angielsku const sendMessage = (message) => { @@ -190,7 +138,6 @@ const sendMessage = (message) => { alert('Please enter a message'); return; } - // Send message via WebSocket socket.emit('message', message); }; @@ -202,4 +149,21 @@ const wyslijWiadomosc = (wiadomosc) => { } socket.emit('wiadomosc', wiadomosc); }; -``` \ No newline at end of file +``` + +--- + +## 📚 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 diff --git a/docs/RESOURCES.md b/docs/RESOURCES.md new file mode 100644 index 0000000..91aee75 --- /dev/null +++ b/docs/RESOURCES.md @@ -0,0 +1,294 @@ +# Resources - spotlight.cam + +**Learning resources, documentation links, and useful references** + +--- + +## 📚 Official Documentation + +### Backend (Node.js + Express) +- **Express.js** - https://expressjs.com/ + - Best practices: https://expressjs.com/en/advanced/best-practice-performance.html + - Security: https://expressjs.com/en/advanced/best-practice-security.html +- **Node.js** - https://nodejs.org/docs/ +- **Socket.IO** - https://socket.io/docs/v4/ + - Rooms: https://socket.io/docs/v4/rooms/ + - Emit cheatsheet: https://socket.io/docs/v4/emit-cheatsheet/ + +### Database +- **PostgreSQL** - https://www.postgresql.org/docs/ + - Best practices: https://wiki.postgresql.org/wiki/Don't_Do_This + - Performance tips: https://wiki.postgresql.org/wiki/Performance_Optimization +- **Prisma** - https://www.prisma.io/docs + - Schema reference: https://www.prisma.io/docs/concepts/components/prisma-schema + - Migrations: https://www.prisma.io/docs/concepts/components/prisma-migrate +- **Knex.js** - https://knexjs.org/ + - Migrations: https://knexjs.org/guide/migrations.html + +### Frontend +- **React** - https://react.dev/ + - Hooks: https://react.dev/reference/react + - Context: https://react.dev/reference/react/useContext +- **Vite** - https://vitejs.dev/ + - Config: https://vitejs.dev/config/ + - Env variables: https://vitejs.dev/guide/env-and-mode.html +- **Tailwind CSS** - https://tailwindcss.com/docs + - Configuration: https://tailwindcss.com/docs/configuration + - Customization: https://tailwindcss.com/docs/theme +- **React Router** - https://reactrouter.com/en/main + - Protected routes: https://reactrouter.com/en/main/start/tutorial#adding-a-loader + +### Docker +- **Docker Compose** - https://docs.docker.com/compose/ + - Compose file reference: https://docs.docker.com/compose/compose-file/ + - Networking: https://docs.docker.com/compose/networking/ +- **nginx** - https://nginx.org/en/docs/ + - Reverse proxy: https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/ + - WebSocket: https://nginx.org/en/docs/http/websocket.html + +--- + +## 🎥 WebRTC Resources + +### Getting Started +- **WebRTC.org** - https://webrtc.org/ + - Getting started: https://webrtc.org/getting-started/overview + - Use cases: https://webrtc.org/getting-started/use-cases +- **MDN WebRTC API** - https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API + - RTCPeerConnection: https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection + - RTCDataChannel: https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel + - Simple peer-to-peer data: https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Simple_RTCDataChannel_sample + +### Tutorials +- **WebRTC samples** - https://webrtc.github.io/samples/ + - File transfer sample: https://webrtc.github.io/samples/src/content/datachannel/filetransfer/ + - Basic RTCDataChannel: https://webrtc.github.io/samples/src/content/datachannel/basic/ +- **HTML5 Rocks - WebRTC** - https://www.html5rocks.com/en/tutorials/webrtc/basics/ + +### Advanced Topics +- **STUN/TURN Servers** + - Understanding STUN/TURN: https://bloggeek.me/webrtcglossary/stun/ + - Free STUN servers: https://gist.github.com/mondain/b0ec1cf5f60ae726202e + - Coturn (self-hosted TURN): https://github.com/coturn/coturn +- **NAT Traversal** + - ICE explained: https://bloggeek.me/webrtcglossary/ice/ + - Trickle ICE: https://webrtc.org/getting-started/trickle-ice +- **WebRTC for the Curious** (free book) - https://webrtcforthecurious.com/ + +--- + +## 🔐 Security Resources + +### Authentication +- **JWT** - https://jwt.io/ + - Introduction: https://jwt.io/introduction + - Debugger: https://jwt.io/#debugger-io + - Best practices: https://curity.io/resources/learn/jwt-best-practices/ +- **bcrypt** - https://github.com/kelektiv/node.bcrypt.js + - How bcrypt works: https://auth0.com/blog/hashing-in-action-understanding-bcrypt/ + +### General Security +- **OWASP Top 10** - https://owasp.org/www-project-top-ten/ +- **Helmet.js** - https://helmetjs.github.io/ +- **express-rate-limit** - https://github.com/express-rate-limit/express-rate-limit +- **express-validator** - https://express-validator.github.io/docs/ +- **CORS** - https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS + +### WebRTC Security +- **WebRTC Security** - https://webrtc-security.github.io/ +- **DTLS/SRTP** - https://webrtc.org/getting-started/security + +--- + +## 🧪 Testing Resources + +### Backend Testing +- **Jest** - https://jestjs.io/ + - Getting started: https://jestjs.io/docs/getting-started + - API testing: https://jestjs.io/docs/testing-asynchronous-code +- **Supertest** - https://github.com/ladjs/supertest + - Express testing guide: https://github.com/ladjs/supertest#example + +### Frontend Testing +- **Vitest** - https://vitest.dev/ + - Getting started: https://vitest.dev/guide/ +- **React Testing Library** - https://testing-library.com/react + - Cheatsheet: https://testing-library.com/docs/react-testing-library/cheatsheet/ +- **Playwright** - https://playwright.dev/ + - Getting started: https://playwright.dev/docs/intro +- **Cypress** - https://www.cypress.io/ + - Getting started: https://docs.cypress.io/guides/getting-started/installing-cypress + +--- + +## 📱 PWA Resources + +### Service Workers +- **MDN Service Worker API** - https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API +- **Workbox** - https://developers.google.com/web/tools/workbox + - Getting started: https://developers.google.com/web/tools/workbox/guides/get-started + +### PWA Features +- **Vite PWA Plugin** - https://vite-pwa-org.netlify.app/ + - Guide: https://vite-pwa-org.netlify.app/guide/ +- **Web App Manifest** - https://developer.mozilla.org/en-US/docs/Web/Manifest +- **Web Push Notifications** - https://developer.mozilla.org/en-US/docs/Web/API/Push_API + +--- + +## 🚀 Deployment Resources + +### Cloud Platforms +- **Vercel** - https://vercel.com/docs + - React deployment: https://vercel.com/docs/frameworks/vite +- **Netlify** - https://docs.netlify.com/ +- **Render** - https://render.com/docs +- **DigitalOcean** - https://docs.digitalocean.com/ + - App Platform: https://docs.digitalocean.com/products/app-platform/ + - Droplets: https://docs.digitalocean.com/products/droplets/ +- **AWS** - https://aws.amazon.com/getting-started/ + - EC2: https://docs.aws.amazon.com/ec2/ + - RDS: https://docs.aws.amazon.com/rds/ + +### SSL/TLS +- **Let's Encrypt** - https://letsencrypt.org/ + - Certbot: https://certbot.eff.org/ + - Documentation: https://letsencrypt.org/docs/ + +### Docker Production +- **Docker Production Best Practices** - https://docs.docker.com/develop/dev-best-practices/ +- **Multi-stage builds** - https://docs.docker.com/build/building/multi-stage/ + +--- + +## 🎓 Video Tutorials + +### WebRTC +- **WebRTC Crash Course** - https://www.youtube.com/watch?v=WmR9IMUD_CY (Traversy Media) +- **WebRTC File Transfer** - https://www.youtube.com/watch?v=WmR9IMUD_CY +- **Build a Video Chat App** - https://www.youtube.com/watch?v=DvlyzDZDEq4 (Fireship) + +### MERN Stack (Similar to our stack) +- **MERN Stack Tutorial** - https://www.youtube.com/watch?v=7CqJlxBYj-M (freeCodeCamp) +- **Socket.IO Tutorial** - https://www.youtube.com/watch?v=ZKEqqIO7n-k (Web Dev Simplified) + +### React +- **React Course for Beginners** - https://www.youtube.com/watch?v=bMknfKXIFA8 (freeCodeCamp) +- **React Hooks** - https://www.youtube.com/watch?v=O6P86uwfdR0 (Codevolution) + +--- + +## 📦 Useful npm Packages + +### Backend +- **express** - Web framework +- **socket.io** - WebSocket library +- **@prisma/client** / **knex** - Database ORM/query builder +- **bcryptjs** - Password hashing +- **jsonwebtoken** - JWT authentication +- **dotenv** - Environment variables +- **helmet** - Security headers +- **express-rate-limit** - Rate limiting +- **express-validator** - Input validation +- **cors** - CORS middleware +- **winston** / **pino** - Logging +- **nodemon** - Dev server auto-restart + +### Frontend +- **react** - UI library +- **react-dom** - React DOM renderer +- **react-router-dom** - Routing +- **socket.io-client** - Socket.IO client +- **lucide-react** - Icons (already using) +- **react-hook-form** - Form handling +- **zod** - Schema validation +- **axios** - HTTP client + +### Testing +- **jest** - Testing framework +- **supertest** - HTTP testing +- **vitest** - Vite-native testing +- **@testing-library/react** - React component testing +- **@testing-library/user-event** - User interaction simulation +- **playwright** / **cypress** - E2E testing + +--- + +## 🛠️ Development Tools + +### API Development +- **Postman** - https://www.postman.com/ +- **Insomnia** - https://insomnia.rest/ +- **Thunder Client** (VS Code extension) - https://www.thunderclient.com/ + +### Database Tools +- **pgAdmin** - https://www.pgadmin.org/ +- **DBeaver** - https://dbeaver.io/ +- **Prisma Studio** - Built-in with Prisma + +### WebRTC Testing +- **Trickle ICE** - https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/ +- **WebRTC Troubleshooter** - https://test.webrtc.org/ + +### Performance +- **Lighthouse** - Chrome DevTools +- **WebPageTest** - https://www.webpagetest.org/ + +--- + +## 📖 Articles & Guides + +### WebRTC +- **WebRTC File Transfer with Progress** - https://bloggeek.me/webrtc-file-transfer/ +- **Understanding WebRTC Data Channels** - https://bloggeek.me/webrtc-data-channel/ +- **WebRTC for Real-World Applications** - https://webrtchacks.com/ + +### Socket.IO +- **Socket.IO Best Practices** - https://socket.io/docs/v4/performance-tuning/ +- **Scaling Socket.IO** - https://socket.io/docs/v4/using-multiple-nodes/ + +### Authentication +- **JWT Authentication Best Practices** - https://blog.logrocket.com/jwt-authentication-best-practices/ +- **Session vs Token Authentication** - https://security.stackexchange.com/questions/81756/session-authentication-vs-token-authentication + +### Docker +- **Docker for Node.js Developers** - https://nodejs.org/en/docs/guides/nodejs-docker-webapp/ +- **Docker Compose for Development** - https://docs.docker.com/compose/gettingstarted/ + +--- + +## 🌐 Community + +### Forums +- **Stack Overflow** - https://stackoverflow.com/ + - Tag: [webrtc] - https://stackoverflow.com/questions/tagged/webrtc + - Tag: [react] - https://stackoverflow.com/questions/tagged/react + - Tag: [node.js] - https://stackoverflow.com/questions/tagged/node.js + +### Discord/Slack +- **Reactiflux** (React community) - https://www.reactiflux.com/ +- **Node.js Discord** - https://discord.com/invite/nodejs + +### Reddit +- **/r/webdev** - https://www.reddit.com/r/webdev/ +- **/r/reactjs** - https://www.reddit.com/r/reactjs/ +- **/r/node** - https://www.reddit.com/r/node/ + +--- + +## 📚 Recommended Reading + +### Books +- **Node.js Design Patterns** - Mario Casciaro +- **Learning WebRTC** - Dan Ristic +- **React Up & Running** - Stoyan Stefanov + +### Blogs +- **webrtcHacks** - https://webrtchacks.com/ +- **BlogGeek.me** - https://bloggeek.me/ (WebRTC expert) +- **Kent C. Dodds** - https://kentcdodds.com/blog (React expert) + +--- + +**Last Updated:** 2025-11-12 +**Note:** Links verified as of last update. Some may change over time. diff --git a/docs/SESSION_CONTEXT.md b/docs/SESSION_CONTEXT.md new file mode 100644 index 0000000..b3b8c60 --- /dev/null +++ b/docs/SESSION_CONTEXT.md @@ -0,0 +1,285 @@ +# Session Context - spotlight.cam + +**Quick reference for resuming development sessions - optimized for minimal token usage** + +--- + +## Project Overview + +**Name:** spotlight.cam +**Purpose:** P2P video exchange app for dance event participants +**Main Feature:** WebRTC P2P video file transfer (no server storage) +**Tech Stack:** React + Vite + Tailwind | Node.js + Express + Socket.IO | PostgreSQL 15 | Docker Compose + +--- + +## Current Status + +**Phase:** 0 (Frontend Mockup) - ✅ COMPLETED +**Progress:** ~25% +**Next Goal:** Phase 1 - Backend Foundation (Node.js + PostgreSQL + Auth + WebSocket) + +### What Works Now +- ✅ Docker Compose (nginx:8080 + frontend) +- ✅ All frontend views with mockups +- ✅ Mock authentication (localStorage) +- ✅ WebRTC P2P transfer UI mockup + +### What's Missing +- ⏳ Backend API (Node.js + Express) +- ⏳ PostgreSQL database + schema +- ⏳ Real authentication (JWT) +- ⏳ Real-time chat (Socket.IO) +- ⏳ Actual WebRTC implementation + +--- + +## Tech Stack + +**Infrastructure:** +- Docker Compose (nginx, frontend, backend planned, db planned) +- nginx reverse proxy on port 8080 + +**Frontend:** +- React 18 + Vite +- Tailwind CSS v3.4.0 (NOT v4 - compatibility issues) +- React Router +- Context API for state + +**Backend (planned):** +- Node.js + Express +- Socket.IO for WebSocket +- PostgreSQL 15 +- bcrypt + JWT + +**WebRTC:** +- RTCPeerConnection +- RTCDataChannel (file transfer) +- Chunking (16KB chunks) +- STUN/TURN servers + +--- + +## Project Structure + +``` +/spotlightcam +├── docker-compose.yml # nginx + frontend (backend + db planned) +├── nginx/ # Proxy config +├── frontend/ # React PWA +│ ├── src/ +│ │ ├── pages/ # All views (Login, Register, Events, Chat, Match, Rate, History) +│ │ ├── contexts/ # AuthContext (mock) +│ │ ├── components/ # Layout, Navbar +│ │ └── mocks/ # Mock data (users, events, messages, matches) +├── backend/ # NOT CREATED YET +└── docs/ + ├── SESSION_CONTEXT.md # This file + ├── CONTEXT.md # Full project description + ├── TODO.md # Task list + ├── ARCHITECTURE.md # Technical details + ├── COMPLETED.md # Completed tasks archive + └── RESOURCES.md # Learning resources +``` + +--- + +## Key Files + +**Frontend:** +- `frontend/src/pages/MatchChatPage.jsx` - Main WebRTC mockup (file select, transfer progress) +- `frontend/src/contexts/AuthContext.jsx` - Mock auth with localStorage +- `frontend/src/mocks/` - All mock data + +**Config:** +- `docker-compose.yml` - nginx on 8080, frontend on 5173 (internal) +- `nginx/conf.d/default.conf` - Proxy config, WebSocket support for Vite HMR +- `frontend/tailwind.config.js` - Tailwind v3.4.0 config + +--- + +## Database Schema (Planned) + +6 tables: +- `users` - id, username, email, password_hash, created_at +- `events` - id, name, location, start_date, end_date, worldsdc_id +- `chat_rooms` - id, event_id, type (event/private) +- `messages` - id, room_id, user_id, content, type +- `matches` - id, user1_id, user2_id, event_id, status, room_id +- `ratings` - id, match_id, rater_id, rated_id, score, comment + +--- + +## User Flow + +1. Register/Login +2. Choose event (from worldsdc.com list) +3. Event chat - matchmaking +4. Match confirmation → private 1:1 chat +5. **Select video from gallery** (recorded outside app) +6. **WebRTC P2P transfer** (direct, no server storage) OR link sharing fallback +7. Rate partner (1-5 stars, comment) + +--- + +## Development Guidelines + +### Code Language +- **All code, strings, UI text, comments:** ENGLISH +- **Variable/function names:** ENGLISH +- **Communication with developer:** POLISH + +### Git Commits +- Standard format, NO mentions of AI/automatic generation +- ✅ Good: `feat: add WebRTC P2P video transfer` +- ❌ Bad: `feat: add video transfer (generated by AI)` + +### Important Decisions +- Port 8080 (port 80 was occupied) +- Tailwind CSS v3.4.0 (v4 has breaking changes with Vite) +- Mock authentication uses localStorage +- All UI text in English + +--- + +## Next Steps (Phase 1 - Backend Foundation) + +**Priority:** HIGH +**Estimated Time:** 11-14 hours + +### Step 1: Backend Setup (1-2h) +- Add `backend` container to docker-compose.yml +- Initialize Node.js + Express +- Basic folder structure +- Healthcheck endpoint: `GET /api/health` +- Update nginx to proxy `/api/*` to backend + +### Step 2: PostgreSQL Setup (2-3h) +- Add `db` container (PostgreSQL 15) +- Configure volumes +- Choose migration tool (Prisma/Knex/node-pg-migrate) +- Create 6 tables schema +- Seed test data + +### Step 3: Authentication API (3-4h) +- bcrypt for password hashing +- JWT token generation +- Endpoints: `POST /api/auth/register`, `POST /api/auth/login` +- Auth middleware +- Connect frontend to real API + +### Step 4: WebSocket Chat (4-5h) +- Socket.IO setup +- Event room management +- Broadcast messages +- Active users list +- Connect frontend to Socket.IO + +--- + +## Common Commands + +**Start project:** +```bash +docker compose up --build +``` + +**Access:** +- Frontend: http://localhost:8080 +- Backend (planned): http://localhost:8080/api + +**Rebuild after changes:** +```bash +docker compose down +docker compose up --build +``` + +**Git:** +```bash +git status +git add . +git commit -m "feat: description" +``` + +--- + +## Known Issues & Solutions + +### Issue: Tailwind v4 compatibility error +**Solution:** Downgraded to Tailwind v3.4.0 +```bash +npm install -D tailwindcss@^3.4.0 +``` + +### Issue: Port 80 already allocated +**Solution:** Changed nginx port to 8080 in docker-compose.yml + +--- + +## WebRTC Implementation Notes (Future) + +**Main functionality - P2P file transfer:** +- RTCPeerConnection for connection establishment +- RTCDataChannel for binary data transfer +- File chunking (16KB chunks recommended) +- Progress monitoring (both sender and receiver) +- Metadata exchange (filename, size, MIME type) +- Error handling and reconnection logic +- Fallback: link sharing (Google Drive, Dropbox) + +**Signaling:** +- WebSocket (Socket.IO) for SDP/ICE exchange +- Server only for signaling, NOT for file storage + +**Security:** +- WebRTC native encryption (DTLS/SRTP) +- Optional: additional chat encryption (WebCrypto API) + +--- + +## Quick Reference - Frontend Routes + +- `/login` - Login page +- `/register` - Registration page +- `/events` - Event list +- `/events/:id/chat` - Event chat (public) +- `/matches/:id/chat` - Private 1:1 chat + WebRTC mockup +- `/matches/:id/rate` - Rate partner +- `/history` - Match history + +--- + +## Quick Reference - Mock Data + +**Mock User (logged in):** +- ID: 1 +- Username: john_doe +- Email: john@example.com + +**Mock Events:** +- ID: 1 - Warsaw Dance Festival 2025 +- ID: 2 - Swing Camp Barcelona 2025 +- ID: 3 - Blues Week Herräng 2025 + +--- + +## Files to Read for Full Context + +**Minimal (for quick start):** +- `docs/SESSION_CONTEXT.md` (this file) +- `docker-compose.yml` +- `frontend/src/pages/MatchChatPage.jsx` (WebRTC mockup) + +**Full context:** +- `docs/CONTEXT.md` (project description) +- `docs/TODO.md` (task list) +- `docs/ARCHITECTURE.md` (technical details) + +**Archives:** +- `docs/COMPLETED.md` (completed tasks) +- `docs/RESOURCES.md` (learning resources) + +--- + +**Last Updated:** 2025-11-12 +**Session Started:** Frontend Mockup completed, ready for Backend Foundation diff --git a/docs/TODO.md b/docs/TODO.md index 0f6d313..1e022ef 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -1,472 +1,193 @@ # TODO - spotlight.cam -Lista zadań do realizacji projektu spotlight.cam - aplikacji do matchmaking i wymiany nagrań wideo na eventach tanecznych. - -## 📋 Status realizacji -- ⏳ Do zrobienia -- 🔄 W trakcie -- ✅ Zrobione +**Active tasks and roadmap - optimized for quick reference** --- -## 🎯 AKTUALNY STATUS PROJEKTU +## 🎯 CURRENT STATUS -### ✅ Ukończone (Faza 0: Frontend Mockup) -- Frontend mockup z pełną funkcjonalnością UI -- Docker Compose setup (nginx + frontend) -- Dokumentacja projektu -- **Gotowe do prezentacji i testowania UX** +**Phase:** 0 (Frontend Mockup) - ✅ COMPLETED +**Next Phase:** 1 (Backend Foundation) - ⏳ PENDING +**Progress:** ~25% complete -### 🔄 W trakcie -- Przygotowanie do backend development +### ✅ Completed +- Frontend mockup with all views +- Docker Compose (nginx + frontend) +- Mock authentication, mock data +- Documentation -### ⏳ Następne kroki -**Priorytet:** Backend setup → Database → API → WebSocket +### ⏳ Next Priority +**Backend Foundation** - Node.js + PostgreSQL + Auth + WebSocket + +**See:** `docs/COMPLETED.md` for full list of completed tasks --- -## 📌 SUGEROWANE KOLEJNE KROKI +## 📌 NEXT STEPS - Phase 1: Backend Foundation -### 🚀 Krok 1: Backend Foundation (zalecane TERAZ) -Cel: Uruchomić backend Node.js z podstawowym API +**Estimated Time:** 11-14 hours +**Priority:** HIGH -**Co zrobić:** -1. Dodaj kontener `backend` do docker-compose.yml -2. Zainicjalizuj projekt Node.js + Express -3. Skonfiguruj strukturę folderów backend -4. Dodaj podstawowy endpoint healthcheck (`GET /api/health`) -5. Zaktualizuj nginx config aby proxy'ował `/api/*` do backendu +### Step 1: Backend Setup (1-2h) ⏳ +- [ ] Add `backend` service to docker-compose.yml +- [ ] Initialize Node.js + Express project +- [ ] Create folder structure (routes, controllers, middleware, etc.) +- [ ] Add healthcheck endpoint: `GET /api/health` +- [ ] Update nginx config to proxy `/api/*` to backend +- [ ] Test: http://localhost:8080/api/health should return 200 OK -**Czas realizacji:** 1-2 godziny -**Benefit:** Podstawa dla dalszego rozwoju API +### Step 2: PostgreSQL Setup (2-3h) ⏳ +- [ ] Add `db` service (PostgreSQL 15) to docker-compose.yml +- [ ] Configure volumes for data persistence +- [ ] Choose migration tool (Prisma / Knex / node-pg-migrate) +- [ ] Create database schema (6 tables: users, events, chat_rooms, messages, matches, ratings) +- [ ] Add indexes for performance +- [ ] Create seed data (test events from worldsdc.com) +- [ ] Test: Connect to DB from backend, run simple query + +### Step 3: Authentication API (3-4h) ⏳ +- [ ] Install dependencies: bcrypt, jsonwebtoken, express-validator +- [ ] Implement password hashing with bcrypt +- [ ] Implement JWT token generation and verification +- [ ] Create endpoints: + - `POST /api/auth/register` - Create account + - `POST /api/auth/login` - Login, return JWT + - `GET /api/users/me` - Get current user (protected) +- [ ] Create auth middleware for protected routes +- [ ] Update frontend AuthContext to use real API instead of mock +- [ ] Test: Register → Login → Access protected endpoint + +### Step 4: WebSocket Chat (4-5h) ⏳ +- [ ] Install Socket.IO on backend +- [ ] Setup Socket.IO server with Express +- [ ] Implement event handlers: + - Connection/disconnection + - Join/leave event room + - Send/receive messages + - Active users list +- [ ] Install socket.io-client on frontend +- [ ] Update EventChatPage to use Socket.IO instead of mock +- [ ] Update MatchChatPage to use Socket.IO for chat +- [ ] Test: Real-time messaging between users --- -### 🗄️ Krok 2: PostgreSQL Setup (po Kroku 1) -Cel: Uruchomić bazę danych i stworzyć schemat +## 🎯 Future Phases (Reference) -**Co zrobić:** -1. Dodaj kontener `db` (PostgreSQL 15) do docker-compose.yml -2. Skonfiguruj volumes dla persystencji danych -3. Wybierz tool do migracji (Prisma / node-pg-migrate / Knex) -4. Stwórz schemat bazy (6 tabel: users, events, chat_rooms, messages, matches, ratings) -5. Dodaj seed data dla eventów testowych +### Phase 2: Core Features (2-3 weeks) +- [ ] Matches API (create pairs) +- [ ] Private 1:1 chat (Socket.IO rooms) +- [ ] WebRTC signaling server (SDP/ICE exchange) +- [ ] Ratings API -**Czas realizacji:** 2-3 godziny -**Benefit:** Prawdziwe dane zamiast mocków +### Phase 3: WebRTC P2P (3-4 weeks) - MAIN FEATURE +- [ ] RTCPeerConnection setup +- [ ] RTCDataChannel for file transfer +- [ ] Chunking implementation (16KB chunks) +- [ ] Progress monitoring +- [ ] Error handling & reconnection +- [ ] STUN/TURN server configuration + +### Phase 4: MVP Finalization (2-3 weeks) +- [ ] Security hardening (rate limiting, validation, CORS) +- [ ] Testing (unit, integration, E2E) +- [ ] PWA features (manifest, service worker, icons) +- [ ] Deployment (production environment) + +### Phase 5: Optional Extensions +- [ ] User badges & trust system +- [ ] Block users +- [ ] Public profiles +- [ ] Push notifications +- [ ] Video compression +- [ ] Multi-file transfer --- -### 🔐 Krok 3: Authentication API (po Kroku 2) -Cel: Prawdziwa autentykacja JWT +## 📝 Active Development Tasks -**Co zrobić:** -1. Implementacja bcrypt do hashowania haseł -2. JWT token generation i verification -3. Endpointy: POST /api/auth/register, POST /api/auth/login -4. Middleware do weryfikacji tokena -5. Podłączenie frontendu do prawdziwego API +### Documentation +- [x] ✅ README.md +- [x] ✅ QUICKSTART.md +- [x] ✅ CONTEXT.md +- [x] ✅ TODO.md +- [x] ✅ SESSION_CONTEXT.md +- [x] ✅ ARCHITECTURE.md +- [x] ✅ COMPLETED.md +- [x] ✅ RESOURCES.md +- [ ] ⏳ API documentation (Swagger/OpenAPI) - after backend +- [ ] ⏳ Architecture diagrams - after backend +- [ ] ⏳ WebRTC flow diagram - after WebRTC implementation -**Czas realizacji:** 3-4 godziny -**Benefit:** Koniec z mock auth, prawdziwe konta użytkowników +### Infrastructure +- [x] ✅ Docker Compose (nginx, frontend) +- [ ] ⏳ Docker Compose (backend, db) +- [ ] ⏳ Production Dockerfile optimization (multi-stage builds) +- [ ] ⏳ CI/CD pipeline (GitHub Actions) +- [ ] ⏳ HTTPS setup (Let's Encrypt) + +### Testing +- [ ] ⏳ Backend tests (Jest + Supertest) +- [ ] ⏳ Frontend tests (Vitest + React Testing Library) +- [ ] ⏳ E2E tests (Playwright / Cypress) +- [ ] ⏳ WebRTC manual testing (different devices) --- -### 💬 Krok 4: WebSocket Chat (po Kroku 3) -Cel: Real-time czat eventowy +## 🚀 Quick Commands -**Co zrobić:** -1. Setup Socket.IO na backendzie -2. Implementacja room management (event rooms) -3. Broadcast messages -4. Lista aktywnych użytkowników -5. Podłączenie frontendu do Socket.IO +**Start development:** +```bash +docker compose up --build +``` -**Czas realizacji:** 4-5 godzin -**Benefit:** Prawdziwy czat zamiast mocka +**Rebuild after changes:** +```bash +docker compose down && docker compose up --build +``` + +**Access:** +- Frontend: http://localhost:8080 +- Backend (future): http://localhost:8080/api + +**Git workflow:** +```bash +git status +git add . +git commit -m "feat: description" +``` --- -## 🐳 1. Setup projektu i infrastruktura +## 📊 Progress Tracking -### Docker Compose -- [x] ✅ Utworzenie `docker-compose.yml` z serwisem nginx -- [x] ✅ Konfiguracja kontenera frontend (React/Vite) -- [ ] ⏳ Konfiguracja kontenera backend (Node.js) -- [ ] ⏳ Konfiguracja kontenera PostgreSQL 15 -- [ ] ⏳ Konfiguracja volumes dla persystencji danych -- [x] ✅ Konfiguracja sieci między kontenerami +| Phase | Status | Progress | Estimated Time | +|-------|--------|----------|----------------| +| Phase 0: Frontend Mockup | ✅ Done | 100% | ~8h (completed) | +| Phase 1: Backend Foundation | ⏳ Next | 0% | ~11-14h | +| Phase 2: Core Features | ⏳ Pending | 0% | ~15-20h | +| Phase 3: WebRTC P2P | ⏳ Pending | 0% | ~20-30h | +| Phase 4: MVP Finalization | ⏳ Pending | 0% | ~15-20h | -### Struktura projektu -- [x] ✅ Inicjalizacja projektu frontend (React + Vite + Tailwind) -- [x] ✅ Utworzenie `.gitignore` -- [x] ✅ Konfiguracja ESLint (frontend) -- [ ] ⏳ Inicjalizacja projektu backend (Node.js + Express) -- [ ] ⏳ Konfiguracja ESLint i Prettier (backend) -- [ ] ⏳ Konfiguracja TypeScript (opcjonalnie) -- [ ] ⏳ Utworzenie `.env` i `.env.example` +**Overall Progress:** ~25% (1 of 4 core phases done) --- -## 🗄️ 2. Baza danych PostgreSQL +## 📝 Notes -### Schema i migracje -- [ ] ⏳ Setup narzędzia do migracji (np. node-pg-migrate, Knex, Prisma) -- [ ] ⏳ Utworzenie tabeli `users` - - id, username, email, password_hash, created_at, updated_at -- [ ] ⏳ Utworzenie tabeli `events` - - id, name, location, start_date, end_date, worldsdc_id -- [ ] ⏳ Utworzenie tabeli `chat_rooms` - - id, event_id, type (event/private), created_at -- [ ] ⏳ Utworzenie tabeli `messages` - - id, room_id, user_id, content, type (text/link), created_at -- [ ] ⏳ Utworzenie tabeli `matches` - - id, user1_id, user2_id, event_id, status, room_id, created_at -- [ ] ⏳ Utworzenie tabeli `ratings` - - id, match_id, rater_id, rated_id, score (1-5), comment, would_collaborate_again -- [ ] ⏳ Utworzenie indeksów dla optymalizacji zapytań -- [ ] ⏳ Seed danych testowych (events z worldsdc.com) +- Frontend mockup is presentation-ready +- All views work with mock data - easy to connect real API +- WebRTC P2P mockup in MatchChatPage - needs real implementation +- Focus on Phase 1 next (backend foundation) +- Update task status: ⏳ → 🔄 → ✅ --- -## 🔧 3. Backend - REST API - -### Autentykacja i autoryzacja -- [ ] ⏳ Endpoint: `POST /api/auth/register` - rejestracja użytkownika -- [ ] ⏳ Endpoint: `POST /api/auth/login` - logowanie użytkownika -- [ ] ⏳ Endpoint: `POST /api/auth/logout` - wylogowanie -- [ ] ⏳ Implementacja bcrypt do hashowania haseł -- [ ] ⏳ Implementacja JWT/session dla autoryzacji -- [ ] ⏳ Middleware do weryfikacji tokena - -### Users API -- [ ] ⏳ Endpoint: `GET /api/users/me` - pobranie profilu użytkownika -- [ ] ⏳ Endpoint: `PATCH /api/users/me` - aktualizacja profilu -- [ ] ⏳ Endpoint: `GET /api/users/:id` - pobranie profilu innego użytkownika - -### Events API -- [ ] ⏳ Endpoint: `GET /api/events` - lista wszystkich eventów -- [ ] ⏳ Endpoint: `GET /api/events/:id` - szczegóły eventu -- [ ] ⏳ Endpoint: `POST /api/events/:id/join` - dołączenie do eventu -- [ ] ⏳ Integracja z worldsdc.com API (jeśli dostępne) - -### Matches API -- [ ] ⏳ Endpoint: `GET /api/matches` - historia matchów użytkownika -- [ ] ⏳ Endpoint: `POST /api/matches` - utworzenie matcha -- [ ] ⏳ Endpoint: `PATCH /api/matches/:id` - aktualizacja statusu matcha - -### Ratings API -- [ ] ⏳ Endpoint: `POST /api/ratings` - dodanie oceny partnera -- [ ] ⏳ Endpoint: `GET /api/ratings/user/:id` - oceny danego użytkownika -- [ ] ⏳ Endpoint: `GET /api/ratings/stats/:id` - statystyki użytkownika - -### Reports API -- [ ] ⏳ Endpoint: `POST /api/reports` - zgłoszenie użytkownika +**For detailed task history:** See `docs/COMPLETED.md` +**For learning resources:** See `docs/RESOURCES.md` +**For quick session context:** See `docs/SESSION_CONTEXT.md` +**For technical details:** See `docs/ARCHITECTURE.md` --- -## 💬 4. Backend - WebSocket (Socket.IO) - -### Czat eventowy (publiczny) -- [ ] ⏳ Setup Socket.IO na backendzie -- [ ] ⏳ Obsługa połączenia/rozłączenia użytkownika -- [ ] ⏳ Dołączenie użytkownika do pokoju eventowego -- [ ] ⏳ Wysyłanie wiadomości tekstowych do pokoju -- [ ] ⏳ Broadcast wiadomości do wszystkich w pokoju -- [ ] ⏳ Lista aktywnych użytkowników w pokoju - -### Czat 1:1 (prywatny) -- [ ] ⏳ Utworzenie prywatnego pokoju dla pary -- [ ] ⏳ Wysyłanie wiadomości prywatnych -- [ ] ⏳ Powiadomienia o nowych wiadomościach - -### WebRTC Signaling -- [ ] ⏳ Obsługa wymiany SDP offer/answer -- [ ] ⏳ Obsługa wymiany ICE candidates -- [ ] ⏳ Sygnalizacja statusu połączenia WebRTC -- [ ] ⏳ Error handling dla failed connections - ---- - -## 🎥 5. WebRTC - Peer-to-Peer Transfer Filmów (GŁÓWNA FUNKCJONALNOŚĆ) - -### Setup WebRTC -- [ ] ⏳ Konfiguracja STUN servers (Google STUN) -- [ ] ⏳ Konfiguracja TURN server (opcjonalnie, dla trudnych NAT) -- [ ] ⏳ Utworzenie RTCPeerConnection -- [ ] ⏳ Utworzenie RTCDataChannel dla transferu plików - -### Nawiązanie połączenia -- [ ] ⏳ Inicjacja połączenia przez wysyłającego (createOffer) -- [ ] ⏳ Odpowiedź odbierającego (createAnswer) -- [ ] ⏳ Wymiana ICE candidates -- [ ] ⏳ Monitoring statusu połączenia (connecting, connected, failed) - -### Transfer plików -- [ ] ⏳ Wybór pliku z galerii (``) -- [ ] ⏳ Walidacja pliku (typ, rozmiar max) -- [ ] ⏳ Wysłanie metadanych (nazwa, rozmiar, MIME type) -- [ ] ⏳ Implementacja chunkingu (podział na fragmenty 16KB) -- [ ] ⏳ Wysyłanie chunków przez DataChannel -- [ ] ⏳ Odbieranie chunków i składanie w Blob -- [ ] ⏳ Progress monitoring (pasek postępu % dla wysyłającego i odbierającego) -- [ ] ⏳ Obsługa błędów transferu -- [ ] ⏳ Możliwość anulowania transferu -- [ ] ⏳ Zapis pliku do pamięci urządzenia (download) - -### Fallback - wymiana linków -- [x] ✅ UI do wklejenia linku do filmu (Google Drive, Dropbox, itp.) -- [x] ✅ Walidacja URL -- [x] ✅ Wysłanie linku przez czat (mockup) - -### Optymalizacje -- [ ] ⏳ Dostosowanie rozmiaru chunka do bandwidth -- [ ] ⏳ Buffer management (kontrola przepełnienia bufora) -- [ ] ⏳ Reconnection logic przy utracie połączenia - ---- - -## 🎨 6. Frontend - PWA (React + Vite + Tailwind) - -### Setup PWA -- [x] ✅ Konfiguracja Vite -- [x] ✅ Konfiguracja Tailwind CSS -- [ ] ⏳ Konfiguracja Vite PWA plugin -- [ ] ⏳ Utworzenie `manifest.json` -- [ ] ⏳ Utworzenie service worker -- [ ] ⏳ Ikony aplikacji (różne rozmiary) -- [ ] ⏳ Splash screen - -### Routing -- [x] ✅ Setup React Router -- [x] ✅ Ochrona tras (require authentication) - -### Widoki/Komponenty -- [x] ✅ **Logowanie** (`/login`) - Formularz email + hasło, link do rejestracji -- [x] ✅ **Rejestracja** (`/register`) - Formularz username, email, hasło, walidacja -- [x] ✅ **Wybór eventu** (`/events`) - Lista eventów, wyszukiwanie, przycisk "Join chat" -- [x] ✅ **Czat eventowy** (`/events/:id/chat`) - Lista wiadomości, aktywni użytkownicy, matchmaking -- [x] ✅ **Czat 1:1** (`/matches/:id/chat`) - Profil partnera, czat, **mockup WebRTC transfer** -- [x] ✅ **Ocena partnera** (`/matches/:id/rate`) - Gwiazdki 1-5, komentarz, checkbox -- [x] ✅ **Historia współprac** (`/history`) - Lista matchów, oceny, statystyki - -### Komponenty reużywalne -- [x] ✅ `` - nawigacja -- [x] ✅ `` - wrapper dla stron -- [ ] ⏳ `` - wiadomość w czacie (do wydzielenia z page) -- [ ] ⏳ `` - karta użytkownika (do wydzielenia) -- [ ] ⏳ `` - karta eventu (do wydzielenia) -- [ ] ⏳ `` - gwiazdki oceny (do wydzielenia) -- [ ] ⏳ `` - komponent do wyboru i wysyłania filmu -- [ ] ⏳ `` - pasek postępu transferu (do wydzielenia) -- [ ] ⏳ `` - status połączenia WebRTC (do wydzielenia) - -### Stylowanie (Tailwind) -- [x] ✅ Konfiguracja motywu kolorystycznego -- [x] ✅ Responsive design (mobile-first) -- [ ] ⏳ Dark mode (opcjonalnie) - -### State Management -- [x] ✅ Auth state (Context API - current user, mock login/logout) -- [ ] ⏳ Zamiana na prawdziwe API (po backend setup) -- [ ] ⏳ Chat state (messages, active users) - połączenie z Socket.IO -- [ ] ⏳ WebRTC state (connection status, transfer progress) - prawdziwy WebRTC - -### Integracja Socket.IO (client) -- [ ] ⏳ Setup socket.io-client -- [ ] ⏳ Połączenie z backendem -- [ ] ⏳ Obsługa eventów czatu -- [ ] ⏳ Obsługa eventów WebRTC signaling -- [ ] ⏳ Reconnection logic - ---- - -## 🔐 7. Bezpieczeństwo - -### Backend -- [ ] ⏳ Rate limiting (np. express-rate-limit) -- [ ] ⏳ Helmet.js dla security headers -- [ ] ⏳ CORS configuration -- [ ] ⏳ Input sanitization (XSS prevention) -- [ ] ⏳ SQL injection prevention (prepared statements) -- [ ] ⏳ Walidacja wszystkich inputów (express-validator) - -### Frontend -- [ ] ⏳ XSS prevention (sanitize user input) -- [ ] ⏳ CSRF protection -- [ ] ⏳ Secure token storage (httpOnly cookies lub secure localStorage) - -### WebRTC -- [ ] ⏳ Potwierdzenie, że WebRTC używa DTLS/SRTP (natywne szyfrowanie) -- [ ] ⏳ Opcjonalne: dodatkowe szyfrowanie czatu (WebCrypto API) - ---- - -## 🧪 8. Testowanie - -### Backend -- [ ] ⏳ Setup Jest + Supertest -- [ ] ⏳ Testy jednostkowe endpoints API -- [ ] ⏳ Testy integracyjne z bazą danych -- [ ] ⏳ Testy WebSocket (Socket.IO) - -### Frontend -- [ ] ⏳ Setup Vitest + React Testing Library -- [ ] ⏳ Testy jednostkowe komponentów -- [ ] ⏳ Testy integracyjne widoków -- [ ] ⏳ E2E testy (Playwright / Cypress) - -### WebRTC -- [ ] ⏳ Testy manualne transferu plików (różne rozmiary) -- [ ] ⏳ Testy na różnych urządzeniach (Android/iOS) -- [ ] ⏳ Testy w różnych warunkach sieciowych - ---- - -## 📚 9. Dokumentacja - -- [x] ✅ README.md - instrukcja uruchomienia projektu -- [x] ✅ QUICKSTART.md - szybki start (2 minuty) -- [x] ✅ CONTEXT.md - architektura i założenia projektu -- [x] ✅ TODO.md - roadmap projektu -- [ ] ⏳ API documentation (Swagger/OpenAPI) -- [ ] ⏳ Architektura systemu (diagram) -- [ ] ⏳ WebRTC flow diagram -- [ ] ⏳ User flow diagrams - ---- - -## 🚀 10. Deployment i DevOps - -- [ ] ⏳ Konfiguracja CI/CD (GitHub Actions) -- [ ] ⏳ Automated tests w CI -- [ ] ⏳ Docker image optimization (multi-stage builds) -- [ ] ⏳ Konfiguracja production environment variables -- [ ] ⏳ Setup HTTPS (Let's Encrypt) -- [ ] ⏳ Deployment backendu (VPS / Cloud) -- [ ] ⏳ Deployment frontendu (Vercel / Netlify / własny serwer) -- [ ] ⏳ Setup PostgreSQL backup strategy -- [ ] ⏳ Monitoring (logs, errors, performance) - ---- - -## ➕ 11. Opcjonalne rozszerzenia (po MVP) - -- [ ] ⏳ System oznaczeń zaufania (badges dla zweryfikowanych użytkowników) -- [ ] ⏳ Blokowanie użytkowników -- [ ] ⏳ Publiczne profile z opiniami -- [ ] ⏳ Powiadomienia push (Web Push API) -- [ ] ⏳ Kompresja wideo przed wysłaniem (opcjonalnie) -- [ ] ⏳ Podgląd thumbnail filmu przed wysłaniem -- [ ] ⏳ Multi-file transfer (wysyłanie wielu filmów naraz) -- [ ] ⏳ Integracja z worldsdc.com API (automatyczne pobieranie eventów) -- [ ] ⏳ Statystyki użycia aplikacji (analytics) -- [ ] ⏳ Admin panel - ---- - -## 🎯 Priorytet realizacji (zaktualizowany) - -### ✅ Faza 0: Frontend Mockup (UKOŃCZONA) -- ✅ Docker Compose (nginx + frontend) -- ✅ React + Vite + Tailwind setup -- ✅ Wszystkie widoki z mockupami -- ✅ Mock data i routing -- ✅ Dokumentacja - -**Status:** Gotowe do prezentacji i testowania UX - ---- - -### 🔄 Faza 1: MVP Backend Foundation (1-2 tygodnie) - **AKTUALNY CEL** -**Priorytet: WYSOKI** - Następna faza do realizacji - -1. ✨ **Backend setup** (1-2 godziny) - - Kontener backend w docker-compose - - Node.js + Express + podstawowa struktura - - Healthcheck endpoint - -2. 🗄️ **PostgreSQL setup** (2-3 godziny) - - Kontener PostgreSQL - - Schema bazy (6 tabel) - - Narzędzie do migracji (Prisma/Knex) - - Seed data - -3. 🔐 **Authentication API** (3-4 godziny) - - bcrypt + JWT - - Register/Login endpoints - - Auth middleware - - Podłączenie frontendu - -4. 💬 **WebSocket Chat** (4-5 godzin) - - Socket.IO setup - - Event rooms - - Real-time messaging - - Active users list - -**Łączny czas:** ~11-14 godzin (1-2 tygodnie przy spokojnym tempie) - ---- - -### Faza 2: Core Features (2-3 tygodnie) -1. Matches API (tworzenie par) -2. Private chat 1:1 (Socket.IO rooms) -3. WebRTC signaling server -4. Ratings API - ---- - -### Faza 3: Główna funkcjonalność WebRTC (3-4 tygodnie) -1. **WebRTC P2P connection** -2. **File transfer via DataChannel** (chunking, progress) -3. Error handling i reconnection -4. Optymalizacje - ---- - -### Faza 4: Finalizacja MVP (2-3 tygodnie) -1. Bezpieczeństwo (rate limiting, validation, CORS) -2. Testy (unit, integration, E2E) -3. PWA features (manifest, service worker) -4. Deployment - ---- - -### Faza 5: Opcjonalne rozszerzenia (ongoing) -- Features z sekcji 11 - ---- - -## 📊 Postęp projektu - -**Ukończone:** ~25% (frontend mockup + dokumentacja) -**W trakcie:** 0% (przygotowanie do backend) -**Do zrobienia:** ~75% (backend, WebRTC, deployment) - ---- - -## 📝 Notatki -- ✅ Frontend mockup gotowy - można prezentować UX -- 🎯 Następny krok: **Backend setup** (Node.js + Express + PostgreSQL) -- 💡 Wszystkie widoki działają z mock data - łatwo podłączyć prawdziwe API -- 🔥 Główna funkcjonalność (WebRTC P2P) jest mockupem - wymaga implementacji -- 📌 Regularnie aktualizuj status zadań (⏳ → 🔄 → ✅) -- 🚀 WebRTC file transfer to najważniejsza i najtrudniejsza część projektu - ---- - -## 🎓 Dodatkowe zasoby - -### Backend (Node.js + Express) -- Express best practices: https://expressjs.com/en/advanced/best-practice-performance.html -- JWT authentication: https://jwt.io/introduction -- Socket.IO docs: https://socket.io/docs/v4/ - -### WebRTC -- WebRTC for beginners: https://webrtc.org/getting-started/overview -- RTCDataChannel guide: https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel -- File transfer via WebRTC: https://webrtc.github.io/samples/src/content/datachannel/filetransfer/ - -### Database -- Prisma docs: https://www.prisma.io/docs -- PostgreSQL best practices: https://wiki.postgresql.org/wiki/Don't_Do_This +**Last Updated:** 2025-11-12