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

70
README.md
View File

@@ -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

57
docs/DEPLOYMENT.md
View File

@@ -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

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