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

4.2 KiB
Raw Blame History

Requirements: Kimai Heatmap Plugin

Defined: 2026-04-08 Core Value: At a glance, see where your time went — a visual map of tracking activity that makes patterns obvious

v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

Dev Environment

  • DEV-01: Nix flake/devshell provides a running local Kimai instance
  • DEV-02: Local Kimai has a seeded database with realistic time entry data
  • DEV-03: Plugin is loadable in the local Kimai instance for manual testing

Plugin Scaffold

  • PLUG-01: Plugin is a valid Symfony bundle discoverable by Kimai
  • PLUG-02: Plugin registers a dashboard widget visible on the Kimai dashboard
  • PLUG-03: Plugin ships a backend API endpoint returning aggregated daily time data

Heatmap Core

  • HEAT-01: Widget renders a d3.js calendar heatmap (weeks x days grid)
  • HEAT-02: Cell color intensity reflects hours tracked per day (darker = more)
  • HEAT-03: Hovering a cell shows tooltip with date, hours, and entry count
  • HEAT-04: Day-of-week labels (Mon/Wed/Fri) on Y-axis
  • HEAT-05: Month labels along the top showing month boundaries
  • HEAT-06: Empty days render with a distinct "no data" color
  • HEAT-07: Clicking a day cell navigates to Kimai timesheet view filtered to that date
  • HEAT-08: Color scheme uses Kimai's theme CSS variables

Interactivity

  • INTR-01: Dropdown filter to view heatmap for a specific project or activity

Polish

  • POLI-01: Streak indicator showing current consecutive days with tracked time
  • POLI-02: Summary stats row (total hours, average hours/day, busiest day)
  • POLI-03: Visual distinction for weekend days (subtle border or opacity)

Testing

  • TEST-01: PHPUnit tests for the data aggregation service (timezone-correct day grouping)
  • TEST-02: PHPUnit tests for the API endpoint (response format, filtering)
  • TEST-03: JavaScript tests for d3 heatmap rendering (grid structure, color mapping)
  • TEST-04: JavaScript tests for tooltip and click interaction behavior

v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

Interactivity

  • INTR-02: Toggle between hours-per-day and entry-count display modes
  • INTR-03: Configurable time range selector (3 months, 6 months, year, custom)

Polish

  • POLI-04: Responsive widget sizing adapting to dashboard column width

Out of Scope

Feature Reason
Billable vs non-billable split Personal time tracking, not client billing
Real-time / live updates Page reload sufficient for daily-granularity data
Export/share heatmap as image No audience for personal use
Hour-of-day matrix Different visualization, scope creep
Drill-down charts in widget Click-through to Kimai views instead
Multi-user comparison Personal tracking tool
Goal setting / targets Streak indicator covers motivation simply
Animated transitions Complexity for near-zero utility
Mobile-specific layout Desktop Kimai dashboard only
Custom color theme picker Kimai theme integration is sufficient

Traceability

Which phases cover which requirements. Updated during roadmap creation.

Requirement Phase Status
DEV-01 Phase 1 Complete
DEV-02 Phase 1 Pending
DEV-03 Phase 1 Pending
PLUG-01 Phase 2 Pending
PLUG-02 Phase 2 Pending
PLUG-03 Phase 2 Complete
TEST-01 Phase 2 Complete
TEST-02 Phase 2 Complete
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 Complete
INTR-01 Phase 4 Complete
TEST-04 Phase 4 Complete
POLI-01 Phase 5 Pending
POLI-02 Phase 5 Pending
POLI-03 Phase 5 Pending

Coverage:

  • v1 requirements: 22 total
  • Mapped to phases: 22
  • Unmapped: 0

Requirements defined: 2026-04-08 Last updated: 2026-04-08 after roadmap creation