From f005f4a3b4e23130306350512f73e2b91fec420e Mon Sep 17 00:00:00 2001 From: Adolfo Delorenzo Date: Wed, 25 Mar 2026 20:08:35 -0600 Subject: [PATCH] docs(08): capture phase context --- .planning/phases/08-mobile-pwa/08-CONTEXT.md | 96 ++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 .planning/phases/08-mobile-pwa/08-CONTEXT.md diff --git a/.planning/phases/08-mobile-pwa/08-CONTEXT.md b/.planning/phases/08-mobile-pwa/08-CONTEXT.md new file mode 100644 index 0000000..f24d55d --- /dev/null +++ b/.planning/phases/08-mobile-pwa/08-CONTEXT.md @@ -0,0 +1,96 @@ +# Phase 8: Mobile + PWA - Context + +**Gathered:** 2026-03-26 +**Status:** Ready for planning + + +## Phase Boundary + +Responsive mobile/tablet layout for all portal pages and installable Progressive Web App. Bottom tab bar navigation on mobile, full-screen chat flow, offline-capable app shell with cached content, push notifications for new messages, and "K" branded install experience. + + + + +## Implementation Decisions + +### Mobile Navigation +- Dual navigation: bottom tab bar (5 items) for main nav + hamburger/"More" menu for secondary items +- Bottom tab bar items: Dashboard, Employees, Chat, Usage, More +- "More" menu contains: Billing, API Keys, Users, Platform, Settings, Sign Out +- "More" menu style: Claude's discretion (bottom sheet recommended) +- Breakpoint: 768px (md) — tablets and below get mobile layout, desktop keeps the sidebar +- RBAC still applies — operators don't see admin-only items in either nav or "More" + +### Chat on Mobile +- Conversation list → full-screen chat pattern (like WhatsApp/iMessage) +- Tap a conversation to enter full-screen chat, back arrow to return to list +- Top bar in full-screen chat: back arrow + agent name + agent avatar +- Message input: fixed at bottom, pushes content up when virtual keyboard opens +- Streaming responses work the same as desktop — tokens appear word-by-word + +### PWA Install & Offline +- App icon: bold "K" monogram on the gradient mesh background (matching login page aesthetic) +- Splash screen: same gradient + K branding +- Install prompt: smart banner on second visit — not intrusive, proven conversion pattern +- Offline capability: app shell cached + recently viewed pages. Chat history viewable offline. +- Offline banner: shows "You're offline" indicator when disconnected +- Message queue: new messages queue locally until reconnection, then send automatically +- Push notifications: MUST HAVE — users get notified on their phone when an AI Employee responds + +### Claude's Discretion +- "More" menu exact style (bottom sheet vs full-screen overlay vs side drawer) +- Service worker caching strategy (workbox, serwist, or manual) +- Push notification provider (Web Push API, Firebase Cloud Messaging, or OneSignal) +- Touch gesture handling (swipe-to-go-back, pull-to-refresh, etc.) +- Tablet-specific layout adjustments (if any beyond the breakpoint) +- PWA manifest theme color and background color +- How to handle the language switcher on mobile + + + + +## Specific Ideas + +- The bottom tab bar should feel like a native mobile app — solid icons, subtle active indicator, no text labels (or very small ones) +- Chat full-screen view should be indistinguishable from WhatsApp or iMessage — that's the benchmark +- The "K" monogram on the gradient should be striking — this is the app icon people see on their home screen +- Push notifications for AI Employee responses make the platform feel alive — "Mara just replied to your question" + + + + +## Existing Code Insights + +### Reusable Assets +- `packages/portal/components/nav.tsx` — Desktop sidebar nav (needs mobile variant added) +- `packages/portal/app/(dashboard)/layout.tsx` — Dashboard layout (needs responsive wrapper) +- `packages/portal/app/(dashboard)/chat/page.tsx` — Chat page (needs mobile full-screen mode) +- `packages/portal/components/chat-sidebar.tsx` — Conversation list (reuse as mobile list view) +- `packages/portal/components/chat-window.tsx` — Active conversation (becomes full-screen on mobile) +- `packages/portal/app/globals.css` — Design tokens + gradient-mesh animation (reuse for splash) + +### Established Patterns +- Tailwind v4 responsive: `md:` and `lg:` prefixes already used throughout +- shadcn/ui components are responsive primitives +- Next.js 16 App Router with standalone output (PWA-compatible) +- Auth.js v5 JWT (works with service worker, no session cookies needed) + +### Integration Points +- `app/layout.tsx` — PWA manifest link, service worker registration +- `public/` directory — manifest.json, icons, service worker +- WebSocket (chat) — needs to handle reconnection after offline period +- `docker-compose.yml` — portal container serves the PWA assets + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 08-mobile-pwa* +*Context gathered: 2026-03-26*