toph/kimai-plugin-heatmap
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: create roadmap (5 phases)

Browse source
This commit is contained in:
Christopher Mühl 2026-04-08 10:52:40 +02:00
parent 096e187d1f
commit fba1ad4ab1
No known key found for this signature in database
GPG key ID: 925AC7D69955293F
4 changed files with 335 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
.planning/REQUIREMENTS.md
View file

@ -81,34 +81,34 @@ Which phases cover which requirements. Updated during roadmap creation.
| Requirement | Phase | Status |
|-------------|-------|--------|
| DEV-01 | TBD | Pending |
| DEV-02 | TBD | Pending |
| DEV-03 | TBD | Pending |
| PLUG-01 | TBD | Pending |
| PLUG-02 | TBD | Pending |
| PLUG-03 | TBD | Pending |
| HEAT-01 | TBD | Pending |
| HEAT-02 | TBD | Pending |
| HEAT-03 | TBD | Pending |
| HEAT-04 | TBD | Pending |
| HEAT-05 | TBD | Pending |
| HEAT-06 | TBD | Pending |
| HEAT-07 | TBD | Pending |
| HEAT-08 | TBD | Pending |
| INTR-01 | TBD | Pending |
| POLI-01 | TBD | Pending |
| POLI-02 | TBD | Pending |
| POLI-03 | TBD | Pending |
| TEST-01 | TBD | Pending |
| TEST-02 | TBD | Pending |
| TEST-03 | TBD | Pending |
| TEST-04 | TBD | Pending |
| DEV-01 | Phase 1 | Pending |
| DEV-02 | Phase 1 | Pending |
| DEV-03 | Phase 1 | Pending |
| PLUG-01 | Phase 2 | Pending |
| PLUG-02 | Phase 2 | Pending |
| PLUG-03 | Phase 2 | Pending |
| TEST-01 | Phase 2 | Pending |
| TEST-02 | Phase 2 | Pending |
| HEAT-01 | Phase 3 | Pending |
| HEAT-02 | Phase 3 | Pending |
| HEAT-03 | Phase 3 | Pending |
| HEAT-04 | Phase 3 | Pending |
| HEAT-05 | Phase 3 | Pending |
| HEAT-06 | Phase 3 | Pending |
| HEAT-08 | Phase 3 | Pending |
| TEST-03 | Phase 3 | Pending |
| HEAT-07 | Phase 4 | Pending |
| INTR-01 | Phase 4 | Pending |
| TEST-04 | Phase 4 | Pending |
| POLI-01 | Phase 5 | Pending |
| POLI-02 | Phase 5 | Pending |
| POLI-03 | Phase 5 | Pending |
**Coverage:**
- v1 requirements: 22 total
- Mapped to phases: 0
- Unmapped: 22 ⚠️
- Mapped to phases: 22
- Unmapped: 0
---
*Requirements defined: 2026-04-08*
*Last updated: 2026-04-08 after initial definition*
*Last updated: 2026-04-08 after roadmap creation*

113
.planning/ROADMAP.md Normal file
View file

