wulf-pulse/.planning/PROJECT.md

Pulse Mobile Shell Redesign

What This Is

A ground-up redesign of Pulse's /mobile/* shell — the manager-on-the-go view of the existing Pulse PSA dashboard. It replaces the current mobile layout, swaps the standalone /mobile/nav page for a Sheet drawer, restyles Dashboard / Tickets / Finance, and adds two new mobile surfaces (Analyzer feed, Engagement). Built on the existing Pulse codebase — same routes, same data, phone-first layouts.

Core Value

A manager can open Pulse on their phone and, in under 30 seconds, see the state of the business and triage tickets — without ever needing to switch to desktop for read-only awareness.

Requirements

Validated

• ✓ /mobile route shell with sticky header and bottom nav — existing
• ✓ /mobile/dashboard, /mobile/tickets, /mobile/tickets/[id], /mobile/finance routes — existing
• ✓ Standalone /mobile/nav page (to be replaced by drawer) — existing
• ✓ Authentication, sync workers, analyzer pipeline, Engagement data sources — existing in desktop app and reused here
• ✓ PWA scaffolding (manifest, viewport-fit=cover, pt-safe/pb-safe utilities) — Validated in Phase 1: PWA Scaffolding (PWA-01..04)
• ✓ New /mobile/layout.tsx shell — sticky header (WulfMark + Bell placeholder
  • avatar), 5-cell bottom nav (Dashboard/Tickets/Finance/Analyzer + More), shared MoreDrawer Sheet — Validated in Phase 2: Mobile Shell + More Drawer (SHELL-01..06, NAV-01..03)
• ✓ More drawer (right Sheet) replaces /mobile/nav — Mobile sections, Full site links (with ExternalLink hint), Account + Sign out — Validated in Phase 2: Mobile Shell + More Drawer (DRAWER-01..06)
• ✓ Dashboard restyle — 2×2 KPI grid, Needs Attention strip (horizontal scroll), worker/backup status row, no charts. Backed by single /api/mobile/dashboard endpoint returning kpis/needsAttention/workers. Validated in Phase 3: Dashboard Restyle (DASH-01..04)

Active

• Tickets restyle — collapsible filter strip (URL-synced), priority-bar rows, cursor-based infinite scroll (~25/page), keep detail page
• Finance restyle — adopt new Card + typography scale, swap wide tables for stacked lists on mobile
• Analyzer feed (NEW) — /mobile/analyzer read-only stream of recent AI analyses with mobile summary view; new /api/mobile/analyzer/feed
• Engagement mobile (NEW) — /mobile/engagement overview (period chips, stacked summary cards, sortable per-employee list, sparkline) plus /mobile/engagement/[userId] profile page replacing the desktop modal

Out of Scope

• Service worker / offline cache / push notifications — deferred until a clear offline use-case lands
• Tablet breakpoint (md:max-w-2xl) — noted as follow-up, keep max-w-lg
• Real notification list behind the Bell icon — placeholder only this iteration
• Mobile editing on Engagement (user detail) or Analyzer (re-run, prompt edits) — read-only on mobile by design
• Charts / recharts on the mobile Dashboard — not earning their weight on small widths
• Restyling or replacing the desktop pages reachable from the More drawer — desktop pages stay as they are

Context

• Brownfield project. Pulse is a Next.js 16 + React 19 PSA dashboard for Wulf Consulting. Existing codebase fully mapped at .planning/codebase/*.md. See CLAUDE.md, ARCHITECTURE.md, DESIGN.md in repo root.
• Audience. Wulf Consulting managers using Pulse on iOS/Android during the workday — the shell is for status checks and triage, not full editing.
• Mobile is not a replacement for desktop. Pages where mobile editing isn't justified link out via the More drawer with an ExternalLink hint.
• Source of truth for this work. docs/superpowers/specs/2026-05-03-mobile-shell-design.md — 8-section spec with explicit build order. Phases should follow it.
• Existing mobile shell is small. Current app/mobile/layout.tsx has 3 bottom-nav tabs and a /mobile/nav page. This redesign rebuilds it in place — no /mobile-v2, no parallel routes.
• Engagement and Analyzer pages on desktop are large (~1300 + ~650 lines for engagement; analyzer pipeline already has a desktop UI). Mobile surfaces reuse the data sources but build phone-first layouts from scratch.

Constraints

• Tech stack: Next.js 16 App Router, React 19, Tailwind 4, shadcn/ui — match existing Pulse conventions (no new state libraries, no SWR/react-query, no ORM, no Zod in API routes unless required)
• Routes: Keep all existing /mobile/* paths. Replace files in place. No new top-level routes outside /mobile/.
• Build order: Each spec step ships independently — no big-bang merge. Phase boundaries should let each step land on master cleanly.
• No service worker / no offline: don't introduce next-pwa or a custom SW in this iteration.
• Auth: existing Better Auth + middleware handles /mobile/*. No new auth surface.
• Data sources: reuse existing endpoints where possible; add /api/mobile/* only when an existing list endpoint doesn't return the needed shape (e.g., analyzer feed).

Key Decisions

Decision	Rationale	Outcome
Rebuild /mobile in place (no /mobile-v2)	Spec §2 — keep canonical URLs, avoid parallel maintenance burden	— Pending
Bottom nav = 4 tabs + More (5 cells), Engagement in More	Spec §3.1, §6.5 — managers don't check Engagement as often as the four primary surfaces	— Pending
Ship each spec step as its own phase	Spec §8 — independent ship reduces merge risk and keeps reviews focused	— Pending
Bell icon is a placeholder only	Spec §5.1 — real notification list deferred; keep keyboard-accessible button so future phase can wire it	— Pending
No service worker in this iteration	Spec §4 — defer until a clear offline use-case lands	— Pending
Engagement mobile is a real refactor, not a thin adaptation	Spec §6.5 — desktop's wide tables and modals don't translate; build phone-first from same data sources	— Pending
Mobile user-detail is a page, not a modal	Spec §6.5 — back gesture needs real navigation history	— Pending

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition (via /gsd-transition):

1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

After each milestone (via /gsd-complete-milestone):

1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---

Last updated: 2026-05-03 — Phase 3 complete (Dashboard Restyle)