Files

Radosław Gierwiało a1357393e8 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.

2025-11-12 18:07:42 +01:00

4.8 KiB

Raw Blame History

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

Rejestracja/Logowanie użytkownika
Wybór eventu (lista z worldsdc.com) na którym użytkownik jest
Czat eventowy – matchmaking (lista aktywnych użytkowników)
Potwierdzenie matcha → przejście do prywatnego czatu 1:1
Wybór pliku wideo z galerii (nagranie odbywa się poza aplikacją)
Przesłanie filmu przez WebRTC (P2P, bez serwera) LUB wymiana linków (fallback)
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

// ✅ 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

4.8 KiB Raw Blame History Unescape Escape