Trivia App

A multi-tenant trivia application for corporate training and team engagement.

📍 New to the project? See FILE_LOCATIONS.md for a complete guide to finding files in the repository.

⚡ Quick Start

Get the entire application running with a single command:

# Clone the repository
git clone <repository-url>
cd trivia-app

# Start all services (PostgreSQL, Redis, Backend, Frontend)
docker compose up

Access the application:

• 🌐 Frontend: http://localhost:5173
• 🔌 Backend API: http://localhost:8000
• 📚 API Documentation: http://localhost:8000/docs
• 🩺 Health Check: http://localhost:8000/health

Features:

• ✅ Automatic database migrations
• ✅ Hot reload for both backend and frontend
• ✅ Full development environment in < 2 minutes
• ✅ No manual setup required

To stop all services:

docker compose down

📖 Need more Docker info? See the comprehensive Docker Development Guide for commands, workflows, and troubleshooting.

---

Project Structure

trivia-app/
├── backend/              # FastAPI backend
│   ├── api/             # API endpoints
│   ├── core/            # Core configuration
│   ├── db/              # Database CRUD operations
│   ├── models/          # SQLAlchemy ORM models
│   ├── schemas/         # Pydantic schemas
│   ├── services/        # Business logic
│   ├── websocket/       # WebSocket handlers
│   ├── integrations/    # External integrations
│   ├── tasks/           # Background tasks
│   ├── alembic/         # Database migrations
│   └── main.py          # Application entry point
├── frontend/            # React frontend
│   └── src/
│       ├── components/  # React components
│       ├── hooks/       # Custom hooks
│       ├── store/       # Zustand state management
│       ├── services/    # API services
│       ├── pages/       # Page components
│       ├── types/       # TypeScript types
│       ├── styles/      # CSS/styles
│       └── lib/         # Utilities
└── docker-compose.yml   # Local development services

Tech Stack

Backend

• Framework: FastAPI 0.104+
• Database: PostgreSQL 13+
• Cache/PubSub: Redis 7+
• ORM: SQLAlchemy 2.0+
• Migrations: Alembic
• Authentication: JWT with refresh tokens
• Real-Time: WebSocket infrastructure for live updates
• Testing: pytest with 80%+ coverage target

Frontend

• Framework: React 18+
• Build Tool: Vite
• State Management: Zustand
• Server State: TanStack Query
• Styling: Tailwind CSS
• HTTP Client: Axios
• Testing: Vitest + React Testing Library

Prerequisites

For Docker Setup (Recommended):

• Docker & Docker Compose
• Git

For Manual Setup:

• Python 3.11+
• Node.js 18+
• Docker & Docker Compose (for PostgreSQL 13+ and Redis 7+)
• Git
• OpenSSL (for JWT secret generation)

Setup Instructions

Option 1: Docker Setup (Recommended) 🐳

Fastest way to get started - runs everything in containers:

# 1. Clone the repository
git clone <repository-url>
cd trivia-app

# 2. Start all services
docker compose up

That's it! The application will:

• ✅ Start PostgreSQL and Redis
• ✅ Build backend and frontend containers
• ✅ Run database migrations automatically
• ✅ Start both services with hot reload enabled

Access the application at:

• Frontend: http://localhost:5173
• Backend: http://localhost:8000
• API Docs: http://localhost:8000/docs

Common Docker Commands:

# Start in background
docker compose up -d

# View logs
docker compose logs -f

# Stop all services
docker compose down

# Rebuild containers after dependency changes
docker compose up --build

# Stop and remove volumes (clean slate)
docker compose down -v

---

Option 2: Manual Setup (Advanced)

If you prefer to run services locally without Docker:

1. Clone the Repository

git clone <repository-url>
cd trivia-app

2. Start Infrastructure Services

docker compose up -d postgres redis

This starts only PostgreSQL and Redis containers.

3. Backend Setup

# Navigate to backend directory
cd backend

# Create virtual environment
# IMPORTANT: Use 'venv' as the directory name (not '.venv')
# This project standardizes on 'venv/' for consistency
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Copy environment file and configure
cp ../.env.example .env

# IMPORTANT: Generate secure JWT secret
# Run this command and add the output to your .env file:
# openssl rand -hex 32

