5.3 KiB
Phase 7: Engagement Overview (NEW) - Discussion Log
Audit trail only. Do not use as input to planning, research, or execution agents. Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
Date: 2026-05-04 Phase: 07-engagement-overview-new Mode: auto (recommended defaults selected for every gray area) Areas discussed: Period selector mapping, Summary metric semantics, Per- employee list data source, Sparkline data, List pagination, Search, Sort options, Sparkline implementation, Loading/error/empty states, Typography & spacing
Period selector mapping
| Option | Description | Selected |
|---|---|---|
| Spec-literal: today / 7d / 30d | Matches spec text but data layer has no D1 aggregate | |
| Data-aligned: 7d / 30d / 90d | Maps to existing D7/D30/D90 period_type values | ✓ |
| Custom (date range picker) | Heavier UX, not in ENG-02 |
Auto-selection: 7d / 30d / 90d — preserves data-layer fidelity. "Today" deferred (would need new D1 sync).
Summary metric semantics
| Option | Description | Selected |
|---|---|---|
| Reuse existing /api/engagement/summary (averages) and compute totals client-side | Simple, but math on client and avg×count is approximate | |
| New /api/mobile/engagement/summary returning the 4 ENG-03 metrics directly | Cleanest; mirrors Phase 6 pattern of one mobile endpoint | ✓ |
| Extend existing endpoint with totals fields | Couples desktop + mobile semantics |
Auto-selection: New mobile endpoint — clean separation, accurate totals.
Per-employee list data source
| Option | Description | Selected |
|---|---|---|
| Reuse existing /api/engagement/users directly | Already returns the right shape with sort/page params | ✓ |
| Wrap in /api/mobile/engagement/users | Adds a thin mobile-only endpoint with no value-add | |
| Inline SQL in the mobile page | Anti-pattern; violates server/client separation |
Auto-selection: Reuse existing — already shapes the data correctly.
Sparkline data source
| Option | Description | Selected |
|---|---|---|
| New /api/mobile/engagement/trend (daily totals) | Required — no existing endpoint returns time-series | ✓ |
| Reuse engagement_snapshots client-side | snapshots aren't daily; can't compute trend client-side | |
| Skip the sparkline | Violates ENG-05 |
Auto-selection: New trend endpoint — required for ENG-05.
List pagination
| Option | Description | Selected |
|---|---|---|
| Page-based + IntersectionObserver | Existing endpoint is page-based; matches Phase 4/6 UX | ✓ |
| Cursor-based (rewrite endpoint) | Requires modifying desktop endpoint (out of scope) | |
| No pagination (load all) | Page size 50; fine for ≤50 staff but breaks at scale |
Auto-selection: Page-based + IntersectionObserver — same UX as Phase 4/6.
Search behavior
| Option | Description | Selected |
|---|---|---|
| Client-side filter on loaded users | Instant feedback, no server param needed at ≤50 staff | ✓ |
| Server-side search param | Requires modifying desktop endpoint | |
| Skip search | Violates ENG-04 |
Auto-selection: Client-side filter — fine at current scale.
Sort axes
| Option | Description | Selected |
|---|---|---|
| 3 chips: Hours / Name / Utilization | Matches ENG-04 exactly | ✓ |
| Dropdown with 5+ axes | Too many for phone | |
| No sort control | Violates ENG-04 |
Auto-selection: 3 chips matching ENG-04.
Sparkline implementation
| Option | Description | Selected |
|---|---|---|
| Custom inline SVG path | No chart library, 30 lines, fully controlled | ✓ |
| recharts LineChart | Already a dep, but DASH-04 forbids recharts on mobile | |
| Visx/d3 | New dep, overkill for one sparkline |
Auto-selection: Custom SVG — DASH-04 precedent.
Loading / empty / error states
| Option | Description | Selected |
|---|---|---|
| Skeleton + toast.error + Retry + EmptyState card | Phase 4/5/6 precedent | ✓ |
| Single spinner only | Less polished | |
| Server-rendered placeholder | Doesn't match the client-fetch pattern |
Auto-selection: Mirror established mobile patterns.
Typography & spacing
| Option | Description | Selected |
|---|---|---|
| Mirror Phase 4 UI-SPEC: 2 weights / 3 sizes + base/2xl extras | Consistency across mobile shell | ✓ |
| New scale just for Engagement | Avoid divergence cost |
Auto-selection: Mirror Phase 4/5/6.
Auto-Resolved (--auto mode)
All ten gray areas were auto-resolved with the recommended option per
the workflow's --auto mode. No interactive questioning occurred.
Deferred Ideas
(See 07-CONTEXT.md <deferred> section for the canonical list.)
- "Today" period chip (requires D1 sync)
- Server-side search at scale
- Multi-series trend chart (out of spec)
- Per-row drill-down to user profile (Phase 8 owns this)
- Sort by zoom calls / meetings / emails
- "Engagement sync now" button on mobile (read-only by design)
- IDOR fix on existing /api/engagement/* endpoints (desktop, out of scope)
- List virtualization (deferred until scale demands)