diff --git a/README.md b/README.md index fc010cd..da00a96 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,10 @@ Web application (PWA) enabling dance event participants to: - Profile statistics (average rating, reviews) - Responsive mobile layout - 404 page with activity logging for invalid routes -- About Us and How It Works pages (markdown-based static content) +- Static content pages (About Us, How It Works, Privacy Policy) - HTML-based +- Dedicated Footer component for authenticated users +- GDPR/RODO compliant cookie consent banner +- Google Analytics 4 integration with privacy controls ### Admin & Monitoring - Activity Log System with real-time streaming dashboard @@ -95,8 +98,14 @@ Web application (PWA) enabling dance event participants to: ### PWA & Infrastructure - Progressive Web App (offline support, iOS compatible) - Docker Compose orchestration (nginx, frontend, backend, PostgreSQL) + - Development profile: No resource limits + - Production profile: Optimized for 4 CPU / 8GB server (3.5 CPU / 6GB allocated) - PostgreSQL 15 with Prisma ORM (12 tables) - Admin CLI with REPL for operations +- Makefile commands for streamlined development +- Split seed scripts (development vs production data) +- Environment-based configuration (.env.development, .env.production) +- Beta testing mode with account tier auto-assignment --- @@ -133,12 +142,24 @@ docker compose --profile dev up http://localhost:8080 ``` -### 2. Test the application +### 2. Seed the database + +```bash +# Seed with development data (includes test users, events, heats) +make seed-dev + +# Or use npm directly +docker compose exec backend npm run prisma:seed:dev +``` + +### 3. Test the application Use seeded accounts: -- john@example.com / Dance123! -- sarah@example.com / Swing456! -- mike@example.com / Blues789! +- **Admin:** admin@spotlight.cam / [password set during seed] +- **Test users:** + - john@spotlight.cam / Dance123! (SUPPORTER tier) + - sarah@spotlight.cam / Swing456! (SUPPORTER tier) + - mike@spotlight.cam / Blues789! (SUPPORTER tier) **Flow:** 1. Login → Select event → Join chat @@ -155,16 +176,21 @@ docker compose --profile dev down # Rebuild after changes docker compose --profile dev up --build -# Run tests -docker compose exec backend npm test +# Database seeding +make seed-dev # Development data (admin + test users + events) +make seed-prod # Production data (admin + divisions + competition types only) -# Run specific test suite +# Run tests +make test # Run all tests +make test-watch # Run tests in watch mode +make test-coverage # Run tests with coverage report + +# Or use docker compose directly +docker compose exec backend npm test docker compose exec backend npm test -- matching-algorithm.test.js -# Coverage report -docker compose exec backend npm run test:coverage - # Admin CLI +make dev-cli # Interactive REPL docker compose exec backend npm run cli -- users:list --limit 20 ``` @@ -202,23 +228,32 @@ docker compose exec backend npm run cli -- users:list --limit 20 ``` spotlightcam/ +├── Makefile # Development commands (dev-up, seed-dev, test, etc.) ├── docker-compose.yml # Container orchestration (dev + prod profiles) ├── nginx/ # Nginx reverse proxy config ├── frontend/ # React PWA -│ ├── public/content/ # Static markdown content (About Us, How It Works) +│ ├── .env.development # Frontend environment variables (dev) +│ ├── .env.production # Frontend environment variables (prod) +│ ├── public/content/ # Static HTML content (About Us, How It Works, Privacy) │ ├── src/ │ │ ├── components/ # React components +│ │ │ ├── common/ # TierBadge, Footer, CookieConsent, BetaBanner +│ │ │ ├── layout/ # Navbar, Layout, PublicLayout, Footer +│ │ │ └── events/ # ParticipantsSidebar with status grouping │ │ ├── pages/ # Application pages (Home, Profile, Contact, 404) │ │ │ └── admin/ # Admin pages (ActivityLogsPage, ContactMessages) -│ │ ├── hooks/ # Custom hooks (useWebRTC with Cloudflare TURN) +│ │ ├── hooks/ # Custom hooks (useWebRTC, usePageTracking) │ │ ├── contexts/ # AuthContext │ │ ├── services/ # API client, Socket.IO client, WebRTC API +│ │ ├── utils/ # Analytics (GA4 integration) │ │ └── constants/ # Status constants │ ├── Dockerfile # Development container │ └── Dockerfile.prod # Production build ├── backend/ # Node.js + Express API +│ ├── .env.development # Backend environment variables (dev) +│ ├── .env.production # Backend environment variables (prod) │ ├── src/ -│ │ ├── controllers/ # Auth, users, events, WSDC +│ │ ├── controllers/ # Auth (with beta auto-tier), users, events, WSDC │ │ ├── routes/ # API routes (events, matches, admin, webrtc, public) │ │ ├── services/ # Matching algorithm, activity logging │ │ ├── middleware/ # Auth, admin access, message validation (spam protection) @@ -226,7 +261,9 @@ spotlightcam/ │ │ └── __tests__/ # Jest tests (351 tests, 100% passing) │ ├── prisma/ │ │ ├── schema.prisma # Database schema (12 tables) -│ │ └── migrations/ # Database migrations +│ │ ├── migrations/ # Database migrations +│ │ ├── seed.development.js # Development seed (admin + test users + events) +│ │ └── seed.production.js # Production seed (admin + basic data only) │ ├── Dockerfile # Development container │ └── Dockerfile.prod # Production build └── docs/ # Documentation @@ -237,6 +274,7 @@ spotlightcam/ ├── MONITORING.md # Operations & monitoring ├── TESTING_MATCHING_RATINGS.md # Comprehensive test documentation ├── WEBRTC_TESTING_GUIDE.md # WebRTC testing guide + ├── GOOGLE_ANALYTICS_SETUP.md # GA4 integration guide └── archive/ # Archived documentation ``` @@ -394,4 +432,4 @@ TBD --- **Status:** MVP Complete ✅ | 351/351 tests passing (100%) | Production Ready -**Last Updated:** 2025-12-05 +**Last Updated:** 2025-12-06 diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index e00c057..8276b3d 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -32,7 +32,16 @@ docker compose --profile dev up -d docker compose exec backend npx prisma migrate deploy ``` -5. **Access the application** +5. **Seed the database** +```bash +# Development environment - includes test users, events, heats +make seed-dev + +# Or use npm directly +docker compose exec backend npm run prisma:seed:dev +``` + +6. **Access the application** - Frontend: http://localhost:8080 - Backend API: http://localhost:8080/api - Database: localhost:5432 @@ -91,9 +100,53 @@ docker compose --profile prod up -d 6. **Run migrations** ```bash -docker compose --profile prod exec backend-prod npx prisma migrate deploy +docker compose exec backend-prod npx prisma migrate deploy ``` +7. **Seed production database** +```bash +# Production environment - admin user + divisions + competition types only +make seed-prod + +# Or use npm directly +docker compose exec backend-prod npm run prisma:seed:prod +``` + +**Important:** Production seed creates: +- Admin account: admin@spotlight.cam (COMFORT tier, isAdmin flag) +- Divisions: Newcomer, Novice, Intermediate, Advanced, All-Star, Champion +- Competition Types: Jack & Jill, Strictly + +**No test users or events are created in production.** + +--- + +## Server Resource Requirements + +### Recommended Server Specs +- **CPU:** 4 cores minimum +- **RAM:** 8GB minimum +- **Disk:** 50GB SSD (includes OS, Docker images, database) + +### Resource Allocation (Production) +Docker containers configured for 4 CPU / 8GB server: + +| Service | CPU Limit | CPU Reserved | Memory Limit | Memory Reserved | +|---------|-----------|--------------|--------------|-----------------| +| nginx-prod | 0.5 | 0.25 | 512M | 256M | +| frontend-prod | 0.5 | 0.25 | 512M | 256M | +| backend-prod | 1.5 | 1.0 | 2G | 1G | +| db-prod | 1.0 | 0.75 | 3G | 2G | +| **Total** | **3.5** | **2.25** | **6GB** | **3.5GB** | + +Leaves ~0.5 CPU and ~2GB RAM for host system operations. + +**Notes:** +- Limits allow bursting during peak traffic +- Reservations guarantee minimum resources +- PostgreSQL gets most memory for query caching +- Backend gets most CPU for Socket.IO and matching algorithm + --- ## Environment Configuration diff --git a/docs/SESSION_CONTEXT.md b/docs/SESSION_CONTEXT.md index cd4aaad..da793bb 100644 --- a/docs/SESSION_CONTEXT.md +++ b/docs/SESSION_CONTEXT.md @@ -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