# Initialize database with Alembic
alembic upgrade head

# Run development server
python main.py

Backend will be available at: http://localhost:8000 API Documentation: http://localhost:8000/docs

4. Frontend Setup

# Navigate to frontend directory (from project root)
cd frontend

# Install dependencies
npm install

# Run development server
npm run dev

Frontend will be available at: http://localhost:5173

Development

Running Tests

Backend:

cd backend
PYTHONPATH=.. pytest
PYTHONPATH=.. pytest --cov=backend --cov-report=html

# Run with PostgreSQL (matches CI environment)
# Start PostgreSQL service from project root, then set DATABASE_URL
cd ..
docker-compose up -d postgres
cd backend
DATABASE_URL=postgresql://trivia_user:trivia_pass@localhost:5432/trivia_db PYTHONPATH=.. pytest

# Run WebSocket integration tests
PYTHONPATH=.. pytest tests/integration/test_websocket.py -v

# Run tenant isolation tests
PYTHONPATH=.. pytest tests/integration/test_tenant_isolation.py -v

# Run all integration tests
PYTHONPATH=.. pytest tests/integration/ -v

Alternatively, run from project root:

pytest backend/tests --cov=backend --cov-report=html

Note: Tests use the database specified by the DATABASE_URL environment variable. To run tests against PostgreSQL (for example the instance started via docker-compose), set DATABASE_URL to the Postgres connection string; otherwise tests default to SQLite. CI sets DATABASE_URL to a PostgreSQL 13 instance to match production.

Frontend:

cd frontend
npm test
npm run test:coverage

Database Migrations

Create a new migration:

cd backend
alembic revision --autogenerate -m "description"

Apply migrations:

alembic upgrade head

Rollback migration:

alembic downgrade -1

Code Quality

Backend:

ruff check .
black .

Frontend:

npm run lint

Project Status

Current Sprint: Epic 1 - Platform Foundation & Authentication

✅ Completed Stories (As of February 7, 2026)

• ✅ Story 1.1: Project Initialization & Development Environment Setup (9/9 ACs met)
• ✅ Story 1.2: Organization & User Data Models (9/9 ACs met)
• ✅ Story 1.3: User Registration with Email (10/10 ACs met - backend with tests)

