# Phase 8: Mobile + PWA - Context

**Gathered:** 2026-03-26
**Status:** Ready for planning

<domain>
## 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.

</domain>

<decisions>
## 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

</decisions>

<specifics>
## 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"

</specifics>

<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>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

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