# CLAUDE.md

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

## Project Overview

Deskmeter is a productivity tool that measures time spent across desktop workspaces. It consists of four main components:

- **dmcore**: Core tracking daemon (`dmapp/dmcore/main.py`) that monitors active workspace and task changes
- **dmweb**: Flask web application (`dmapp/dmweb/`) for viewing productivity data
- **dmfnt**: Angular frontend (`dmapp/dmfnt/`) for enhanced UI (in development)
- **gnome-extension**: GNOME Shell extension (`gnome-extension/deskmeter-indicator@local/`) that displays current task in the top panel

## Architecture

### Core Components

**Task Management System**: 
- Task definitions stored in files, tracked via `dmapp/dmcore/task.py`
- File modification time monitoring for automatic task switching
- Hierarchical task organization under workspace paths (e.g., `work/default`, `work/dlt`)

**Workspace Tracking**:
- Uses `wmctrl` to detect active X11 workspace (requires XORG, not Wayland)
- Maps workspace indices to labels in `dmapp/dmcore/main.py:desktops`
- Special handling for "work" desktops with automatic task enforcement

**Data Storage**:
- MongoDB backend storing workspace switches with timestamps and durations
- State persistence in `dmapp/dmcore/state.py` for current workspace/task tracking

### Web Interface Structure

**Flask Routes** (`dmapp/dmweb/dm.py`):
- `/` - Today's productivity summary
- `/day/<month>/<day>` - Single day view
- `/calendar` - Google Calendar-style task timeline view (daily/weekly/monthly)
- `/switches` - Raw switch documents view (daily/weekly/monthly)
- `/workmonth` - Monthly calendar showing task totals via `dmapp/dmweb/dmcal.py`
- `/totals` - All-time statistics
- `/api/current_task` - JSON API endpoint returning current task info (for GNOME extension)
- `/api/today` - HTML fragment for AJAX updates

**Task Info API** (`dmapp/dmweb/get_period_times.py`):
- `get_current_task_info()` - Retrieves current task ID and path from MongoDB state collection
- `get_task_path()` - Resolves task ID to path, with automatic task_history fallback
- `get_task_blocks_calendar()` - Groups consecutive switches by task, tracks active/idle time
- `get_raw_switches()` - Returns all switch documents for a period

## Development Commands

### Python Backend

```bash
# Install dependencies
pip install -r requirements.txt

# Start MongoDB service
sudo systemctl start mongod.service

# Run core tracking daemon
cd dmapp/dmcore
python3 main.py

# Run Flask web server
cd dmapp/dmweb  
python3 run.py

# Run tests
cd dmapp/tests
python3 test_dmapp.py
```

### Angular Frontend

```bash
cd dmapp/dmfnt

# Install dependencies
npm install

# Development server
npm run start

# Build for production
npm run build

# Run tests
npm run test
```

### GNOME Extension

```bash
cd gnome-extension

# Install extension
./install.sh

# Restart GNOME Shell (X11 only)
# Alt+F2 → type 'r' → Enter
# (On Wayland: log out and back in)

# Enable extension
gnome-extensions enable deskmeter-indicator@local

# Update extension after changes
./update.sh
# Then restart GNOME Shell

# Debug logs
journalctl -f -o cat /usr/bin/gnome-shell

# Test API endpoint
curl http://localhost:10000/api/current_task
```

### System Setup

The application requires:
- MongoDB running locally
- wmctrl installed (`apt install wmctrl`)
- X11 desktop environment (not Wayland for dmcore; GNOME extension works on both X11/Wayland)
- Python virtual environment recommended

## Key Configuration

**Workspace Labels**: Edit `desktops` tuple in `dmapp/dmcore/main.py:12`
**Work Desktop Mapping**: Configure `work_desktops` dict in `dmapp/dmcore/main.py:13`
**Timezone**: Set in `dmapp/dmcore/main.py:19` using zoneinfo

## Calendar & Switches Visualization

### Overview

Two complementary views for analyzing workspace switching patterns:
- **Calendar View** (`/calendar`) - Google Calendar-style blocks showing when you worked on each task
- **Switches View** (`/switches`) - Granular list of every workspace switch

Both support daily, weekly, and monthly scopes with navigation.

### Calendar View Features

**Visual Design**:
- Task blocks positioned at actual times during the day
- Each task gets consistent color (HSL hue based on task name hash)
- Gradient within each block:
  - Left side (bright) = active time (Plan/Think/Work workspaces)
  - Right side (faded) = idle time (Other/Away workspaces)
  - Gradient split point = active/idle ratio

**Block Grouping**:
- Consecutive switches to same task are merged into blocks
- Minimum durations filter micro-switches:
  - Daily: 60 seconds
  - Weekly: 5 minutes
  - Monthly: 10 minutes

**Data Structure** (`get_task_blocks_calendar()`):
```python
{
    'task_id': str,
    'task_path': str,
    'start': datetime,
    'end': datetime,
    'duration': int,           # total seconds
    'active_seconds': int,     # Plan/Think/Work time
    'idle_seconds': int,       # Other/Away time
    'active_ratio': float      # 0.0 to 1.0
}
```

