From fba1ad4ab1231c009b8a7e8f7dcc874c28a234d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christopher=20M=C3=BChl?= Date: Wed, 8 Apr 2026 10:52:40 +0200 Subject: [PATCH] docs: create roadmap (5 phases) --- .planning/REQUIREMENTS.md | 50 +++++++------- .planning/ROADMAP.md | 113 ++++++++++++++++++++++++++++++++ .planning/STATE.md | 63 ++++++++++++++++++ CLAUDE.md | 134 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 335 insertions(+), 25 deletions(-) create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/STATE.md create mode 100644 CLAUDE.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 6df1e47..fe6ab9c 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -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* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..9fe3b59 --- /dev/null +++ b/.planning/ROADMAP.md @@ -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 | - | diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..cb9a45d --- /dev/null +++ b/.planning/STATE.md @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2f240ae --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,134 @@ + +## 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 +- 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/ + + + +## 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. +