@ -0,0 +1,113 @@
# Roadmap: Kimai Heatmap Plugin
## Overview
Build a Kimai dashboard widget that displays a GitHub-style activity heatmap of time tracking data. The path goes: reproducible dev environment, then prove the plugin loads and serves data, then render the heatmap visualization, then add interaction (click-through, filtering), then polish with stats and visual refinements. Tests are written alongside each feature phase (TDD), not deferred.
## Phases
**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
Decimal phases appear between their surrounding integers in numeric order.
- [ ] **Phase 1: Dev Environment** - Nix flake with local Kimai instance and seeded test data
- [ ] **Phase 2: Plugin Scaffold + Data Layer** - Symfony bundle, dashboard widget, aggregation API with PHPUnit tests
- [ ] **Phase 3: Core Heatmap Rendering** - d3.js calendar grid with color mapping, labels, tooltips, theme integration, and JS tests
- [ ] **Phase 4: Heatmap Interaction** - Click-through navigation, project/activity filtering, interaction tests
- [ ] **Phase 5: Polish** - Streak indicator, summary stats, weekend styling
## Phase Details
### Phase 1: Dev Environment
**Goal**: Developer can run `nix develop` and have a working Kimai instance with test data, ready for plugin development
**Depends on**: Nothing (first phase)
**Requirements**: DEV-01, DEV-02, DEV-03
**Success Criteria** (what must be TRUE):
1. Running `nix develop` drops into a shell with PHP 8.2+, Composer, and Node available
2. A local Kimai instance starts and is accessible in the browser
3. The Kimai instance contains seeded time entry data spanning multiple months
4. A plugin directory is symlinked/mounted so code changes are reflected without reinstallation
**Plans**: TBD
Plans:
- [ ] 01-01: TBD
- [ ] 01-02: TBD
### Phase 2: Plugin Scaffold + Data Layer
**Goal**: Plugin is recognized by Kimai, shows a widget on the dashboard, and serves aggregated daily time data via API
**Depends on**: Phase 1
**Requirements**: PLUG-01, PLUG-02, PLUG-03, TEST-01, TEST-02
**Success Criteria** (what must be TRUE):
1. Kimai discovers the plugin and lists it in the plugin admin page
2. A widget placeholder appears on the Kimai dashboard
3. The API endpoint returns JSON with per-day aggregated hours and entry counts, correctly grouped by the user's timezone
4. PHPUnit tests pass for the data aggregation service and API endpoint
**Plans**: TBD
Plans:
- [ ] 02-01: TBD
- [ ] 02-02: TBD
### Phase 3: Core Heatmap Rendering
**Goal**: The dashboard widget renders a fully styled d3.js calendar heatmap from live Kimai data
**Depends on**: Phase 2
**Requirements**: HEAT-01, HEAT-02, HEAT-03, HEAT-04, HEAT-05, HEAT-06, HEAT-08, TEST-03
**Success Criteria** (what must be TRUE):
1. The widget displays a weeks-by-days calendar grid with cells colored by hours tracked (darker = more hours)
2. Hovering any cell shows a tooltip with date, hours, and entry count
3. Day-of-week labels appear on the Y-axis and month boundary labels along the top
4. Days with no tracked time render with a distinct "no data" color
5. Colors use Kimai's theme CSS variables (works with both light and dark themes)
**Plans**: TBD
**UI hint**: yes
Plans:
- [ ] 03-01: TBD
- [ ] 03-02: TBD
- [ ] 03-03: TBD
### Phase 4: Heatmap Interaction
**Goal**: Users can click through to daily details and filter the heatmap by project or activity
**Depends on**: Phase 3
**Requirements**: HEAT-07, INTR-01, TEST-04
**Success Criteria** (what must be TRUE):
1. Clicking a day cell navigates to Kimai's timesheet view filtered to that specific date
2. A dropdown allows filtering the heatmap to show data for a single project or activity
3. Filtering updates the heatmap in place without a full page reload
4. JavaScript tests verify click navigation and tooltip interaction behavior
**Plans**: TBD
**UI hint**: yes
Plans:
- [ ] 04-01: TBD
- [ ] 04-02: TBD
### Phase 5: Polish
**Goal**: The widget provides at-a-glance context beyond the heatmap itself -- streaks, stats, and visual cues for weekends
**Depends on**: Phase 4
**Requirements**: POLI-01, POLI-02, POLI-03
**Success Criteria** (what must be TRUE):
1. A streak indicator shows the current number of consecutive days with tracked time
2. A summary stats row displays total hours, average hours/day, and the busiest day
3. Weekend days are visually distinct from weekdays (subtle border or opacity difference)
**Plans**: TBD
**UI hint**: yes
Plans:
- [ ] 05-01: TBD
- [ ] 05-02: TBD
## Progress
**Execution Order:**
Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Dev Environment | 0/2 | Not started | - |
| 2. Plugin Scaffold + Data Layer | 0/2 | Not started | - |
| 3. Core Heatmap Rendering | 0/3 | Not started | - |
| 4. Heatmap Interaction | 0/2 | Not started | - |
| 5. Polish | 0/2 | Not started | - |

63
.planning/STATE.md Normal file
View file

