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

### 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