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

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"

<code_context>

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

</code_context>

## Deferred Ideas

None — discussion stayed within phase scope

Phase: 08-mobile-pwa Context gathered: 2026-03-26

4.3 KiB Raw Blame History