@ -0,0 +1,63 @@
# Project State
## Project Reference
See: .planning/PROJECT.md (updated 2026-04-08)
**Core value:** At a glance, see where your time went -- a visual map of tracking activity that makes patterns obvious
**Current focus:** Phase 1: Dev Environment
## Current Position
Phase: 1 of 5 (Dev Environment)
Plan: 0 of 2 in current phase
Status: Ready to plan
Last activity: 2026-04-08 -- Roadmap created
Progress: [░░░░░░░░░░] 0%
## Performance Metrics
**Velocity:**
- Total plans completed: 0
- Average duration: -
- Total execution time: 0 hours
**By Phase:**
| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| - | - | - | - |
**Recent Trend:**
- Last 5 plans: -
- Trend: -
*Updated after each plan completion*
## Accumulated Context
### Decisions
Decisions are logged in PROJECT.md Key Decisions table.
Recent decisions affecting current work:
- [Roadmap]: TDD approach -- tests written alongside features, not in a separate phase
- [Roadmap]: Nix dev environment is Phase 1 prerequisite; everything else depends on it
- [Research]: Use Vitest + jsdom for JS tests (d3 v7 is ESM-only, Jest struggles)
- [Research]: Ship prebuilt JS in Resources/public/, do not hook into Kimai's Webpack Encore
### Pending Todos
None yet.
### Blockers/Concerns
- [Research]: Kimai widget API (WidgetInterface, DI tags) needs verification against target Kimai version
- [Research]: Nix + PHP dev environment can consume days if not timeboxed -- 1 day timebox recommended
## Session Continuity
Last session: 2026-04-08
Stopped at: Roadmap created, ready to plan Phase 1
Resume file: None

134
CLAUDE.md Normal file
View file

