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

   git checkout -b feature/<description>
   

2. Commit frequently during development

   git add .
   git commit -m "feat: implement basic orb button structure"
   

3. Push branch and create PR when complete

   git push origin feature/<description>
   

4. Merge to main and delete feature branch

   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:

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