PokeGoalsHelper/CLAUDE.md

# Claude Development Guidelines

This document establishes development patterns and workflows for maintaining clean, trackable progress on the PokeGoalsHelper2 project.

## Git Workflow

### Branch Naming Convention
Use descriptive branch names following this pattern:
- `feature/description-of-feature`
- `bugfix/description-of-bug`
- `refactor/description-of-refactor`
- `docs/description-of-documentation`

Examples:
- `feature/floating-orb-ui`
- `bugfix/image-buffer-leak`
- `refactor/mvc-architecture`

### Commit Guidelines

#### Commit Early and Often
- Commit after each logical change or completion of a small task
- Don't wait to complete entire features before committing
- Use the TodoWrite tool to track progress and commit when todos are completed

#### Commit Message Format
```
<type>: <brief description>

<optional detailed description>

Related todos: #<todo-id>, #<todo-id>
```

Types:
- `feat`: New feature
- `fix`: Bug fix  
- `refactor`: Code refactoring
- `docs`: Documentation
- `test`: Testing
- `style`: Code formatting/style

Examples:
```
feat: add floating orb UI with expandable menu

Implemented CalcIV-style floating orb that expands to show
detection and filter options. Replaces old button grid layout.

Related todos: #22
```

```
fix: resolve ImageReader buffer leak causing logcat spam

- Increased buffer count from 2 to 3
- Added proper image cleanup in triggerManualDetection()
- Ensures images are closed after processing

Related todos: #buffer-fix
```

### Branch Management

1. **Create branch for each task/feature**
   ```bash
   git checkout -b feature/<description>
   ```

2. **Commit frequently during development**
   ```bash
   git add .
   git commit -m "feat: implement basic orb button structure"
   ```

3. **Push branch and create PR when complete**
   ```bash
   git push origin feature/<description>
   ```

4. **Merge to main and delete feature branch**
   ```bash
   git checkout main
   git merge feature/<description>
   git branch -d feature/<description>
   ```

## Architecture Guidelines

### Separation of Concerns

#### UI Layer (Views)
- Handle only UI interactions and display
- No business logic or direct data manipulation
- Communicate via events/callbacks

#### Business Logic Layer (Controllers/Services)  
- Handle core application logic
- Process data and make decisions
- Independent of UI implementation

#### Data Layer (Models)
- Manage data structures and persistence
- Handle API calls and data transformations
- Pure data operations

### Event-Driven Communication

Use callbacks and event buses to decouple UI from business logic:

```kotlin
// UI publishes events
interface DetectionUIEvents {
    fun onDetectionRequested()
    fun onClassFilterChanged(className: String?)
    fun onDebugModeToggled()
}

// Business logic handles events
class DetectionController : DetectionUIEvents {
    override fun onDetectionRequested() {
        // Handle detection logic
        // Notify UI via callbacks
    }
}
```

### File Organization

```
app/src/main/java/com/quillstudios/pokegoalshelper/
├── ui/
│   ├── FloatingOrbUI.kt           # UI components
│   ├── DetectionOverlay.kt        # Visual overlays
│   └── interfaces/
│       └── DetectionUIEvents.kt   # UI event interfaces
├── controllers/
│   ├── DetectionController.kt     # Business logic
│   └── ScreenCaptureController.kt # Screen capture logic  
├── models/
│   ├── Detection.kt               # Data models
│   ├── PokemonInfo.kt            # Domain models
│   └── DetectionSettings.kt       # Configuration
└── services/
    ├── YOLOOnnxDetector.kt       # YOLO inference
    └── ScreenCaptureService.kt    # Android service
```

## Development Best Practices

### Testing Approach
- Test business logic separately from UI
- Mock UI interactions for controller tests
- Use dependency injection for testability

### Code Quality
- Single responsibility principle
- Minimize coupling between layers
- Use interfaces for dependency injection
- Keep functions small and focused

### Code Style Guidelines

#### Brace Placement
- Opening braces `{` go on the line **below** functions and statements
- This improves visual separation and readability

```kotlin
// Preferred style
fun myFunction()
{
    if (condition)
    {
        // code here
    }
}

// NOT this style
fun myFunction() {
    if (condition) {
        // code here
    }
}
```

#### Variable Naming Conventions
Use different naming patterns to distinguish variable scope at a glance:

- **Local variables**: `snake_case` (e.g., `display_metrics`, `captured_image`, `window_manager`)
- **Member variables**: `camelCase` (e.g., `screenWidth`, `mediaProjection`, `isActive`)
- **Function parameters**: `camelCase` (e.g., `resultData`, `callback`, `className`)
- **Constants**: `UPPER_SNAKE_CASE` (e.g., `TAG`, `BUFFER_COUNT`)

```kotlin
class ExampleClass
{
    // Member variables in camelCase
    private var screenWidth = 0
    private var mediaProjection: MediaProjection? = null
    
    // Function parameters in camelCase
    fun processData(inputData: String, callback: (String) -> Unit)
    {
        // Local variables in snake_case
        val processed_result = inputData.uppercase()
        val final_output = "Result: $processed_result"
        
        callback(final_output)
    }
}
```

#### Benefits of This Style
- **Instant recognition**: Variable scope is immediately visible
- **Improved debugging**: Easy to distinguish locals from members
- **Better readability**: Clean visual structure with separated braces
- **Consistent codebase**: All new code follows the same patterns

### Documentation
- Update this file when patterns change
- Document complex business logic
- Use clear variable and function names
- Add TODO comments for future improvements

## Current Architecture Status

### Phase 1: Current State (Coupled)
- UI and business logic mixed in ScreenCaptureService
- Direct calls between UI and YOLO detector
- Monolithic service class

### Phase 2: Target State (Decoupled)
- Separate UI components with event interfaces
- Controller layer handling business logic
- Clean dependency injection
- Testable, maintainable architecture

## Commit Reminders

Before each commit, ensure:
- [ ] Code follows separation of concerns
- [ ] No business logic in UI classes
- [ ] Interfaces used for layer communication
- [ ] Todo list updated with progress
- [ ] Commit message follows format guidelines
- [ ] Branch name is descriptive

## Claude Instructions

When working on this project:
1. Always create a new branch for each task
2. Commit frequently with descriptive messages
3. Use TodoWrite tool to track progress
4. Follow MVC/event-driven patterns
5. Separate UI logic from business logic
6. Test changes incrementally
7. Update documentation when architecture changes