From fe1401366f123b9d55707c77899396c53283aab2 Mon Sep 17 00:00:00 2001 From: lorentz Date: Sun, 3 May 2026 12:38:56 -0400 Subject: [PATCH] docs: initialize mobile shell redesign project --- .planning/PROJECT.md | 134 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 .planning/PROJECT.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md new file mode 100644 index 0000000..ed9cb75 --- /dev/null +++ b/.planning/PROJECT.md @@ -0,0 +1,134 @@ +# 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 + +### Active + + + +- [ ] PWA scaffolding (manifest, viewport, safe-area insets) — no service worker +- [ ] New `/mobile/layout.tsx` shell — header (logo + Bell placeholder + avatar), + content area, bottom nav with 4 tabs + More +- [ ] More drawer (Sheet) replaces `/mobile/nav` — Mobile sections, Full site + links (with `ExternalLink` hint), Account + Sign out +- [ ] Dashboard restyle — 2×2 KPI grid, Needs Attention strip (horizontal + scroll), worker/backup status row, no charts +- [ ] 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 after initialization*