@ -0,0 +1,134 @@
<!-- GSD:project-start source:PROJECT.md -->
## Project
**Kimai Heatmap Plugin**
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.
### 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
<!-- GSD:project-end -->
<!-- GSD:stack-start source:research/STACK.md -->
## Technology Stack
## Recommended Stack
### Core Framework (Kimai Plugin)
| Technology | Version | Purpose | Why | Confidence |
|------------|---------|---------|-----|------------|
| PHP | 8.2+ | Plugin runtime | Kimai 2.x requires PHP 8.1 minimum; 8.2 for current features and performance. Verify against Kimai's composer.json. | MEDIUM |
| Symfony | 6.4 LTS | Bundle framework | Kimai 2.x is built on Symfony 6.4 LTS. Plugins must match the host Symfony version exactly. | MEDIUM |
| Kimai | 2.x (latest) | Host application | Target the current stable release. Check github.com/kimai/kimai/releases before starting. | MEDIUM |
### Visualization
| Technology | Version | Purpose | Why | Confidence |
|------------|---------|---------|-----|------------|
| d3 | ^7.9 | Core visualization library | d3 v7 is the current stable. ESM-native, tree-shakeable. Use specific sub-modules, not the full bundle. | HIGH |
| d3-scale | ^4.0 | Color and position scales | Needed for mapping hours/counts to color intensities and day positions. | HIGH |
| d3-selection | ^3.0 | DOM manipulation | Core d3 pattern for binidng data to SVG elements. | HIGH |
| d3-time | ^3.1 | Date calculations | Week/day grid layout calculations for the calendar. | HIGH |
| d3-time-format | ^4.1 | Date formatting | Tooltip and axis labels. | HIGH |
| d3-scale-chromatic | ^3.1 | Color schemes | Provides sequential color scales (Greens, Blues) as starting points before mapping to Kimai theme vars. | HIGH |
| d3-shape | ^3.2 | Rect generation | For the heatmap cell rectangles. | HIGH |
- `cal-heatmap` or other d3-wrapper heatmap libraries: They add abstraction over d3 that limits customization (Kimai theme integration, click-to-navigate, toggle modes). Rolling your own with raw d3 modules is straightforward for a calendar heatmap and gives full control.
- `d3` full bundle import: Import only the sub-modules you need. Keeps the asset small and avoids polluting the Kimai frontend.
### Testing
| Technology | Version | Purpose | Why | Confidence |
|------------|---------|---------|-----|------------|
| PHPUnit | ^10.5 or ^11.0 | Backend tests | Kimai uses PHPUnit for its own tests. Match the version Kimai ships with in its dev dependencies. | MEDIUM |
| Vitest | ^3.0 | JS heatmap tests | Fast, ESM-native, works with d3's ESM modules out of the box. Jest struggles with ESM d3 imports without transformation config. | HIGH |
| jsdom | (via vitest) | DOM environment | Vitest's jsdom environment provides enough DOM for d3 selection/rendering tests without a browser. | HIGH |
- `Jest` for JS tests: d3 v7 is ESM-only. Jest's ESM support requires `--experimental-vm-modules` and transform config. Vitest handles ESM natively.
- `Cypress`/`Playwright` for the heatmap: Overkill for a single widget. SVG output assertions via jsdom + snapshot testing covers the rendering. Save E2E for integration testing against a running Kimai instance if needed later.
### Development Environment
| Technology | Version | Purpose | Why | Confidence |
|------------|---------|---------|-----|------------|
| Nix flake | - | Reproducible dev env | Matches Toph's NixOS infra. Provides PHP, Node, Composer, and a local Kimai instance. | HIGH |
| Composer | ^2.7 | PHP dependency management | Standard for Symfony/Kimai. | HIGH |
| npm | ^10.x | JS dependency management | For d3 modules and Vitest. Simpler than yarn/pnpm for a single-widget plugin. | HIGH |
| esbuild | ^0.24 | JS bundling | Bundle d3 modules into a single file for Kimai's asset pipeline. Faster than webpack, simpler config, handles ESM natively. | HIGH |
- `Webpack Encore`: Kimai's own frontend uses it, but for a plugin shipping a single JS file, esbuild is simpler. One build command, no Symfony Encore config to maintain.
- `Docker` for dev: The project spec calls for Nix flake. Docker would work but adds friction on NixOS and doesn't match the user's infrastructure.
### Database
## Kimai Plugin Structure
### Directory Layout
### Bundle Registration
### Dashboard Widget Registration
### Twig Template Pattern
## Alternatives Considered
| Category | Recommended | Alternative | Why Not |
|----------|-------------|-------------|---------|
| JS Visualization | d3 sub-modules | cal-heatmap | Limits customization for Kimai theme integration, click navigation, and mode toggling |
| JS Visualization | d3 sub-modules | Chart.js matrix | Less control over calendar layout, weaker SVG customization |
| JS Bundler | esbuild | Webpack Encore | Overkill for bundling a single widget's JS. Encore adds Symfony config overhead. |
| JS Testing | Vitest | Jest | d3 v7 is ESM-only; Jest's ESM support requires workarounds |
| JS Language | TypeScript | Plain JS | Type safety for the d3 code, catches data shape mismatches at build time |
| PHP Testing | PHPUnit | Pest | Kimai's own tests use PHPUnit. Consistency with the host app matters. |
| Dev Env | Nix flake | Docker Compose | User runs NixOS; Nix is native. Docker adds a layer. |
## TypeScript for d3
## Installation Commands
# PHP dependencies (in the plugin directory)
# No extra PHP packages needed beyond Kimai's own dependencies
# JS dependencies
## Nix Flake Approach
## Key Version Verification Checklist
- [ ] Kimai latest stable version (check GitHub releases)
- [ ] Kimai's required PHP version (check `composer.json`)
- [ ] Kimai's Symfony version (check `composer.lock`)
- [ ] Kimai's `WidgetInterface` API (check `src/Widget/` in Kimai source)
- [ ] Kimai's Twig widget template blocks (check existing dashboard widgets in Kimai source)
- [ ] Kimai's asset serving mechanism for plugins (may use Symfony AssetMapper now instead of Encore)
- [ ] d3 v7 latest patch version on npm
## Sources
- Kimai plugin documentation: https://www.kimai.org/documentation/plugin-development.html
- Kimai GitHub: https://github.com/kimai/kimai
- d3.js documentation: https://d3js.org/
- d3 calendar heatmap examples: https://observablehq.com/@d3/calendar
- Vitest documentation: https://vitest.dev/
- esbuild documentation: https://esbuild.github.io/
<!-- GSD:stack-end -->
<!-- GSD:conventions-start source:CONVENTIONS.md -->
## Conventions
Conventions not yet established. Will populate as patterns emerge during development.
<!-- GSD:conventions-end -->
<!-- GSD:architecture-start source:ARCHITECTURE.md -->
## Architecture
Architecture not yet mapped. Follow existing patterns found in the codebase.
<!-- GSD:architecture-end -->
<!-- GSD:skills-start source:skills/ -->
## Project Skills
No project skills found. Add skills to any of: `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, or `.github/skills/` with a `SKILL.md` index file.
<!-- GSD:skills-end -->
<!-- GSD:workflow-start source:GSD defaults -->
## GSD Workflow Enforcement
Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.
Use these entry points:
- `/gsd-quick` for small fixes, doc updates, and ad-hoc tasks
- `/gsd-debug` for investigation and bug fixing
- `/gsd-execute-phase` for planned phase work
Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.
<!-- GSD:workflow-end -->
<!-- GSD:profile-start -->
## Developer Profile
> Profile not yet configured. Run `/gsd-profile-user` to generate your developer profile.
> This section is managed by `generate-claude-profile` -- do not edit manually.
<!-- GSD:profile-end -->