Starting to go places. More testing in place, need to solidify the dashboard api boundary next

2025-06-12 11:36:30 -06:00
commit 8ea06b12f7
44 changed files with 7736 additions and 0 deletions
@@ -0,0 +1,76 @@
+# 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