76 lines
3.1 KiB
Markdown
76 lines
3.1 KiB
Markdown
# 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 |