### Switches View Features

**Visual Design**:
- Each switch row color-coded by task (same colors as calendar)
- Border color and background both use task color for visual grouping
- Active workspaces (Plan/Think/Work) shown bold
- Idle workspaces (Other/Away) shown faded

**Display**:
- Timestamp, workspace name, task path, duration for each switch
- Stats summary showing total switches and total time
- All switches in chronological order

### Task History System

**Problem**: Historic task IDs (from archived task files) display as raw IDs instead of paths.

**Solution**: Automatic on-demand task resolution via `task_history` collection:

1. When displaying unknown task ID, `get_task_path()` tries:
   - Current `tasks` collection (active tasks from `main` file)
   - `task_history` collection (cached historic tasks)
   - File scan: searches all files in `/home/mariano/LETRAS/adm/task/`
2. When found via file scan, stores in `task_history` for next time
3. Returns task_id as fallback if not found anywhere

**Benefits**:
- No manual history loading required
- No dmcore startup overhead
- History populates automatically as you view old data
- Frontend self-sufficient and independent

**Files**:
- Frontend parsing: `dmapp/dmweb/get_period_times.py:parse_task_line()`
- File scanning: `dmapp/dmweb/get_period_times.py:load_task_from_files()`
- Resolution: `dmapp/dmweb/get_period_times.py:get_task_path()`

## Component Integration

### How Task Updates Flow

1. **User switches workspace** → GNOME detects immediately
2. **dmcore polling** (every 2 seconds) → detects workspace change via `wmctrl`
3. **Task enforcement** → dmcore updates MongoDB state collection with current task
4. **GNOME extension** → listens to `workspace-switched` signal, waits 2.2s, queries API
5. **Panel indicator updates** → shows current task path in top panel

### GNOME Extension Architecture

**Location**: `gnome-extension/deskmeter-indicator@local/`

**Files**:
- `extension.js` - Main extension logic, workspace switch listener, API polling
- `metadata.json` - Extension metadata (GNOME 40-47 compatible)
- `stylesheet.css` - Panel indicator styling

**Behavior**:
- Connects to GNOME's `workspace-switched` signal
- Debounces updates by 2.2 seconds after workspace switch
- Queries `/api/current_task` endpoint
- Displays task path in panel, truncates if > 40 chars
- Shows last 2 path segments for long paths (e.g., `.../work/project`)

**Update Workflow**:
1. Edit source files in `gnome-extension/deskmeter-indicator@local/`
2. Run `./update.sh` to copy to `~/.local/share/gnome-shell/extensions/`
3. Restart GNOME Shell (`Alt+F2` → `r` on X11, or log out/in on Wayland)
4. Check logs: `journalctl -f -o cat /usr/bin/gnome-shell`

## Development Notes

- The system enforces task constraints within work desktops - switching to a non-work task automatically reverts to the designated work task
- Task files are monitored for changes to enable automatic context switching
- Web interface runs on port 10000 by default
- Core daemon sleeps for 2 seconds between workspace checks
- GNOME extension debounce delay (2.2s) must be > dmcore polling interval (2s) to ensure MongoDB is updated before API query

## Working on Calendar/Switches Views

### Current Implementation

**Routes** (`dmapp/dmweb/dm.py`):
- `/calendar` and `/switches` must be defined BEFORE the catch-all `/<string:task>` route
- Both support `/<scope>` (daily/weekly/monthly) and `/<scope>/<year>/<month>/<day>`
- Navigation via prev/next date links and tab switching between scopes

**Templates**:
- `calendar_view.html` - 24-hour grid with task blocks positioned by time
- `switches_view.html` - Simple list with task-based color coding
- Both use Jinja2 `|hash` filter for color generation (registered in `__init__.py`)

**Data Flow**:
1. Route extracts date range from URL params
2. Calls `get_task_blocks_calendar()` or `get_raw_switches()`
3. Each function calls `get_task_path()` for task name resolution
4. `get_task_path()` auto-populates `task_history` on cache miss
5. Template renders with inline styles (HSL colors from task name hash)

### Potential Improvements

- **Performance**: Cache `get_task_path()` results in-memory to avoid repeated DB lookups
- **Color collision**: Current hash % 360 can produce similar hues for different tasks
- **Weekly/monthly calendar**: Currently shows sequential blocks, could show multi-column grid like daily view
- **Task filtering**: Add URL param to filter by specific task(s)
- **Export**: Add CSV/JSON export of block or switch data
- **Overlapping blocks**: If switching between tasks within same hour, blocks could overlap visually

### Key Design Decisions

1. **No JavaScript frameworks** - Pure server-rendered HTML with minimal CSS transitions
2. **Task history is frontend-only** - dmcore never touches task_history collection
3. **Color coding consistency** - Same task always gets same color across all views
4. **Gradient indicates work quality** - Visual distinction between active focus and idle time
5. **Multiple thresholds** - Different minimum block durations for different scopes reduces noise

## Tool Development Guidelines

- This is a personal tool, not professionally developed
- reuse as it is as much as possible unless refactor is required explicitly, suggest improvements
- Only modify existing code if it absolutely doesn't make sense to add a new flow