radziel/spotlightcam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
75cb4b16e74562e4e0e52f7be886d5a2552d1cd0
spotlightcam/docs/SESSION_CONTEXT.md
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

7.2 KiB
Raw Blame History

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:

docker compose up --build

Access:

Rebuild after changes:

docker compose down
docker compose up --build

Git:

git status
git add .
git commit -m "feat: description"

Known Issues & Solutions

Issue: Tailwind v4 compatibility error

Solution: Downgraded to Tailwind v3.4.0

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):

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