Recent Updates (PR #21 - Feb 2, 2026):

• ✅ Comprehensive CI/CD workflows (Codacy, CodeQL, dependency review)
• ✅ Authentication endpoints fully implemented with JWT
• ✅ Comprehensive test suite (pytest with 80%+ coverage)
• ✅ Code quality tooling (Codacy CLI, linting configurations)
• ✅ BMAD agent framework integration (23 custom agents)
• ✅ Complete documentation suite (README, CONTRIBUTING, architecture docs)
• ✅ Multi-tenant middleware (organization scoping, security isolation)

Recent Updates (PR #29 - Feb 3, 2026):

• ✅ WebSocket Infrastructure implemented for real-time features
  • Connection manager with session-based tracking
  • JWT authentication for WebSocket connections
  • Message broadcasting and session isolation
  • Frontend WebSocket service with auto-reconnection
  • 6 integration tests (100% pass rate)
  • Complete documentation in docs/websocket-infrastructure.md

Recent Updates (Feb 7, 2026):

• ✅ Consolidated CI/CD Pipeline (.github/workflows/ci.yml)
  • Eliminated duplicate test runs (was running 2x per PR)
  • Single workflow for backend and frontend tests
  • PostgreSQL 13 service in CI environment (matches production)
  • 50% reduction in PR feedback time
• ✅ Multi-Tenant Isolation Tests (backend/tests/integration/test_tenant_isolation.py)
  • 130 tests passing with 96.29% coverage (exceeds 80% target)
  • Comprehensive tenant boundary validation
  • End-to-end API security testing
• ✅ Codacy Configuration Optimization
  • 30-40% faster analysis (removed unused runtimes/tools)
  • Proper path exclusions (node_modules, venv, build artifacts)
  • CodeQL now analyzes Python and TypeScript (was GitHub Actions only)

Validation Report: See docs/validation/epic-1-validation-report.md

Quality Metrics (Updated Feb 7, 2026):

• Acceptance Criteria: 28/28 (100%)
• Implementation Quality: 96.3%
• Architecture Compliance: 92%
• Test Coverage: 96.29% (backend) - 130 tests passing
• CI Environment: PostgreSQL 13 (matches production)

🔄 In Progress

• 🔄 Story 1.4: User Login with JWT Authentication (implementation complete, needs frontend integration)
• 🔄 Story 1.5: Session Management & Token Refresh (ready for development)

📋 Upcoming Stories

• Story 1.6: Multi-Tenant Access Control
• Story 1.7: User Profile Management

⚠️ Known Technical Debt & Action Items

Critical (Must Address Before Feature Work):

1. CI/CD Optimization: Consolidate duplicate test runs (Codacy + CodeQL both run tests on every PR) ✅ COMPLETED (Feb 7, 2026)
2. Multi-Tenant Middleware: Implement organization scoping middleware for automatic data isolation ✅ COMPLETED
3. WebSocket Infrastructure: Real-time features not yet implemented (required for Epic 3) ✅ COMPLETED (PR #29)
4. PostgreSQL in CI: Test database uses SQLite in CI vs PostgreSQL in production (potential compatibility issues) ✅ COMPLETED (Feb 7, 2026)

High Priority: 5. Frontend components not yet implemented (placeholders exist) 6. CodeQL only scans GitHub Actions files (needs Python/TypeScript configuration) ✅ COMPLETED (Feb 7, 2026)

Medium Priority: 7. Dependency updates available (FastAPI, Pydantic, React, Vite) 8. No seed data script for development organizations 9. Security headers middleware not implemented

See _bmad-output/implementation-artifacts/action-items-2026-02-02.md for complete action items and _bmad-output/implementation-artifacts/code-review-2026-02-02.md for detailed code review findings.

CI/CD Workflows

The project uses GitHub Actions for continuous integration and code quality. Current workflows:

Active Workflows

CI Pipeline (.github/workflows/ci.yml) - PRIMARY WORKFLOW

• Triggers: Pull requests, pushes to main
• Purpose: Fast feedback on code changes with comprehensive testing
• What it does:
  • Runs backend tests with pytest in PostgreSQL 13 environment
  • Runs frontend tests (with graceful handling when tests not yet implemented)
  • Enforces 80% code coverage threshold
  • Uploads coverage to Codacy and GitHub
  • Executes in ~3-5 minutes (50% faster than previous setup)
• Key Features:
  • ✅ Single test execution per PR (no duplication)
  • ✅ PostgreSQL 13 service matches production environment
  • ✅ Graceful secret handling for external contributors

Codacy Workflow (.github/workflows/codacy.yml)

• Triggers: Weekly schedule (Thursday 5:33 PM UTC), manual
• Purpose: Deep code quality analysis and security scanning
• What it does:
  • Runs Codacy CLI security analysis
  • Generates detailed quality reports
  • Analyzes with optimized tool configuration (ESLint, Semgrep, Trivy)
• Optimization: 30-40% faster due to runtime/tool pruning (Node.js + Python only)

CodeQL Workflow (.github/workflows/codeql.yml)

• Triggers: Weekly schedule (Saturday 11:21 AM UTC), manual
• Purpose: Advanced security vulnerability scanning
• What it does:
  • Analyzes Python, JavaScript/TypeScript code for security issues
  • Uploads results to GitHub Security tab
  • Detects SQL injection, XSS, authentication bypasses, etc.
• Recent Update: Now analyzes Python and TypeScript (was GitHub Actions only)

Security Scheduled (.github/workflows/security-scheduled.yml)

• Triggers: Weekly schedule, pushes to main
• Purpose: Scheduled security scans without impacting PR velocity
• What it does:
  • Deep Codacy CLI analysis
  • CodeQL security scanning
  • Runs on schedule to avoid slowing down development

Other Workflows:

• Greetings: Welcomes new contributors on their first issue/PR
• Summary: AI-powered issue summarization
• Dependency Review (disabled): Planned for dependency vulnerability scanning

Recent CI/CD Improvements (Feb 7, 2026)

✅ Eliminated Duplicate Test Runs:

• Before: Tests ran 2x per PR (Codacy + CodeQL workflows)
• After: Single consolidated CI pipeline
• Impact: 50% reduction in PR feedback time

✅ PostgreSQL in CI:

• Before: SQLite in CI, PostgreSQL in production (compatibility risk)
• After: PostgreSQL 13 service in CI environment
• Impact: Better production parity, catches DB-specific issues

✅ Optimized Analysis Tools:

• Removed 3 unused language runtimes (Dart, Go, Java)
• Removed 4 unused analysis tools
• Result: 30-40% faster Codacy analysis

Known CI/CD Status

✅ Previously Identified Issues - NOW RESOLVED:

• Duplicate test runs → Fixed with consolidated CI pipeline
• No frontend CI → Frontend tests now run in ci.yml workflow
• SQLite vs PostgreSQL mismatch → PostgreSQL 13 service added
• CodeQL limited scope → Now analyzes Python and TypeScript

Architecture

• Multi-tenancy: Row-level isolation via organization_id
• Authentication: JWT access tokens (15min) + refresh tokens (7 days)
• Real-time: WebSocket + Redis Pub/Sub (planned, not yet implemented)
• API Response Format:
  • Success: {data: {...}}
  • Error: {error: {code, message}}

Current Implementation Status

• ✅ Backend API with FastAPI
• ✅ PostgreSQL database with SQLAlchemy ORM
• ✅ JWT authentication with refresh tokens
• ✅ Multi-tenant data models with organization scoping
• ✅ Multi-tenant middleware with automatic filtering
• ✅ Alembic migrations
• ✅ pytest test infrastructure (96.29% coverage, 130 tests)
• ✅ Comprehensive integration tests for tenant isolation
• ✅ WebSocket infrastructure with connection manager
• ✅ WebSocket JWT authentication and message broadcasting
• ✅ Frontend WebSocket service with auto-reconnection
• ✅ Consolidated CI/CD pipeline with PostgreSQL
• ⏳ Redis Pub/Sub (infrastructure ready, not used yet)
• ⏳ Frontend React components (structure exists, components not implemented)

Environment Variables

See .env.example for required environment variables.

⚠️ SECURITY CRITICAL: Before running in any environment:

1. Generate a secure JWT secret:

   openssl rand -hex 32

2. Add the generated secret to your .env file:

   SECRET_KEY=your-generated-secret-here
   

3. Never commit .env to version control

API Documentation

Once the backend is running, access interactive API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Available Endpoints (Epic 1)

• POST /api/v1/auth/register - User registration
• POST /api/v1/auth/login - User login (returns JWT access token)
• POST /api/v1/auth/logout - User logout (clears refresh token)

Validation & Quality Assurance

The project undergoes architectural validation at each epic milestone. Current validation status:

Epic 1 (Stories 1.1-1.3): ✅ APPROVED - 96.3% Quality Score

Key achievements:

• ✅ Multi-tenant row-level isolation implemented correctly
• ✅ Security-first authentication (bcrypt 12 rounds, httpOnly cookies)
• ✅ Clean architecture with proper separation of concerns
• ✅ Comprehensive Pydantic validation schemas
• ✅ Production-ready database design with migrations

See docs/validation/epic-1-validation-report.md for detailed analysis.

Troubleshooting

Common Issues

Database Connection Errors

Problem: FATAL: database "trivia_db" does not exist or connection refused errors

Solutions:

1. Ensure Docker containers are running:

   docker compose ps

2. If containers aren't running:

   docker compose up -d

3. Check PostgreSQL logs:

   docker compose logs postgres

4. Verify database connection settings in .env:

   DATABASE_URL=postgresql://trivia_user:trivia_pass@localhost:5432/trivia_db
   

Alembic Migration Errors

Problem: Target database is not up to date or migration conflicts

Solutions:

1. Check current migration status:

   cd backend
   alembic current
   alembic history

2. Reset to head:

   alembic upgrade head

3. If corrupted, drop and recreate database:

   docker compose down -v
   docker compose up -d
   alembic upgrade head

Test Failures

Problem: Tests fail with import errors or database issues

Solutions:

1. Ensure PYTHONPATH is set when running tests:

   # From backend directory
   PYTHONPATH=.. pytest
   
   # Or from project root
   pytest backend/tests

2. Check pytest.ini configuration is present in backend/
3. Verify test database is configured (uses SQLite automatically)
4. Clear pytest cache if needed:

   rm -rf .pytest_cache __pycache__

JWT Token Issues

Problem: 401 Unauthorized errors or token validation failures

Solutions:

1. Ensure SECRET_KEY is set in .env and is at least 32 characters
2. Generate a secure key:

   openssl rand -hex 32

3. Restart the backend server after changing SECRET_KEY
4. Check token expiration (access tokens expire after 15 minutes)

Port Already in Use

Problem: Address already in use when starting services

Solutions:

1. Check what's using the port:

   # For backend (port 8000)
   lsof -i :8000
   
   # For frontend (port 5173)
   lsof -i :5173
   
   # For PostgreSQL (port 5432)
   lsof -i :5432

2. Kill the process or use a different port:

   # Kill process by PID
   kill -9 <PID>
   
   # Or change port in .env or vite.config.ts

Docker-Specific Issues

Problem: Docker containers fail to start or build

Solutions:

1. Container won't start - "already in use" error:

   # Stop all containers
   docker compose down
   
   # Remove stopped containers
   docker compose rm -f
   
   # Start fresh
   docker compose up

2. Build fails or outdated dependencies:

   # Rebuild containers from scratch
   docker compose build --no-cache
   
   # Or rebuild specific service
   docker compose build --no-cache backend

3. Database migrations not running:

   # Check backend logs
   docker compose logs backend
   
   # Manually run migrations in container
   docker compose exec backend alembic upgrade head

4. Hot reload not working:

   • Ensure volumes are mounted correctly in docker-compose.yml
   • On Windows, you may need to enable file sharing in Docker Desktop settings
   • Try restarting the specific service:

     docker compose restart backend
     # or
     docker compose restart frontend

5. Out of disk space or "no space left on device":

   # Clean up unused Docker resources
   docker system prune -a
   
   # Remove specific volumes (WARNING: deletes data)
   docker compose down -v

6. Frontend shows blank page or can't connect to backend:

   • Check backend is running: docker compose ps
   • Verify backend health: curl http://localhost:8000/health
   • Check CORS settings in backend/.env (should include frontend URL)
   • View frontend logs: docker compose logs frontend

7. Permission denied errors:

   # Fix entrypoint script permissions
   chmod +x backend/docker-entrypoint.sh
   
   # Or rebuild the image
   docker compose build backend

Quick Debug Commands:

# View all container logs
docker compose logs -f

# View specific service logs
docker compose logs -f backend

# Check container status
docker compose ps

# Enter a running container for debugging
docker compose exec backend bash
docker compose exec frontend sh

# Restart a service
docker compose restart backend

# Stop and remove everything (fresh start)
docker compose down -v
docker compose up --build

Frontend Dependencies Issues

Problem: npm install fails or module not found errors

Solutions:

1. Clear npm cache:

   cd frontend
   rm -rf node_modules package-lock.json
   npm cache clean --force
   npm install

2. Ensure Node.js version is 18+:

   node --version

3. Try using npm instead of yarn or vice versa

CI/CD Workflow Failures

Problem: GitHub Actions workflows fail

Common Issues:

1. Missing secrets: Some workflows use CODACY_PROJECT_TOKEN for coverage uploads
   • For external contributors: This is normal – workflows treat CODACY_PROJECT_TOKEN as optional and skip coverage upload steps gracefully
   • For maintainers: CODACY_PROJECT_TOKEN is optional for PR CI but recommended if you want coverage reports uploaded from main/default-branch runs. See CI/CD Setup in CONTRIBUTING.md for setup details.
2. Test failures: Check workflow logs for specific test errors
3. Coverage below 80%: Add more tests to meet the coverage threshold
4. Linting/style issues (Codacy or local checks): The main PR CI workflow runs backend tests and coverage only, but Codacy and local tools may report style problems. Run ruff check . and black . locally to fix these before pushing.

For detailed CI/CD documentation and local testing instructions, see the CI/CD section in CONTRIBUTING.md.

Getting Additional Help

If you encounter issues not covered here:

1. Check existing GitHub Issues
2. Review documentation in docs/ directory
3. Check validation reports for architectural guidance
4. Open a new issue with:
   • Clear description of the problem
   • Steps to reproduce
   • Error messages/logs
   • Environment details (OS, Python version, Node version)

Contributing

We welcome contributions from the development community! This is an open source project aimed at helping organizations create engaging learning experiences through gamified trivia.

📖 For complete contribution guidelines, see CONTRIBUTING.md

🔧 For CI/CD setup and running tests locally, see CI/CD Setup in CONTRIBUTING.md

How to Contribute

1. Fork the repository
2. Create a feature branch from main

   git checkout -b feature/your-feature-name

3. Follow existing code structure and conventions
   • Backend: Follow FastAPI patterns, use type hints, maintain 80%+ test coverage
   • Frontend: Follow React best practices, use TypeScript
   • Write descriptive commit messages
4. Write tests for new features
   • Backend: pytest with comprehensive test cases
   • Frontend: Vitest + React Testing Library
5. Ensure all tests pass

   # Backend (from project root)
   pytest backend/tests
   
   # Or from backend directory
   cd backend && PYTHONPATH=.. pytest
   
   # Frontend
   cd frontend && npm test

6. Update documentation as needed
7. Submit a pull request with a clear description of changes

Code of Conduct

• Be respectful and inclusive
• Provide constructive feedback
• Help others learn and grow
• Focus on what is best for the community

Areas for Contribution

• 🐛 Bug Fixes: Help resolve issues and improve stability
• ✨ New Features: Implement features from the roadmap
• 📝 Documentation: Improve guides, API docs, and examples
• 🧪 Testing: Increase test coverage and quality
• ♿ Accessibility: Enhance WCAG compliance and usability
• 🌐 Internationalization: Add i18n support and translations
• 🎨 UX/UI: Design and implementation improvements
• 🚀 Performance: Optimization and scalability enhancements

Getting Help

• Review existing issues and pull requests
• Check documentation in docs/ directory
• Review validation reports for architectural guidance
• Open an issue for questions or discussions

Development Roadmap

Phase 1: MVP (Month 1-3)

• Epic 1: Platform Foundation & Authentication ← Current
• Epic 2: Session Creation & Management
• Epic 3: Live Trivia Gameplay & Real-Time Scoring
• Epic 4: Educational Feedback & Knowledge Assessment
• Epic 5: Chat Platform Integration

Phase 2: Market Fit Validation (Month 4-6)

• Epic 6: Advanced Engagement Mechanics
• Epic 7: Flexible Participation Modes
• Epic 8: Enterprise Features & AI Customization

Phase 3: Scale & Expansion (Month 7+)

• Epic 9: New Hire Onboarding Specialization

See _bmad-output/planning-artifacts/epics.md for complete epic breakdown.

Support & Documentation

• 📍 File Locations Guide: FILE_LOCATIONS.md - Complete index of all files
• Architecture Document: _bmad-output/implementation-artifacts/architecture.md
• CI/CD Workflows: docs/CI_CD.md - Complete workflow documentation
• 🔒 Multi-Tenancy Guide: docs/MULTI_TENANCY.md - Organization scoping and security
• PRD: _bmad-output/implementation-artifacts/TRIVIA_APP_PRD.md
• UX Specifications: _bmad-output/implementation-artifacts/UI_UX_SPECIFICATIONS.md
• QA Test Strategy: _bmad-output/implementation-artifacts/QA_TEST_STRATEGY.md
• Dev Implementation Record: _bmad-output/implementation-artifacts/dev-agent-record.md
• Validation Reports: docs/validation/

License

This project is licensed under the MIT License - see the LICENSE file for full details.

MIT License Summary

✅ Permissions:

• ✓ Commercial use
• ✓ Modification
• ✓ Distribution
• ✓ Private use

⚠️ Conditions:

• License and copyright notice must be included

❌ Limitations:

• No warranty
• No liability

Copyright (c) 2026 trivia-app Contributors

---

Built with ❤️ by the open source community for learning and development teams everywhere