3.9 KiB
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
- ✓ Mode switcher (year/week) and metric toggle (hours/count) — Phase 7
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-09 after Phase 7 complete