# 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*