n8r/xp_nix
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d34cccc253
xp_nix/xp_server/CLAUDE.md

3.1 KiB
Raw Blame History

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