radziel/spotlightcam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2c5689ac8e458042f10925c12b5b5249bb5ac61a
spotlightcam/docs/SESSION_CONTEXT.md
Radosław Gierwiało f6fd983c68 docs: update documentation with chat enhancements 
Document three recent chat improvements:

1. Real-time Active Users Fix (dd31761)
   - Fixed bug where users list didn't update when new users joined
   - Rewrote getAllDisplayUsers() to prioritize Socket.IO data

2. Message Length Limits (4a91a10)
   - Added 2000 character limit with visual counter
   - Backend + frontend validation

3. Spam Protection System (ace3311)
   - Rate limiting: 10 messages per minute
   - Duplicate detection within 60 second window
   - Profanity filter with Polish + English words

Updated:
- README.md: Added chat features to Events & Chat section
- SESSION_CONTEXT.md: New "Chat Enhancements" section
- COMPLETED.md: Comprehensive entry with problem/solution/impact
- Last updated dates: 2025-12-03
2025-12-03 00:03:37 +01:00

264 lines
10 KiB
Markdown
Raw Blame History

# Session Context - spotlight.cam
**Quick reference for resuming development sessions**
---
## 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:** MVP Complete - Production Ready
**Tests:** 342/342 backend tests passing - 100% ✅ (72.5% coverage)
**Recent Work:** Activity Log System with real-time admin dashboard (Phase 3.5 complete)
### Core Features (All Implemented)
- JWT authentication with email verification (AWS SES)
- Real-time chat (Socket.IO) - event rooms + private 1:1
- Real-time active users with instant updates
- Message validation (2000 char limit with visual counter)
- Spam protection (rate limiting, duplicate detection, profanity filter)
- WebRTC P2P file transfer (RTCDataChannel, up to 700MB tested)
- Competition heats system for matchmaking
- Recording matching system with 3-tier account system (BASIC/SUPPORTER/COMFORT)
- Fairness algorithm (karma tracking: recordingsDone vs recordingsReceived)
- Dual buffer system (prep before + rest after dancing)
- Matching runs audit with origin_run_id tracking
- Incremental matching (preserves accepted/completed suggestions)
- Scheduler integration (automated matching with cron)
- Atomic stats updates with race condition prevention
- Clickable usernames with @ prefix, country flags
- Matches & ratings API
- QR code event check-in
- PWA (offline support, iOS compatible)
- Security: CSRF, rate limiting, account lockout
- Test bot for automated testing
- Activity Log System - admin monitoring dashboard with real-time streaming (18 action types)
---
## Project Structure (Key Paths)
```
/spotlightcam
├── docker-compose.yml # nginx:8080 + frontend + backend + db
├── frontend/src/
│ ├── pages/ # React pages
│ │ └── admin/ # Admin pages (ActivityLogsPage.jsx)
│ ├── components/ # Reusable components
│ ├── contexts/ # AuthContext
│ ├── services/ # api.js, socket.js
│ ├── hooks/ # useWebRTC.js
│ └── constants/ # MATCH_STATUS, SUGGESTION_STATUS, etc.
├── backend/src/
│ ├── routes/ # API endpoints (events.js, matches.js, admin.js)
│ ├── controllers/ # Business logic
│ ├── services/ # matching.js (auto-matching), activityLog.js (audit trail)
│ ├── middleware/ # auth.js, admin.js (requireAdmin)
│ ├── socket/ # Socket.IO handlers (chat, WebRTC, admin logs)
│ ├── utils/ # request.js (IP extraction)
│ ├── constants/ # Status constants
│ └── __tests__/ # Jest tests (342 tests - 100% passing)
│ ├── matching-algorithm.test.js # 19 tests
│ ├── ratings-stats-flow.test.js # 9 tests
│ ├── matching-runs-audit.test.js # 6 tests
│ ├── matching-incremental.test.js # 5 tests
│ └── socket.test.js # 12 tests
└── docs/
├── SESSION_CONTEXT.md # This file - quick context
├── TODO.md # Current tasks & roadmap
├── ARCHITECTURE.md # Technical details
├── DEPLOYMENT.md # Deployment guide
├── MONITORING.md # Operations guide
├── TESTING_MATCHING_RATINGS.md # Comprehensive test documentation (45 tests)
├── WEBRTC_TESTING_GUIDE.md # WebRTC testing guide
└── archive/ # Archived documentation
```
---
## Database Schema (12 tables)
Key models:
- `users` - Auth, profile, social links, location, lockout fields, `isAdmin` flag
- Account tiers: `accountTier` (BASIC/SUPPORTER/COMFORT), `recordingsDone`, `recordingsReceived`
- `events` - Dance events with unique slugs
- `event_participants` - User-event relationship, competitorNumber, recorderOptOut, `accountTierOverride`
- `divisions` / `competition_types` / `event_user_heats` - Competition system
- `matches` - User pairings with CUID slugs
- `ratings` - 1-5 stars, comments, `statsApplied` flag
- `recording_suggestions` - Auto-matching results with collision detection, `originRunId` tracking
- `matching_runs` - Audit trail (manual/scheduler, status, stats)
- `chat_rooms` / `messages` - Real-time chat persistence
- `activity_logs` - Comprehensive audit trail (18 action types, indexed for performance)
---
## Recent Changes (2025-12-03)
### Chat Enhancements - Complete ✅
**Real-time updates, message validation, and spam protection**
**Commits:** `dd31761` (real-time users), `4a91a10` (message limits), `ace3311` (spam protection)
**1. Real-time Active Users Fix (dd31761)**
- Fixed bug where active users list didn't update when new users joined chat
- Root cause: Used static `checkedInUsers` as base instead of real-time `activeUsers`
- Solution: Rewrote `getAllDisplayUsers()` to prioritize Socket.IO data
- Files: `frontend/src/pages/EventChatPage.jsx`, `frontend/src/hooks/useEventChat.js`
**2. Message Length Limits (4a91a10)**
- Added 2000 character limit for all chat messages (event + match chat)
- Backend validation in `send_event_message` and `send_match_message` handlers
- Frontend: `maxLength` attribute + character counter at 80% threshold (1600+)
- Visual feedback: red text when at limit, submit button disabled
- Files: `backend/src/constants/index.js`, `backend/src/socket/index.js`, `frontend/src/constants/index.js`, `frontend/src/components/chat/ChatInput.jsx`
**3. Spam Protection System (ace3311)**
- Rate Limiting: 10 messages per minute per user
- Duplicate Detection: Prevents identical messages within 1 minute window
- Profanity Filter: bad-words library (v2.0.0) with English + 11 Polish words
- In-memory tracking with automatic cleanup every 5 minutes
- User-friendly error messages for each validation type
- Files: `backend/src/middleware/messageValidation.js` (new), `backend/src/socket/index.js`, `backend/package.json`
---
### Activity Log System (Phase 3.5) - Complete ✅ (2025-12-02)
**Comprehensive admin monitoring with real-time streaming dashboard**
**Backend (Phases 1-5):**
- `activity_logs` table with 18 action types (AUTH_*, EVENT_*, MATCH_*, ADMIN_*, CHAT_*)
- `activityLog.js` service - fire-and-forget logging, never blocks requests
- `requireAdmin` middleware - fresh DB check for admin status
- 3 API endpoints: query logs, get action types, get statistics
- Socket.IO streaming - `admin_activity_logs` room with permission check
- 14 integration points across auth, events, matches, socket handlers
**Frontend (Phases 6-7):**
- `ActivityLogsPage.jsx` (600+ lines) - full admin dashboard
- Stats dashboard: total logs, unique users, failures, 24h activity
- Advanced filtering: date range, category, action type, username, success/failure
- Paginated table (50 per page) with color-coded action badges
- Real-time streaming toggle (Socket.IO integration)
- Admin-only route `/admin/activity-logs` with Shield icon in navbar
**Files Created/Modified:**
- Backend: `schema.prisma`, `activityLog.js`, `admin.js`, `request.js`, admin routes
- Frontend: `ActivityLogsPage.jsx`, `api.js`, `App.jsx`, `Navbar.jsx`
- Integration: 14 logging points in auth, events, matches, socket handlers
**Admin User:** spotlight@radziel.com / Dance123!
---
## Quick Commands
```bash
# Start development
docker compose --profile dev up
# Run all backend tests
docker compose exec backend npm test
# Run specific test suite
docker compose exec backend npm test -- matching-runs-audit.test.js
# Coverage report
docker compose exec backend npm run test:coverage
# Admin CLI
docker compose exec backend npm run cli -- users:list --limit 20
# Access
# Frontend: http://localhost:8080
# API: http://localhost:8080/api
# Health: http://localhost:8080/api/health
```
---
## Development Guidelines
- **Code language:** All code, strings, comments in ENGLISH
- **Communication:** POLISH with developer
- **Git commits:** Standard format, NO AI mentions
- **Port:** 8080 (not 80)
- **Tailwind:** v3.4.0 (v4 has breaking changes)
---
## Key Constants
```javascript
// frontend/src/constants/ & backend/src/constants/
MATCH_STATUS: pending | accepted | rejected | completed
SUGGESTION_STATUS: pending | accepted | rejected | not_found
CONNECTION_STATE: disconnected | connecting | connected | failed
ACCOUNT_TIER: BASIC | SUPPORTER | COMFORT
// Tier fairness penalties
FAIRNESS_SUPPORTER_PENALTY: 10
FAIRNESS_COMFORT_PENALTY: 50
// Matching config
MAX_RECORDINGS_PER_PERSON: 3
PREP_BUFFER_MINUTES: 30
REST_BUFFER_MINUTES: 60
```
---
## Test Accounts (Seeded)
| Username | Email | Password |
|----------|-------|----------|
| john_dancer | john@example.com | Dance123! |
| sarah_swings | sarah@example.com | Swing456! |
| mike_blues | mike@example.com | Blues789! |
---
## Test Coverage Summary
**Total:** 342/342 tests passing (100% ✅)
- **Matching Algorithm:** 19 tests (TC1-TC19)
- Fundamentals, collision detection, limits, fairness, edge cases
- **Ratings & Stats:** 9 tests
- Atomic updates, race prevention, idempotency
- **Matching Runs Audit:** 6 tests
- origin_run_id tracking, sequential runs, filtering
- **Incremental Matching:** 5 tests
- **Recording Stats Integration:** 6 tests
- **WebRTC Signaling:** 12 tests
- **Socket.IO:** 12 tests
- **API Routes:** Full CRUD coverage (auth, events, matches, dashboard)
**Code Coverage:**
- matching.js: 94.71% statements, 91.5% branches
- routes/matches.js: 76.11% statements
- routes/events.js: 78.2% statements
---
## For More Details
- `docs/TODO.md` - Active tasks, security audit, future improvements
- `docs/ARCHITECTURE.md` - Technical implementation details
- `docs/TESTING_MATCHING_RATINGS.md` - Comprehensive test documentation
- `docs/DEPLOYMENT.md` - Production deployment guide
- `docs/MONITORING.md` - Operations and monitoring
- `docs/archive/COMPLETED.md` - Full history of completed features
---
**Last Updated:** 2025-12-03
Reference in New Issue View Git Blame Copy Permalink