# CLAUDE.md

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

## Commands

### Development
- `dart run bin/xp_nix.dart` - Run the main application
- `dart test` - Run all tests  
- `dart test test/specific_test.dart` - Run a specific test file
- `dart analyze` - Run static analysis
- `dart pub get` - Install dependencies
- `nix develop` - Enter development environment with Dart and SQLite

### Nix Environment
This project uses Nix flakes for development environment management. The flake provides Dart SDK and SQLite with proper library paths configured.

## Architecture Overview

### Dependency Injection & Testing
The codebase uses dependency injection through interfaces to enable both production and testing modes:

- **Interfaces** (`lib/src/interfaces/`): Define contracts for core components
  - `IActivityDetector` - Window/application activity detection
  - `IIdleMonitor` - User idle state monitoring  
  - `IDesktopEnhancer` - Desktop theme/visual enhancements
  - `ITimeProvider` - Time operations (for testing time manipulation)

- **Production Implementations**: Real system integrations (Hyprland, system time)
- **Test Mocks** (`lib/src/testing/`): Controllable implementations for testing

### Core Components

**ProductivityMonitor** - Central orchestrator that:
- Coordinates activity detection, idle monitoring, and desktop enhancement
- Calculates XP rewards based on activity types and time multipliers
- Manages level progression and achievement system
- Handles both event-driven (via IActivityDetector) and polling modes

**Activity Classification System**:
- Uses `ActivityEventType` enum for categorizing activities (coding, meetings, etc.)
- Supports user-defined application classifications stored in database
- Fallback categorization based on application names and window titles

**XP & Gamification**:
- Time-based multipliers for deep work hours vs late night penalty
- Focus session bonuses with milestone rewards (60min, 120min, 180min)
- Level-based visual themes applied via desktop enhancer
- Achievement system with level, focus, and session-based rewards

### Database Schema
SQLite database with tables for:
- Daily stats (XP, focus time, meeting time, level)
- Activity events with duration and metadata
- Application classifications (user-defined)
- Achievements and focus sessions
- Theme change history and streak tracking

### Configuration
JSON-based configuration (`config/xp_config.json`) defines:
- XP multipliers by activity type and time of day
- Achievement definitions and rewards
- Focus session bonus structure
- Monitoring intervals and thresholds

### Web Dashboard
Built-in web server (`lib/src/web/`) provides real-time dashboard at http://localhost:8080 showing stats, recent activities, and progress visualization.

## Testing Strategy

The architecture supports comprehensive testing through:
- Interface-based dependency injection
- Time manipulation via `ITimeProvider`
- Mock implementations that simulate user behavior
- Simulation tests that model complete work days
- Integration tests for idle detection and activity consolidation