docs: initialize mobile shell redesign project
This commit is contained in:
parent
cf3b740d34
commit
fe1401366f
1 changed files with 134 additions and 0 deletions
134
.planning/PROJECT.md
Normal file
134
.planning/PROJECT.md
Normal file
|
|
@ -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
|
||||
|
||||
<!-- Capabilities that already exist in the Pulse mobile shell. -->
|
||||
|
||||
- ✓ `/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
|
||||
|
||||
<!-- Hypotheses for this milestone — see docs/superpowers/specs/2026-05-03-mobile-shell-design.md -->
|
||||
|
||||
- [ ] 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
|
||||
|
||||
<!-- From spec §7. Explicit boundaries to prevent scope creep. -->
|
||||
|
||||
- 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
|
||||
|
||||
<!-- Decisions that constrain future work. -->
|
||||
|
||||
| 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*
|
||||
Loading…
Add table
Add a link
Reference in a new issue