# Project Research Summary

**Project:** Kimai Heatmap Plugin
**Domain:** Time-tracking dashboard widget (Symfony bundle + d3.js visualization)
**Researched:** 2026-04-08
**Confidence:** MEDIUM

## Executive Summary

This is a Kimai 2.x plugin that adds a GitHub-style activity heatmap to the dashboard. The product pattern is well-established: calendar grid, color intensity for activity levels, tooltips, click-through navigation. The technology choices are straightforward -- a Symfony bundle for the backend (matching Kimai's framework), d3.js sub-modules for the SVG visualization, TypeScript for type safety, and esbuild for bundling. No additional database is needed; the plugin reads from Kimai's existing timesheet table.

The recommended approach is a strict 4-phase build: plugin scaffold first (prove the widget appears on the dashboard), then data layer (aggregation API), then visualization (d3 heatmap rendering), then interactivity (filters, toggles, click navigation). This ordering is dictated by hard dependencies -- you cannot render a heatmap without data, and you cannot build data queries without a working plugin scaffold. The Nix dev environment setup is a prerequisite phase that should be timeboxed to one day.

The primary risks are: (1) Kimai's plugin API is under-documented and shifts between releases -- the widget interface, DI tags, and asset conventions all need verification against the target Kimai version before writing code; (2) timezone-incorrect day aggregation will produce wrong data silently -- aggregation must happen server-side in the user's configured timezone; (3) the Nix + PHP + Kimai dev environment setup can consume days if not timeboxed. All three are manageable with the mitigations outlined below.

## Key Findings

### Recommended Stack

The plugin is a standard Symfony bundle running inside Kimai 2.x. The frontend is a self-contained d3.js visualization bundled with esbuild and shipped as a single JS file in `Resources/public/`. No integration with Kimai's Webpack Encore build is needed or desired.

**Core technologies:**
- **PHP 8.2+ / Symfony 6.4 LTS**: Must match Kimai's runtime exactly. Verify against Kimai's `composer.json`.
- **d3.js sub-modules** (d3-scale, d3-selection, d3-time, d3-time-format, d3-scale-chromatic, d3-shape): Selective imports keep bundle size to ~50-80KB vs ~500KB for full d3.
- **TypeScript**: d3 v7 ships types. Catches data shape bugs at build time. esbuild handles `.ts` natively.
- **esbuild**: Single-command bundling of d3 modules into one JS file. Simpler than Webpack Encore for a single widget.
- **Vitest + jsdom**: ESM-native testing for d3 code. Jest struggles with d3 v7's ESM-only modules.
- **PHPUnit**: Matches Kimai's own test framework.
- **Nix flake**: Reproducible dev env with PHP 8.2, Composer, Node 22, SQLite.

### Expected Features

**Must have (table stakes):**
- Calendar grid layout (weeks x days) with color intensity mapping
- Tooltip on hover showing date, hours, entry count
- Day-of-week and month labels
- Empty state rendering (no-data days visible, not invisible)
- Click-through to Kimai timesheet filtered by date
- Kimai theme integration via CSS variables
- Default trailing 12-month range

**Should have (differentiators):**
- Toggle between hours/day and entry count (different questions answered)
- Project/activity filter dropdown
- Configurable time range (3/6/12 months)
- Streak indicator and summary stats row

**Defer indefinitely:**
- Hour-of-day matrix, export/share, goal setting, animations, multi-user, mobile layout, custom color picker -- all anti-features for a personal tracking widget.

### Architecture Approach

The architecture follows a clean separation: thin Twig template (HTML shell + controls), XHR data fetching from a dedicated API controller, and client-side d3 rendering. The widget registers via Kimai's `WidgetInterface` + `kimai.widget` DI tag. Data flows from Kimai's timesheet table through a `HeatmapService` (Doctrine QueryBuilder, GROUP BY date, user-scoped), to a `HeatmapController` (JSON API), to the d3 module (SVG rendering).

**Major components:**
1. **KimaiHeatmapBundle** -- Symfony bundle class implementing `PluginInterface`, auto-discovered by Kimai
2. **HeatmapWidget** -- `WidgetInterface` implementation, registers on dashboard, renders Twig template
3. **HeatmapController** -- API endpoint (`/api/plugins/heatmap/data`) returning aggregated JSON
4. **HeatmapService** -- Server-side aggregation (hours/count per day, timezone-aware, user-scoped)
5. **d3 heatmap module** -- TypeScript, calendar grid rendering, event handling, theme integration

### Critical Pitfalls

1. **Kimai plugin API instability** -- Pin to a specific Kimai version. Write an integration test that boots the Symfony kernel with the plugin loaded. Subscribe to Kimai releases for breaking change awareness.
2. **Timezone mismatch (PHP vs JS day boundaries)** -- Aggregate by day on the PHP side using `$user->getTimezone()`. Send date strings to the frontend, never raw timestamps. Compare output against Kimai's own reports.
3. **Widget system misunderstanding** -- Use `WidgetInterface` + `kimai.widget` DI tag from the start. Do not build a standalone controller page. Study existing Kimai widgets before coding.
4. **Asset loading failures** -- Ship prebuilt JS in `Resources/public/`, loaded via `<script>` in Twig. Do not hook into Kimai's Webpack Encore. Start with inline script as fallback.
5. **Nix + PHP dev environment** -- Timebox to 1 day. Use SQLite. Set `COMPOSER_HOME` to a writable temp dir. Fall back to Docker if stuck.

## Implications for Roadmap

### Phase 0: Development Environment
**Rationale:** Everything blocks on a working Kimai instance with the plugin loaded. Nix+PHP setup is the highest-risk non-code task.
**Delivers:** `nix develop` shell with PHP 8.2, Composer, Node 22, local Kimai on SQLite, plugin symlinked into `var/plugins/`.
**Avoids:** Pitfall 5 (Nix+PHP complexity) -- timeboxed to 1 day with Docker fallback.

### Phase 1: Plugin Scaffold + Data Layer
**Rationale:** Proves the plugin loads, widget appears on dashboard, and data flows correctly. These are the hardest unknowns (Kimai plugin API, widget system, timezone aggregation).
**Delivers:** Empty widget visible on dashboard. API endpoint returning correct per-day aggregated JSON. PHPUnit tests for service and controller.
**Addresses:** Table stakes groundwork (no visible features yet, but the pipeline works end-to-end).
**Avoids:** Pitfalls 1, 2, 3, 7 (plugin API, timezone, widget system, asset loading).

### Phase 2: Core Heatmap Visualization
**Rationale:** With data flowing, build the actual product. The calendar grid with all table-stakes features is the MVP.
**Delivers:** d3 calendar heatmap rendering from API data. Tooltips, labels, empty state, click-through, theme integration.
**Addresses:** All table-stakes features from FEATURES.md.
**Avoids:** Pitfalls 4, 8, 9 (d3 bundle size, color theming, empty state).

### Phase 3: Interactivity and Polish
**Rationale:** Differentiators that make the widget genuinely useful beyond a static picture. Low complexity, high value.
**Delivers:** Hours/count toggle, project filter dropdown, configurable time range, streak indicator, summary stats.
**Addresses:** All differentiator features from FEATURES.md.
**Avoids:** Pitfall 10 (hardcoded URLs -- generate timesheet URL template server-side).

### Phase Ordering Rationale

- Phase 0 before everything: no plugin code without a working dev environment.
- Phase 1 combines scaffold + data because the scaffold alone is not testable in a meaningful way -- you need data flowing to confirm the widget system integration works.
- Phase 2 is pure frontend work that depends on Phase 1's API but is otherwise independent.
- Phase 3 layers interactivity onto an already-working heatmap. Each feature is independently shippable.
- This ordering front-loads risk: the hardest unknowns (Kimai plugin API, widget system, timezone handling) are resolved in Phase 1. Phases 2 and 3 use well-established d3 patterns with high confidence.

### Research Flags

Phases likely needing deeper research during planning:
- **Phase 0:** Kimai Nix setup is uncommon. May need to inspect current Kimai `composer.json` and PHP extension requirements live.
- **Phase 1:** Kimai's `WidgetInterface`, DI tags, and route registration need verification against the target Kimai version. The plugin API documentation is sparse -- reading existing plugin source code is essential.

Phases with standard patterns (skip research):
- **Phase 2:** d3 calendar heatmap is a well-documented pattern with official Observable examples. TypeScript + esbuild bundling is straightforward.
- **Phase 3:** Filter dropdowns, toggle buttons, and URL template interpolation are standard frontend work.

## Confidence Assessment

| Area | Confidence | Notes |
|------|------------|-------|
| Stack | MEDIUM | PHP/Symfony/d3 choices are solid. Exact Kimai version requirements need live verification. |
| Features | MEDIUM-HIGH | GitHub-style heatmap is a proven pattern. Feature priorities are well-reasoned from reference products. |
| Architecture | MEDIUM | Symfony bundle + API + d3 rendering is sound. Kimai-specific widget API details (interface methods, DI tags, Twig blocks) need verification. |
| Pitfalls | MEDIUM-HIGH | Timezone and d3 pitfalls are universal and well-understood. Kimai-specific pitfalls (plugin API instability, asset pipeline) based on training data, not live docs. |

**Overall confidence:** MEDIUM

### Gaps to Address

- **Kimai widget API verification**: The exact `WidgetInterface` methods, `AbstractWidgetType` hierarchy, and `kimai.widget` DI tag must be verified against the target Kimai release. This is the single biggest unknown.
- **Kimai asset serving for plugins**: Whether Kimai uses `assets:install` to copy `Resources/public/` to `public/bundles/` or has a different mechanism needs checking.
- **Kimai CSS variable names**: The actual theme variable names for colors are unknown. Fallback values mitigate this, but proper theme integration requires inspecting a running Kimai instance.
- **Kimai timesheet URL structure**: The route name and filter parameter format for click-through navigation must be verified.
- **Twig widget template blocks**: The exact block names (`widget_content`, `widget_javascript`) and base template path need verification.

## Sources

### Primary (HIGH confidence)
- d3.js documentation and calendar heatmap patterns (d3js.org, Observable)
- Symfony bundle system documentation (symfony.com)
- Vitest and esbuild documentation
- General timezone handling and SVG performance patterns

### Secondary (MEDIUM confidence)
- Kimai plugin development documentation (kimai.org/documentation/plugin-development.html) -- from training data
- Kimai GitHub repository structure and existing plugins -- from training data
- Kimai widget system internals -- from training data

### Tertiary (LOW confidence)
- Kimai Twig template block names and asset path conventions -- inferred, needs validation
- Kimai CSS custom property names -- inferred, needs validation

---
*Research completed: 2026-04-08*
*Ready for roadmap: yes*