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

Code Style Guidelines

Brace Placement

• Opening braces { go on the line below functions and statements
• This improves visual separation and readability

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

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

Build Commands

Compilation

JAVA_HOME="C:\\Program Files\\Android\\Android Studio\\jbr" ./gradlew assembleDebug

Compilation (Skip Lint)

JAVA_HOME="C:\\Program Files\\Android\\Android Studio\\jbr" ./gradlew assembleDebug -x lint

Lint Check

JAVA_HOME="C:\\Program Files\\Android\\Android Studio\\jbr" ./gradlew lintDebug

Type Check

JAVA_HOME="C:\\Program Files\\Android\\Android Studio\\jbr" ./gradlew compileDebugKotlin

Note: The key is using JAVA_HOME pointing to Android Studio's JBR (Java Runtime) and using ./gradlew (not gradlew.bat or cmd.exe).

Atlassian Integration

This project is connected to the following Atlassian resources:

Jira Project

• Cloud ID: 99236c42-6dc2-4abb-a828-8ad797987eb0
• Project: PokeGoalsHelper (Key: PGH)
• URL: https://quillstudios.atlassian.net
• Available Issue Types: Task, Sub-task

Confluence Space

• Cloud ID: 99236c42-6dc2-4abb-a828-8ad797987eb0
• Space: PokeGoalsHelper (Key: PokeGoalsH, ID: 98676)
• URL: https://quillstudios.atlassian.net/wiki

When referencing Jira or Confluence in conversations, always use these project identifiers.

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
8. Use the build commands above for compilation testing
9. When asked about Jira/Confluence, use the Atlassian resources defined above

JIRA Management Guidelines

Task Status Updates

• NEVER edit task descriptions to update status or progress
• ALWAYS use comments to provide status updates instead
• Preserve original task descriptions - they document the original intent and requirements
• Comments should include: current progress, blockers, next steps, implementation notes

Task Completion Rules

• NEVER mark tasks as "Done" without explicit user approval
• Code compilation ≠ task completion - must be tested on actual device
• Implementation complete ≠ task complete - requires validation and testing
• Always check with user before transitioning tasks to "Done" status
• Use "In Progress" for actively worked tasks, even if implementation is complete

Progress Documentation

• Use comments for progress updates:

  Progress Update:
  ✅ Implementation complete - added close functionality to drawer
  ✅ Compilation successful 
  🔄 Next steps: Device testing required before marking complete
  📋 Files modified: ResultsBottomDrawer.kt, enhanced swipe-to-dismiss
  

Status Workflow

1. To Do → Start working
2. In Progress → Implementation and testing in progress
3. Ready for Review → Implementation complete, needs device testing/validation
4. Done → Only after user confirmation that feature works as expected

Implementation vs Completion

• Implementation Complete: Code written, compiles, logic appears correct
• Task Complete: Feature tested on device, user validated, works as intended
• Always distinguish between these two states in updates

Example Comment Format

**Implementation Progress:**
- ✅ Added swipe-to-dismiss functionality 
- ✅ Enhanced close buttons in both states
- ✅ Build compilation successful
- 🔄 **Pending**: Device testing to validate gesture behavior
- 🔄 **Pending**: User validation of close functionality

**Technical Details:**
- Modified touch handling in ResultsBottomDrawer.kt
- Enhanced gesture detection for full dismiss vs collapse
- Added header close button for expanded state

**Next Steps:**
- Device testing required
- User validation needed before marking Done

This preserves original task intent while providing clear progress visibility.