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**:
   ```bash
   git clone <repository-url>
   cd know_foolery
   cp .env.example .env
   ```

2. **Start with Docker**:
   ```bash
   docker compose up --build
   ```

3. **Initialize database**:
   ```bash
   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**:
```bash
cd frontend
npm install
npm run dev
```

**Backend Services**:
```bash
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
```bash
npm run dev          # Start development server
npm run build        # Build for production
npm run lint         # Run ESLint
npm run preview      # Preview production build
```

### Backend
```bash
# 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
```bash
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:
   ```bash
   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](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