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

8.2 KiB
Raw Blame History

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

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

Conventions

Conventions not yet established. Will populate as patterns emerge during development.

Architecture

Architecture not yet mapped. Follow existing patterns found in the codebase.

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 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.

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.