kimai-plugin-heatmap/.planning/PROJECT.md

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 use, rendering an interactive d3.js calendar heatmap on the Kimai dashboard.

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

(None yet — ship to validate)

Active

• Dashboard widget renders a d3.js calendar heatmap of time entries
• Heatmap cells toggle between hours-per-day and entry-count display
• Configurable time range (not locked to a single preset)
• Filterable by project and/or activity
• Clicking a day cell navigates to Kimai's timesheet view filtered to that day
• Color scheme uses Kimai's theme variables
• Nix flake/devshell provides a local Kimai instance with seeded database
• PHPUnit tests for backend (API, data aggregation)
• JavaScript tests for the d3 heatmap component

Out of Scope

• Billable hours tracking features — this is for personal time tracking
• Mobile-specific layout — desktop Kimai dashboard only
• Export/sharing of heatmap images
• Real-time updates — refresh on page load is fine

Context

• Kimai is a self-hosted time tracking application built on Symfony
• Plugins are Symfony bundles, installable via composer
• The user runs Kimai for personal time tracking, not billable client work
• d3.js is the visualization library of choice for the heatmap
• Development follows TDD — tests written first to prevent AI-generated regressions
• Local development uses a Nix flake/devshell with a running Kimai instance and seeded test data
• The user's infra runs on NixOS

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, user preference	— Pending
Symfony bundle (not local plugin)	Standard Kimai plugin distribution, composable	— Pending
Kimai theme colors (not custom)	Visual consistency with the rest of the dashboard	— Pending
TDD with PHPUnit + JS tests	Prevent regressions from AI-generated code	— Pending
Nix flake for dev environment	Reproducible local Kimai instance, matches user's NixOS infra	— Pending

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition (via /gsd-transition):

1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

After each milestone (via /gsd-complete-milestone):

1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---

Last updated: 2026-04-08 after initialization