<div align="center">
<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
</div>

# Kaboot

Kaboot is an AI-powered quiz party game inspired by Kahoot. It leverages the Google Gemini API to instantly generate engaging quizzes on any topic, allowing users to host and join multiplayer games with ease.

## Features

- **AI Quiz Generation**: Create full quizzes in seconds by simply providing a topic or prompt using Google Gemini.
- **Real-time Multiplayer**: Host games and have players join via game pins using Peer-to-Peer technology.
- **Single-player Arcade Mode**: Play against AI bots to sharpen your skills.
- **Secure Authentication**: Integrated with Authentik for robust OIDC-based user management.
- **Quiz Library**: Save, manage, and reuse your AI-generated quizzes.
- **Dynamic UI**: A premium, responsive interface built with React, Framer Motion, and Lucide.

## Architecture

Kaboot is built with a modern decoupled architecture:

- **Frontend**: React (Vite) with PeerJS for real-time communication.
- **Backend**: Node.js Express server managing the quiz database and session state.
- **Database**: SQLite (Better-SQLite3) for lightweight, reliable data storage.
- **Identity Provider**: Authentik (running in Docker) providing OIDC authentication.
- **Infrastructure**: Redis and PostgreSQL (supporting Authentik).
- **AI Engine**: Google Gemini API for intelligent content generation.

## Prerequisites

Before you begin, ensure you have the following installed:

- **Docker & Docker Compose**: For running the backend services and authentication.
- **Node.js (v18+)**: For local frontend development.
- **Google Gemini API Key**: Required for AI quiz generation.

## Quick Start

The fastest way to get Kaboot running is using Docker Compose.

### 1. Initialize Environment
Run the setup script to generate necessary secrets and create your `.env` file:

```bash
chmod +x scripts/setup.sh
./scripts/setup.sh
```

### 2. Configure Gemini API
Open the newly created `.env` file and add your Gemini API key:

```env
GEMINI_API_KEY=your_api_key_here
```

### 3. Start Services
Launch the entire stack using Docker Compose:

```bash
docker compose up -d
```

This will start:
- **Authentik** (Port 9000)
- **PostgreSQL** & **Redis** (Internal)
- **Kaboot Backend** (Port 3001)

### 4. Setup Authentication
Follow the [Authentik Setup Guide](docs/AUTHENTIK_SETUP.md) to configure the OIDC provider.

## Development Setup

If you want to run the frontend in development mode with hot-reloading:

1. **Install Dependencies**:
   ```bash
   npm install
   ```

2. **Run Development Server**:
   ```bash
   npm run dev
   ```
   The frontend will be available at `http://localhost:5173`.

### Mobile/Network Access

To access the dev server from other devices (phones, tablets):

1. **Run setup script** - it auto-detects your IP:
   ```bash
   ./scripts/setup.sh
   ```

2. **Update Authentik redirect URIs** to include your IP (e.g., `http://192.168.1.100:5173/callback`)

3. **Start dev server with host binding**:
   ```bash
   npm run dev -- --host
   ```

4. **Access from mobile** via `http://<your-ip>:5173`

## Configuration

Kaboot uses environment variables for configuration. Refer to `.env.example` for a complete list.

| Variable | Description | Default |
|----------|-------------|---------|
| `KABOOT_HOST` | Host IP/domain for network access | `localhost` |
| `KABOOT_FRONTEND_PORT` | Port for the frontend dev server | `5173` |
| `KABOOT_BACKEND_PORT` | Port for the Express backend | `3001` |
| `AUTHENTIK_PORT_HTTP` | Port for Authentik web interface | `9000` |
| `GEMINI_API_KEY` | Your Google Gemini API key | (Required) |
| `PG_PASS` | PostgreSQL password for Authentik | (Generated) |
| `AUTHENTIK_SECRET_KEY` | Secret key for Authentik | (Generated) |

## Testing

### Backend Tests
To run the backend test suite:

```bash
cd server
npm install
npm test
```

## Documentation

- [Authentik Configuration](docs/AUTHENTIK_SETUP.md)
- [API Reference](docs/API.md)

## Troubleshooting

- **Authentik Initial Setup**: If you can't access the setup page, ensure `authentik-server` container is healthy using `docker compose ps`.
- **CORS Errors**: Verify that `CORS_ORIGIN` in your `.env` matches your frontend URL.
- **Gemini API Issues**: Ensure your API key is valid and has sufficient quota. Check the browser console for specific error messages from the GenAI SDK.
- **Database Locked**: If you encounter SQLite locking issues, ensure only one instance of the backend is writing to the database volume.

---

View your app in AI Studio: [https://ai.studio/apps/drive/1N0ITrr45ZWdQvXMQNxOULCmJBQyaiWH8](https://ai.studio/apps/drive/1N0ITrr45ZWdQvXMQNxOULCmJBQyaiWH8)