know_foolery/README.md

Know Foolery 🎯

A web-based quiz game inspired by the French game "Déconnaissance" where players test their knowledge across various themes and compete for the highest score.

🎮 Game Features

• Multi-themed Questions: Questions across Geography, Science, History, Literature, Movies, Sports, Music, and Art
• Scoring System: 2 points for correct answers without hints, 1 point with hints
• Attempts: Up to 3 attempts per question
• Time Limit: 30-minute game sessions
• Leaderboard: Top 10 players displayed
• Admin Panel: Secure question management with OAuth

🏗 Architecture

Frontend (React + TypeScript)

• React 18 with TypeScript
• Material-UI (MUI) for components
• Vite for build tooling
• Zustand for state management
• React Query for server state

Backend (Python Microservices)

• FastAPI microservices architecture
• SQLAlchemy ORM with SQLite database
• JWT authentication for admin
• Docker containerization
• Nginx reverse proxy

Services

• api-gateway - Main API gateway (Port 8000)
• game-service - Game logic and scoring (Port 8001)
• question-service - Question management (Port 8002)
• player-service - Player management (Port 8003)
• admin-service - Administration panel (Port 8004)

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• Node.js 18+ (for local development)
• Python 3.11+ (for local development)

Development Setup

1. Clone and setup:

   git clone <repository-url>
   cd know_foolery
   cp .env.example .env
   

2. Start with Docker:

   docker compose up --build
   

3. Initialize database:

   docker compose exec game-service python /app/shared/database/init_db.py
   

4. Access the application:

   • Frontend: http://localhost:3000
   • API Gateway: http://localhost:8000
   • API Docs: http://localhost:8000/docs

Local Development

Frontend:

cd frontend
npm install
npm run dev

Backend Services:

cd backend
pip install -r requirements.txt

# Run individual services
cd services/api-gateway
uvicorn app.main:app --reload --port 8000

cd services/game-service  
uvicorn app.main:app --reload --port 8001
# ... repeat for other services

📊 Database Schema

Tables

• themes - Question categories
• questions - Quiz questions with hints and answers
• players - Player information
• game_sessions - Individual game sessions
• game_answers - Player answers and attempts

Sample Data

The database comes pre-loaded with:

• 8 themes (Geography, Science, History, etc.)
• 40+ sample questions across all themes
• Varying difficulty levels (1-4)

🎯 Game Flow

1. Player enters name on home page
2. Game session starts (30-minute timer)
3. Random question presented with theme
4. Player can submit answer (up to 3 attempts) or use hint
5. Scoring applied based on correctness and hint usage
6. Next question or game end
7. Final score saved to leaderboard

🔒 Admin Features

• Authentication: OAuth integration (Auth0/Firebase)
• Question Management: Add, edit, delete questions
• Theme Management: Manage question categories
• Analytics: Player performance and question difficulty analysis
• Bulk Import: CSV/JSON question import capability

🛠 Development Commands

Frontend

npm run dev          # Start development server
npm run build        # Build for production
npm run lint         # Run ESLint
npm run preview      # Preview production build

Backend

# Database operations
python backend/shared/database/init_db.py    # Initialize database

# Testing
pytest backend/                              # Run tests

# Code formatting
black backend/                               # Format Python code
isort backend/                               # Sort imports
flake8 backend/                              # Lint Python code

Docker

docker compose up --build                    # Build and start all services
docker compose up -d                         # Start in background
docker compose down                          # Stop all services
docker compose logs -f [service-name]        # View logs

📁 Project Structure

know_foolery/
├── frontend/                    # React TypeScript app
│   ├── src/
│   │   ├── components/          # React components
│   │   ├── pages/              # Page components
│   │   ├── types/              # TypeScript types
│   │   └── services/           # API services
│   └── package.json
├── backend/
│   ├── shared/                 # Common utilities
│   │   ├── database/           # Database models & connection
│   │   ├── auth/              # Authentication utilities  
│   │   └── utils/             # Shared utilities
│   ├── services/              # Microservices
│   │   ├── api-gateway/       # Main API gateway
│   │   ├── game-service/      # Game logic
│   │   ├── question-service/  # Question management
│   │   ├── player-service/    # Player management
│   │   └── admin-service/     # Admin operations
│   └── database/
│       ├── schema.sql         # Database schema
│       └── seeds/             # Sample data
├── docker compose.yml         # Container orchestration
├── nginx.conf                 # Reverse proxy config
└── README.md

🔧 Configuration

Environment Variables

Copy .env.example to .env and configure:

• DATABASE_URL - Database connection string
• JWT_SECRET_KEY - JWT signing key (change in production!)
• OAUTH_* - OAuth provider configuration
• Service URLs and ports
• Game configuration (timeouts, scoring)

Game Configuration

• Max session duration: 30 minutes (1800 seconds)
• Question timeout: 2 minutes (120 seconds)
• Max attempts per question: 3
• Base scoring: 2 points (no hint), 1 point (with hint)
• Consecutive bonus: 1.1x multiplier per consecutive correct answer

🚀 Deployment

Production Deployment

1. Set environment variables for production
2. Change JWT_SECRET_KEY to a secure value
3. Configure OAuth provider
4. Use production Docker Compose profile:

   docker compose --profile production up -d
   

Scaling Considerations

• Use PostgreSQL instead of SQLite for production
• Add Redis for caching and sessions
• Configure load balancing with multiple service instances
• Use external OAuth provider (Auth0, Firebase Auth)
• Implement logging and monitoring

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: pytest backend/ && npm test --prefix frontend
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

📝 License

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

🙏 Acknowledgments

• Inspired by the French game "Déconnaissance"
• Built with modern web technologies and best practices
• Sample questions curated for educational entertainment