Application/CLAUDE.md

CLAUDE.md

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

Build Commands

Build the Project

# On Windows (using gradlew.bat)
.\gradlew.bat build

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

Build and Install Debug APK

# On Windows
.\gradlew.bat assembleDebug

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

Run Tests

# 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

.\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