# Requirements Archive: v1.0 MVP

**Archived:** 2026-04-08
**Status:** SHIPPED

For current requirements, see `.planning/REQUIREMENTS.md`.

---

# 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

- [x] **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
- [x] **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
- [x] **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

- [x] **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

- [x] **TEST-01**: PHPUnit tests for the data aggregation service (timezone-correct day grouping)
- [x] **TEST-02**: PHPUnit tests for the API endpoint (response format, filtering)
- [ ] **TEST-03**: JavaScript tests for d3 heatmap rendering (grid structure, color mapping)
- [x] **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*