# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build Commands

### Build the Project
```bash
# On Windows (using gradlew.bat)
.\gradlew.bat build

# On Linux/Mac (using gradlew)
./gradlew build
```

### Build and Install Debug APK
```bash
# On Windows
.\gradlew.bat assembleDebug

# Install to connected device
adb install -r app\build\outputs\apk\debug\app-debug.apk
```

### Run Tests
```bash
# Unit tests only
.\gradlew.bat test

# Android instrumented tests (requires connected device/emulator)
.\gradlew.bat connectedAndroidTest

# Run specific test class
.\gradlew.bat test --tests com.example.boidelov3.game.GameEngineTest
```

### Clean Build
```bash
.\gradlew.bat clean
```

## Project Architecture

### High-Level Structure
Boidelo is an Android drinking game app built with Java and Gradle. The architecture has evolved from a single-game app to a multi-game platform with a central hub.

**Package Structure:**
- `com.example.boidelov3` - Root package
- `com.example.boidelov3.hub` - Game selection hub (main entry point)
- `com.example.boidelov3.games.boideloclassic` - Original Boidelo game
- `com.example.boidelov3.games.game89` - 89++ card game
- `com.example.boidelov3.games.papelito` - Undercover party game
- `com.example.boidelov3.data` - Data models and repositories
- `com.example.boidelov3.game` - GameEngine (pure Java game logic)
- `com.example.boidelov3.utils` - Utilities (sound, error handling, security)

### Entry Points
- **GameSelectionActivity** (`hub/GameSelectionActivity.java`) - Main hub, displays available games via RecyclerView
- **MainActivity** (`MainActivity.java`) - Legacy entry for Boidelo Classic, being phased out

### Game Flow Pattern
Each game follows this flow:
1. **Setup Activity** - Player configuration (e.g., `BoideloClassicSetupActivity`, `Game89SetupActivity`)
2. **Parameters Activity** - Game settings (e.g., `BoideloClassicParamsActivity`)
3. **Game Activity** - Main gameplay (e.g., `BoideloClassicGameActivity`, `Game89GameActivity`)
4. **End Game Activity** - Results and statistics

### Core Architecture Components

**Data Layer:**
- `QuestionRepository` - Loads questions from JSON assets, manages SharedPreferences
- `Result<T, E>` - Type-safe error handling wrapper (pattern: `Result.success(value)` or `Result.error(error)`)
- `PlayerStats` - Tracks drinks consumed/distributed per player
- `Question` - Rich model with variants, manches (rounds), distribution flags
- `QuestionCategory` - Categorization with styling (colors, icons)

**Business Logic:**
- `GameEngine` - Pure Java game logic, isolated from Android framework for testability
- `OpenAIService` - AI-powered question generation via ChatGPT API
- `ChatGPTTask` - Async task for AI question generation

**UI Patterns:**
- Material Design 3 components
- RecyclerView for game selection
- Dynamic player input (add/remove fields)
- Haptic feedback and sound effects

### Question Processing Pipeline
Questions go through several transformations before display:
1. Load from `assets/questions.json` (150+ questions)
2. Replace player placeholders (`<J1>`, `<J2>`, `<J3>`)
3. Process variants (`<variante>`)
4. Handle manches (round challenges with countdown)
5. Add drink count and verb conjugation
6. Apply category-based styling

### Persistence
- **SharedPreferences** - Player names, settings, asked questions tracking, statistics
- **JSON Assets** - Pre-loaded question database
- **BuildConfig** - API keys (stored in `local.properties`, not version-controlled)

### Security Configuration
- API keys stored in `local.properties` (excluded from git)
- `SecureConfig` utility for secure access
- Database credentials in BuildConfig are intentionally empty (use backend API)

### Testing Infrastructure
- Unit tests in `app/src/test/java/com/example/boidelov3/`
- `GameEngineTest` - 15 tests for game logic
- `ResultTest` - Error handling wrapper tests
- `QuestionCategoryTest` - Category validation tests
- `PlayerStatsTest` - Player statistics tracking tests
- Game-specific tests in subpackages (e.g., `games/papelito/`, `games/game89/`)
- JUnit 4 framework
- Mockito 5.7.0 for mocking

**Test Patterns:**
- Each game has comprehensive test coverage (15+ tests per game)
- Tests cover: setup/teardown, edge cases, state transitions, player management, win conditions
- Defensive copy testing for collections

### Important Files
- `app/build.gradle` - Dependencies, build config, BuildConfig fields
- `local.properties` - Local SDK path and API keys (not in git)
- `assets/questions.json` - Question database

### Resource Management Conventions
**Layout Naming:** `activity_<game>_<screen>.xml`
- `activity_<game>_setup.xml` - Player configuration
- `activity_<game>_game.xml` - Main game screen
- `activity_<game>_result.xml` - Results screen
- `dialog_<game>_<purpose>.xml` - Custom dialogs

**String Resources:** Internationalized strings in `res/values/strings.xml`, organized by game with clear prefixes (e.g., `papelito_`, `boidelo_`, `game89_`)

**Drawables:** Game icons follow `ic_<gamename>.xml` pattern in `res/drawable/`

### Game Registration (GameInfo System)
Games are registered in `GameSelectionActivity.setupGamesList()` via the `GameInfo` class. Each entry includes:
- Game name (enum value)
- Display name (string resource)
- Description (string resource)
- Icon resource
- Availability flag

Games are launched via Intent using `GameType` enum values.

### Adding a New Game
1. Create package under `com.example.boidelov3.games.<gamename>`
2. Implement setup, parameters, and game activities
3. Create `GameInfo` entry in `GameSelectionActivity.setupGamesList()`
4. Add game icon/drawable resources
5. Follow existing patterns for player management and game flow

### Dependencies
- AndroidX AppCompat 1.7.0
- Material Design 1.12.0
- ConstraintLayout 2.2.0
- OkHttp 4.12.0
- Gson 2.11.0
- pgjdbc-ng 0.8.3 (PostgreSQL - currently unused)
- JUnit 4.13.2
- Mockito 5.7.0
- AndroidX Test JUnit 1.2.1
- Espresso 3.6.1

### Build Configuration
- `minSdk`: 24 (Android 7.0+)
- `targetSdk`: 35
- `compileSdk`: 35
- Java 8 compatibility
- Namespace: `com.example.boidelov3`