radziel/spotlightcam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update documentation for Phase 3.7 changes

Browse Source 
- Update README.md with beta features, seed commands, resource limits
- Update SESSION_CONTEXT.md with Phase 3.7 changelog and new structure
- Update DEPLOYMENT.md with seeding instructions and resource requirements
- Document Makefile commands, environment reorganization, footer changes
- Update test accounts to use @spotlight.cam domain
- Add production resource allocation table (4 CPU / 8GB server)
- Last updated: 2025-12-06
This commit is contained in:
Radosław Gierwiało
2025-12-06 12:33:01 +01:00
parent e1fabeb297
commit d98222da12
3 changed files with 223 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

151
docs/SESSION_CONTEXT.md
View File

@@ -15,9 +15,9 @@
## Current Status
**Phase:** MVP Complete - Production Ready (Phase 3.6 complete)
**Phase:** MVP Complete - Production Ready (Phase 3.7 complete)
**Tests:** 351/351 backend tests passing - 100% ✅ (73% coverage)
**Recent Work:** Cloudflare integrations (CAPTCHA, TURN/STUN), public pages, responsive design improvements
**Recent Work:** Beta testing features, environment reorganization, footer updates, seed script separation, production resource limits
### Core Features (All Implemented)
- JWT authentication with email verification (AWS SES)
@@ -39,9 +39,13 @@
- Atomic stats updates with race condition prevention
- Clickable usernames in navbar, country flags
- Public profiles (/u/{username}) - accessible without authentication
- Static content pages (About Us, How It Works) - markdown-based
- Static content pages (About Us, How It Works, Privacy Policy) - HTML-based
- Contact form with admin panel
- 404 page with activity logging
- Dedicated Footer component for authenticated users (removed History link)
- GDPR/RODO cookie consent banner
- Google Analytics 4 integration with privacy controls
- Beta testing features (dismissible banner, auto SUPPORTER tier assignment)
- Matches & ratings API
- QR code event check-in
- PWA (offline support, iOS compatible)
@@ -56,39 +60,47 @@
```
/spotlightcam
├── docker-compose.yml # nginx:8080 + frontend + backend + db
├── Makefile # Dev commands (dev-up, seed-dev, seed-prod, test, etc.)
├── docker-compose.yml # nginx:8080 + frontend + backend + db (dev/prod profiles with resource limits)
├── frontend/
│ ├── public/content/ # Static markdown content (about-us.md, how-it-works.md)
│ ├── .env.development # Frontend env vars (VITE_BETA_MODE, VITE_GA_MEASUREMENT_ID)
│ ├── .env.production
│ ├── public/content/ # Static HTML content (about-us.html, how-it-works.html, privacy.html)
│ └── src/
│ ├── pages/ # React pages (Home, Profile, Contact, 404, AboutUs, HowItWorks)
│ ├── pages/ # React pages (Home, Profile, Contact, 404, AboutUs, HowItWorks, Privacy)
│ │ └── admin/ # Admin pages (ActivityLogsPage.jsx, ContactMessagesPage.jsx)
│ ├── components/ # Reusable components
│ │ ├── common/ # TierBadge, CookieConsent, BetaBanner
│ │ ├── layout/ # Navbar (no History link), Layout (with Footer), Footer
│ │ └── events/ # ParticipantsSidebar (user status grouping)
│ ├── contexts/ # AuthContext
│ ├── services/ # api.js, socket.js, webrtcAPI
│ ├── hooks/ # useWebRTC.js (Cloudflare TURN)
│ ├── hooks/ # useWebRTC.js, usePageTracking.js (GA4)
│ ├── utils/ # analytics.js (GA4 integration)
│ └── constants/ # MATCH_STATUS, SUGGESTION_STATUS, etc.
├── backend/src/
│ ├── routes/ # API endpoints (events.js, matches.js, admin.js, webrtc.js, public.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 (351 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
│ ├── webrtc-api.test.js # 9 tests (Cloudflare TURN)
│ └── socket.test.js # 12 tests
├── backend/
│ ├── .env.development # Backend env vars (BETA_AUTO_SUPPORTER)
│ ├── .env.production
│ └── src/
│ ├── routes/ # API endpoints (events.js, matches.js, admin.js, webrtc.js, public.js)
│ ├── controllers/ # Business logic (auth.js with beta auto-tier)
│ ├── 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
│ ├── prisma/
│ │ ├── seed.development.js # Admin + test users + events
│ │ └── seed.production.js # Admin + divisions + competition types only
│ └── __tests__/ # Jest tests (351 tests - 100% passing)
└── 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)
├── GOOGLE_ANALYTICS_SETUP.md # GA4 integration
├── TESTING_MATCHING_RATINGS.md # Test documentation
├── WEBRTC_TESTING_GUIDE.md # WebRTC testing guide
└── archive/ # Archived documentation
```
@@ -112,6 +124,65 @@ Key models:
---
## Recent Changes (2025-12-06)
### Phase 3.7 - Beta Testing & Infrastructure Updates ✅
**Beta features, environment reorganization, footer improvements, seed separation, resource limits**
**Commits:** `a786b1d` (GA4), `3523172` (GDPR cookie consent), `2cab8c3` (profile links), `229aafc` (remove manual matching), `76be8a4` (confirmation modals), `4066bf1` (footer & navbar), `b556abb` (seed scripts), `e1fabeb` (resource limits)
**1. Beta Testing Features**
- Dismissible beta banner (BetaBanner component) controlled by `VITE_BETA_MODE` env var
- Auto-assign SUPPORTER tier to new registrations via `BETA_AUTO_SUPPORTER` env var
- TierBadge component for displaying SUPPORTER/COMFORT badges (Sparkles/Crown icons)
- Badge display in navbar, public profiles, and user lists
- Files: `frontend/src/components/BetaBanner.jsx`, `frontend/src/components/common/TierBadge.jsx`, `backend/src/controllers/auth.js`
**2. Environment Reorganization**
- Moved .env files from root to `frontend/` and `backend/` subdirectories
- Pattern: `.env.{development,production}{,.example}`
- Updated docker-compose.yml to use new paths
- Files: `frontend/.env.development`, `backend/.env.development`, docker-compose.yml
**3. Privacy & Analytics**
- Created dedicated /privacy page with GDPR/RODO compliant privacy policy
- GDPR cookie consent banner (CookieConsent component) with localStorage persistence
- Google Analytics 4 integration with privacy controls
- Cookie consent controls GA initialization
- Files: `frontend/public/content/privacy.html`, `frontend/src/components/common/CookieConsent.jsx`, `frontend/src/utils/analytics.js`
**4. UI/UX Improvements**
- Updated How It Works page with detailed 10-step user guide
- Dedicated Footer component for authenticated users (Layout)
- Removed History link from navbar (desktop & mobile)
- ParticipantsSidebar now groups users by status:
- Available (online + heats) - green dot
- Online - No Heats (yellow dot) - disabled match button
- Offline (gray dot) - faded match button if has heats
- "No heats declared" badge in UserListItem
- Profile links to usernames in Participants tab
- Files: `frontend/src/components/layout/Footer.jsx`, `frontend/src/components/layout/Navbar.jsx`, `frontend/src/components/events/ParticipantsSidebar.jsx`
**5. Database Seeding**
- Split seed.js into seed.development.js and seed.production.js
- Production seed: admin user + divisions + competition types only
- Development seed: everything + test users + events + heats
- Admin account: admin@spotlight.cam (COMFORT tier, isAdmin flag)
- Test users: john/sarah/mike@spotlight.cam (SUPPORTER tier, no wsdcId)
- Makefile commands: `make seed-dev`, `make seed-prod`
- Files: `backend/prisma/seed.development.js`, `backend/prisma/seed.production.js`, `backend/package.json`, `Makefile`
**6. Production Resource Limits**
- Configured docker-compose.yml production profile for 4 CPU / 8GB server
- nginx-prod: 0.5 CPU / 512M (limits), 0.25 CPU / 256M (reserved)
- frontend-prod: 0.5 CPU / 512M (limits), 0.25 CPU / 256M (reserved)
- backend-prod: 1.5 CPU / 2G (limits), 1.0 CPU / 1G (reserved)
- db-prod: 1.0 CPU / 3G (limits), 0.75 CPU / 2G (reserved)
- Total: 3.5 CPU / 6GB limits, leaves ~0.5 CPU / 2GB for host
- File: `docker-compose.yml`
---
## Recent Changes (2025-12-03)
### Chat Enhancements - Complete ✅
@@ -174,18 +245,20 @@ Key models:
```bash
# Start development
docker compose --profile dev up
make dev-up # Or: docker compose --profile dev up
make dev-down # Stop development
# Run all backend tests
docker compose exec backend npm test
# Database seeding
make seed-dev # Seed with development data (admin + test users + events)
make seed-prod # Seed with production data (admin + basic data only)
# 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
# Testing
make test # Run all backend tests
make test-watch # Run tests in watch mode
make test-coverage # Run tests with coverage report
# Admin CLI
make dev-cli # Interactive REPL
docker compose exec backend npm run cli -- users:list --limit 20
# Access
@@ -229,11 +302,15 @@ 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! |
**Admin:**
- admin@spotlight.cam / [password set during seed] (COMFORT tier, isAdmin)
**Test Users:**
| Username | Email | Password | Tier |
|----------|-------|----------|------|
| john_dancer | john@spotlight.cam | Dance123! | SUPPORTER |
| sarah_swings | sarah@spotlight.cam | Swing456! | SUPPORTER |
| mike_blues | mike@spotlight.cam | Blues789! | SUPPORTER |
---
@@ -271,4 +348,4 @@ REST_BUFFER_MINUTES: 60
---
**Last Updated:** 2025-12-03
**Last Updated:** 2025-12-06