From 3c26092ea3f4410a4c3f155d97803041103e65dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christopher=20M=C3=BChl?= <toki@toph.so>
Date: Wed, 8 Apr 2026 09:55:55 +0200
Subject: [PATCH] docs: initialize project

---
 .planning/PROJECT.md | 81 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 .planning/PROJECT.md

diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
new file mode 100644
index 0000000..997d3c7
--- /dev/null
+++ b/.planning/PROJECT.md
@@ -0,0 +1,81 @@
+# 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*