# Kimai Heatmap Plugin

## What This Is

A Kimai dashboard widget that displays a GitHub-style activity heatmap visualizing time tracking data. Built as a Symfony bundle plugin for personal time tracking, rendering an interactive d3.js calendar heatmap with click-through navigation, project filtering, streak tracking, and summary stats.

## Core Value

At a glance, see where your time went — a visual map of tracking activity that makes patterns obvious without clicking through reports.

## Requirements

### Validated

- ✓ Dashboard widget renders a d3.js calendar heatmap of time entries — v1.0
- ✓ Filterable by project — v1.0
- ✓ Clicking a day cell navigates to Kimai's timesheet view filtered to that day — v1.0
- ✓ Color scheme uses Kimai's theme CSS variables — v1.0 (partial: tooltip/labels/empty use CSS vars, color scale hardcoded green)
- ✓ Nix flake/devshell provides a local Kimai instance with seeded database — v1.0
- ✓ PHPUnit tests for backend (API, data aggregation) — v1.0
- ✓ JavaScript tests for the d3 heatmap component — v1.0
- ✓ Streak indicator, summary stats, weekend styling — v1.0

### Active

- [ ] Switchable visualization modes (year, week, day, combined day/hour)
- [ ] Native TomSelect entity pickers with customer→project→activity cascade
- [ ] Activity filtering via cascading pickers
- [ ] Toggle between hours-per-day and entry-count display

## Current Milestone: v1.1 Modes & Filtering

**Goal:** Multiple visualization modes and richer filtering using Kimai-native UI components

**Target features:**
- Switchable views: year-mode, week-mode (day-of-week), day-mode (time-of-day), combined day/hour
- Native TomSelect entity pickers replacing plain `<select>` — customer→project→activity cascade
- Activity filtering (descoped from v1.0)
- Toggle between hours-per-day and entry-count display

### Out of Scope

- Billable hours tracking features — personal time tracking only
- Mobile-specific layout — desktop Kimai dashboard only
- Export/sharing of heatmap images — no audience for personal use
- Real-time updates — refresh on page load is fine
- Custom color theme picker — Kimai theme integration is sufficient
- Configurable time range selector — deferred to future milestone
- Multi-user comparison — personal tracking tool

## Context

Shipped v1.0 with ~650 LOC source (PHP + TypeScript) and ~730 LOC tests.
Tech stack: Symfony bundle (PHP 8.2), d3.js v7 (TypeScript), esbuild, Vitest, PHPUnit.
Dev environment: Nix flake with process-compose, MariaDB 11.4, Kimai 2.52.0.

## Constraints

- **Tech stack**: Symfony bundle (PHP) + d3.js (JavaScript), must conform to Kimai plugin architecture
- **Testing**: TDD approach — PHPUnit for backend, JS tests for frontend heatmap
- **Dev environment**: Nix flake/devshell with local Kimai and seeded DB for manual testing
- **Compatibility**: Must work with current Kimai release

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| d3.js for visualization | Flexible, well-suited for calendar heatmaps | ✓ Good |
| Symfony bundle (not local plugin) | Standard Kimai plugin distribution | ✓ Good |
| Kimai theme CSS vars | Visual consistency with dashboard | ⚠️ Partial — color scale hardcoded green (Tabler lacks green scale vars) |
| TDD with PHPUnit + Vitest | Prevent regressions from AI-generated code | ✓ Good — 30+ tests |
| Nix flake for dev environment | Reproducible local Kimai instance | ✓ Good |
| IIFE format with KimaiHeatmap global | Browser compat without Kimai's Webpack Encore | ✓ Good |
| Ship prebuilt JS in Resources/public/ | Avoids hooking into Kimai's build pipeline | ✓ Good |
| Descope activity filtering | Project filter sufficient for personal use | ✓ Acceptable |

---
*Last updated: 2026-04-08 after v1.1 milestone start*