4.2 KiB
4.2 KiB
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 | 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: 22
- Unmapped: 0
Requirements defined: 2026-04-08 Last updated: 2026-04-08 after roadmap creation