81 lines
3.4 KiB
Markdown
81 lines
3.4 KiB
Markdown
# 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*
|