# MemberJunction Mobile App — React Native Architecture & Phase 1 Plan **Status:** Phase 1 feature-complete (code) — pending on-device verification **Date:** 2026-05-18 (proposal) · 2026-05-19 (kickoff) · 2026-05-20 (Phase 1 code complete) **Branch:** `an-mobile-app-dev` **Supersedes:** The earlier PWA-based proposal that lived at `packages/Mobile/ARCHITECTURE.md` (removed via PR #1734) > **Implementation status (2026-05-20):** Phase 1 is **code-complete** in `packages/MobileApp/`. The app boots on the iOS Simulator and renders the conversation list. Remaining before sign-off is **on-device verification of the full data path**, which is gated on adding the `mjmobile://auth` callback URL to the Auth0 dev tenant. > > **What's built (all wired to MJAPI via the MJ object model — no mocks):** > - **Auth** — Auth0 OAuth + PKCE (primary, via `expo-auth-session`), MSAL (Azure AD, ready pending its redirect-URI registration), dev-JWT paste (fallback). Login screen gates the app; silent token refresh; sign-out. Tokens in `expo-secure-store`. > - **Chat (read)** — conversation list grouped by recency with multi-agent avatar stacks; chat thread with per-message agent attribution, markdown, `@mention` highlighting, pull-to-refresh. > - **Chat (write)** — composer creates a user `Conversation Detail` and triggers an agent via `GraphQLDataProvider.AI.RunAIAgentFromConversationDetail` with live progress; new-conversation flow creates the conversation + first message. Server owns the AI response row. > - **Artifacts** — per-conversation artifact list + single-artifact detail rendering by classified kind (json-table / json / markdown / code / text), reading `Conversation Artifact Version` content. > - **Data Explorer** — entity picker → records (RunView) → read-only record detail (`GetEntityObject`/`InnerLoad`); query picker → results (`RunQuery`); dashboard picker (best-effort viewer). "Ask Skip about this" bridge on every surface. > - **Profile** — identity from `Metadata.CurrentUser`; preference toggles present (Phase 2 wires them). > > **Notable build/runtime fixes captured along the way:** monorepo hoisting of `expo-router` (babel-preset-expo gating), workspace-wide `react@19.1.0` override (RN renderer mismatch), MMKV `ILocalStorageProvider`, boot timeout + escape hatch. > > **Deferred to Phase 2** (designed-for, not yet wired): voice STT/TTS pipeline (the voice-mode screen is a visual scaffold), push notifications, biometric lock, record editing, interactive-component artifact rendering via `@memberjunction/react-runtime`, the shared `@memberjunction/markdown-core` extraction (a lightweight inline renderer stands in for now), and real dashboard part rendering. > > Original kickoff note follows for history. Open `index.html` in this folder for the visual handoff; open questions are in Part 11. --- ## Why This Document Exists We previously explored a PWA-only path for MJ mobile. After working through the trade-offs (see "Decision Trail" at the end of this doc), we've landed on **React Native** as the right approach. This document captures: 1. Why RN over PWA, Capacitor, and Flutter 2. The architectural model — **one TypeScript brain, three UIs** 3. The Phase 1 scope (deliberately small: Data Explorer subset + Chat) 4. The one real refactor required in shared code (cache abstraction) 5. The pluggability story (`@RegisterClass`, ClassFactory, BaseSingleton — all preserved) The PWA doc had the right instinct about reuse but oversold the user experience. RN gives us **native-quality UX** while still letting us share **~70% of the stack** — specifically, the entire non-visual TypeScript layer that contains the real intellectual property of MemberJunction. --- ## Part 1: Decision Summary — Why React Native ### The four options, scored against what matters for MJ | Option | TS reuse | UI reuse | Native feel | Distribution | Team fit | |---|---|---|---|---|---| | **PWA (Angular as-is)** | ~95% | ~95% | **6/10** (WebView feel; iOS limits) | Browser only | Day-one | | **Capacitor (Angular wrapped)** | ~95% | ~95% | **7/10** (WebView in native shell) | App Store ✅ | Day-one | | **React Native** | **~70%** (cache refactor) | 0% (fresh mobile UI) | **9.5/10** (real native views) | App Store ✅ | Day-one (TS) | | **Flutter** | **0%** (Dart ≠ TS) | 0% | 9.5/10 (Skia-rendered) | App Store ✅ | Weeks (new language) | ### Why RN wins for MJ **Why not PWA / Capacitor:** Both render in a WebView. The "feel" gap vs. native is real and persistent — list scroll, keyboard handling, animations, gesture handling, cold start time all suffer. iOS adds specific pain: 7-day Safari eviction of unused PWAs, ~50 MB storage cap, no background sync, push only after the "Add to Home Screen" funnel completes. Enterprise B2B users compare mobile apps to Salesforce Mobile and Workday — both native. The "100% codebase reuse" sales pitch obscures that the *UI layer* would still be largely rewritten for mobile breakpoints regardless of which option we pick. **Why not Flutter:** TS reuse is **zero**. Flutter is Dart, with no realistic bridge to our TS core. The options are (a) embed a JS engine and run TS via `flutter_js` (slow, ugly, debugging-hostile), (b) regenerate the entire MJ entity layer + AI packages + agent framework in Dart and maintain two parallel non-visual stacks forever, or (c) make the mobile app a thin RPC client over MJAPI with no local intelligence. None of those preserve MemberJunction's architectural advantages. **Why RN works:** RN runs JavaScript (via Hermes). Our `@memberjunction/core`, `core-entities`, `ai`, `ai-prompts`, `ai-agents`, `graphql-dataprovider` (with one refactor — see Part 4), and `global` packages run **unchanged** in that runtime. The pluggability machinery (`@RegisterClass`, `MJGlobal.ClassFactory`, `BaseSingleton`, decorators, inheritance chains) is pure TypeScript and survives intact. Function components and hooks call into our OOP classes idiomatically — this is the dominant pattern in modern React, not a workaround. ### What we explicitly accept - **The mobile UI is a fresh codebase.** No reuse of Angular components, templates, or styles. That's fine: we're building a deliberately smaller mobile product, not porting MJExplorer. - **AI writes ~99% of the UI code.** With Claude/AI assistance, the cost of authoring RN components is low. The architectural overhead (two stacks to keep in sync) is the part AI doesn't eliminate — which is why Flutter's "AI can write Dart fast" argument doesn't save it. - **App Store review is a fact of life.** We trade instant web deploys for native distribution. For enterprise mobile, this is a feature, not a bug — IT departments prefer App Store / MDM distribution. --- ## Part 2: Architectural Model — One TS Brain, Three UIs ``` ┌────────────────────────────────────────────────────────────────────┐ │ UI LAYER │ │ │ │ ┌────────────────────┐ ┌────────────────────┐ ┌──────────────┐ │ │ │ MJExplorer │ │ (Future) Mobile │ │ Mobile │ │ │ │ (Angular, desktop │ │ responsive web │ │ (React │ │ │ │ + tablet) │ │ if useful │ │ Native) │ │ │ │ │ │ │ │ │ │ │ │ ✓ Today │ │ ✓ Optional later │ │ ✓ New │ │ │ └────────────────────┘ └────────────────────┘ └──────────────┘ │ │ │ │ │ │ └───────────┼───────────────────────┼───────────────────────┼────────┘ │ │ │ └───────────────┬───────┴───────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────────────┐ │ SHARED TYPESCRIPT BRAIN (unchanged) │ │ │ │ @memberjunction/global — utilities, ClassFactory │ │ @memberjunction/core — BaseEntity, Metadata, RunView │ │ @memberjunction/core-entities — generated entity classes │ │ @memberjunction/ai — LLM abstraction │ │ @memberjunction/ai-prompts — prompt runner │ │ @memberjunction/ai-agents — BaseAgent framework │ │ @memberjunction/graphql- — Apollo client + pluggable cache │ │ dataprovider (refactored — see Part 4) │ │ @memberjunction/credentials — auth management │ └────────────────────────────────────────────────────────────────────┘ │ ▼ MJAPI Server (GraphQL + WebSockets, unchanged) ``` ### What this means concretely - A `Metadata().GetEntityObject('Contacts')` call in an RN component runs the **exact same code path** as in MJExplorer. - `@RegisterClass` registrations resolve through the same `ClassFactory` instance — no special "mobile registry." - `BaseAgent` subclasses execute the same way. Skip agent runs from a phone work identically to runs from a desktop browser. - New entities generated by CodeGen automatically flow to the mobile app via the shared `core-entities` package — no parallel generation, no porting. - The only place mobile-specific work happens is the **RN UI layer** (screens, navigation, gestures, native modules). This is the architectural payoff that makes RN worth the fresh-UI cost. --- ## Part 3: Phase 1 Scope — Deliberately Minimal The earlier proposal tried to mirror Explorer on mobile. That's the wrong move. Mobile is **not a port** — it's a focused product for the workflows that actually make sense on a phone. ### Phase 1 features (full list) #### 1. Chat with Agents The conversational AI surface. This is the single highest-value mobile workflow. - Open a conversation, send messages, receive agent responses - Talk to existing agents (Skip, custom agents) via the existing agent framework - View artifacts that agents produce inline (text, structured data, simple visualizations) - Stream responses (server-sent events / WebSocket — same path Explorer uses) - Voice input (defer to Phase 2 unless trivial — see "Phase 1 non-goals") **Why this fits mobile:** Chat is the canonical mobile UX. Users already expect to text things on their phone. Voice and push extend it naturally in later phases. **What we reuse:** All of `@memberjunction/ai-agents`, `ai-prompts`, the conversation entities (`MJ: Conversation`, `MJ: Conversation Detail`, artifacts entities), and the GraphQL conversation subscriptions. Zero new server work. #### 2. Data Explorer (subset) Three top-nav surfaces from Explorer, mobile-adapted: **a. Entity Browser** - List of entities the user has access to (filtered by permissions) - Tap an entity → list of records (card-based, swipe actions) - Tap a record → mobile record view (single-column, key fields prominent) - Read-first. Edit is a Phase 2 question. - **No grids.** Cards only on mobile. **b. Queries** - List of saved queries the user can run - Tap a query → parameter form (if any) → results - Results render as cards or simple tabular view depending on shape - Save / share results out-of-scope for Phase 1 **c. Dashboards** - List of dashboards - Tap a dashboard → renders the dashboard component - **Honest caveat:** most existing dashboards are built for desktop and **won't render well on mobile by default.** That's a known limitation we accept for Phase 1. We don't fix individual dashboards in this phase — we just provide the surface, and dashboard authors will eventually add mobile-aware layouts (a separate initiative). ### Phase 1 non-goals (explicit) To prevent scope creep, these are **not** in Phase 1: - ❌ Voice input/output (Phase 2 — Web Speech API doesn't exist in RN; Phase 2 reuses core's realtime stack via `@memberjunction/ai-realtime-client` — see the revised Voice mode subsection) - ❌ Push notifications (Phase 2 — APNs/FCM wiring is non-trivial, server-side endpoint required) - ❌ Offline mutations / queue (Phase 3 — read-only caching is fine for Phase 1) - ❌ Biometric login (Phase 2 — `expo-local-authentication`, simple but not first-week work) - ❌ Record editing / creation (Phase 2 — keeps Phase 1 read-only, eliminates a huge surface of bugs) - ❌ Dashboard authoring or mobile-specific dashboard layouts (separate initiative) - ❌ Photo capture, file upload, attachments (Phase 3) - ❌ Settings/admin/configuration UIs (desktop-only) - ❌ Anything from the rest of Explorer's nav (reports, AI Admin, etc.) ### Phase 1 navigation shape ``` ┌────────── App root (after auth) ──────────┐ │ │ │ Chat thread (default screen) │ │ ↑ │ │ │ tap hamburger / swipe edge │ │ ↓ │ │ Conversation list (drawer) │ │ │ │ │ ├─ Conversation rows → chat thread │ │ ├─ Data Explorer link → explorer-home │ │ └─ Profile link → profile │ │ │ └────────────────────────────────────────────┘ ``` **No bottom tab bar.** Chat is the persistent default; the conversation-list drawer is the global nav root and contains links down to the Data Explorer and Profile surfaces. This pattern (drawer-only, following ChatGPT/Claude iOS conventions) keeps the chat thread visually uncluttered, which is essential because chat is the primary product. Data Explorer and Profile, being secondary, are reached via the drawer rather than competing for permanent screen real estate. This choice is reflected throughout the mockups in Part 4. --- ## Part 4: Phase 1 UX Specification — Screen by Screen This section is the implementation handoff. Each screen has a full-resolution mockup at `html/.html`, opened side-by-side in `html/index.html` (or the top-level `index.html` in this folder). The visuals are not suggestions — they are the design contract. Deviations should be discussed and reflected back into the mockups so this document stays the single source of truth. ### 4.1 Design system (cross-cutting) | Token | Value | Use | |---|---|---| | Background | `#fafaf7` (warm off-white) | Page surface | | Surface | `#ffffff` | Cards, sheets, composer, dock | | Surface-2 | `#f6f5ef` | Inset panels, hover/pressed states | | Ink | `#0d0d10` | Primary text | | Ink-2 | `#4a4a52` | Secondary text | | Ink-3 | `#8a8a93` | Tertiary text, labels | | Line | `rgba(13,13,16,0.06)` | Hairline borders | | Brand | `#264FAF` (MJ blue) | Mic button, primary brand, Skip identity | | Positive | `#1a8a5f` | Wins, healthy state | | Warn | `#b87a1f` | Caution, negotiation stage | | Danger | `#c84a39` | High risk | **Agent accent colors** (each agent gets a stable identity color): - Skip → `#264FAF` (MJ blue) - Research → `#7c5cd6` (purple) - Account Analyst → `#d97757` (terracotta) - Forecaster → `#1a8a5f` (green) - Email Drafter → `#b87a1f` (amber) - Fallback → `#4a4f5a` (slate) **Type:** SF Pro (system). Body 15–16pt, agent attribution 11–12pt with PascalCase semantic spacing. **Corner radii:** 14px (cards), 18–22px (sheets), 24px (composer), 50% (avatars, mic). **Phone frame:** mockups assume iPhone 15-class viewport (393 × 852 logical pixels, Dynamic Island, home indicator). ### 4.2 Screens #### A. Authentication | File | Purpose | |---|---| | [`html/login.html`](html/login.html) | Single-screen sign-in with email + SSO options (passkey, Google, Apple). | - **Data:** Existing MJ OAuth flow via `expo-auth-session`; passkey via WebAuthn through `expo-secure-store` for credential storage. - **Interaction:** Email + Continue (magic link or password depending on tenant). SSO buttons launch in-app browser auth, return token to `expo-secure-store`. - **Notes:** Logo block uses an "M" mark in MJ-blue gradient. Bottom legal note links to Terms/Privacy as in-app webviews. #### B. Conversation surface (primary) | File | Purpose | |---|---| | [`html/conversation-list.html`](html/conversation-list.html) | Drawer / global nav. Lists conversations grouped by Pinned / Today / Yesterday / Earlier. Footer rows link to Data Explorer and Profile. | | [`html/new-conversation.html`](html/new-conversation.html) | Start screen when user taps "+ New conversation." Composer + suggested prompts + agent-pick rail. | | [`html/chat-thread.html`](html/chat-thread.html) | The hero screen. Active conversation with multi-agent thread, step indicators, inline artifact card, action chips, collapsed artifact dock handle, and composer. | | [`html/voice-mode.html`](html/voice-mode.html) | Fullscreen voice capture (Phase 2 design, designed-for in Phase 1). Animated orb, waveform, live transcript, controls. | | [`html/artifacts-dock-open.html`](html/artifacts-dock-open.html) | The artifact dock pulled up. Shows all artifacts in the conversation, agent-filterable. | | [`html/artifact-detail.html`](html/artifact-detail.html) | Single artifact zoomed to full screen. Tabs for Data / Chart / JSON, version selector, summary stats, sticky "Back to conversation" + "Ask Skip" bar. | **Conversation list (drawer):** - **Data sources:** `MJ: Conversation` for the list, `MJ: Conversation Detail` for the most-recent-message snippet, `MJ: Conversation Artifacts` count for badge. Sort by `__mj_UpdatedAt DESC`. Group rows client-side by relative recency. - **Multi-agent visual:** Avatar stack on the left of each row. Distinct agents are derived from the `AIAgentID` referenced in the conversation's `Conversation Detail` rows (LEFT JOIN, distinct). - **Interactions:** Tap row → enter chat thread for that conversation. Tap "New conversation" → `new-conversation.html`. Tap "Data Explorer" footer → `explorer-home.html`. Tap profile footer → `profile.html`. Long-press a row → action sheet (pin, rename, archive, delete) — Phase 1 minimum is pin + delete. - **Live state:** Green dot on rows where an agent task is still in flight (`Status='In-Progress'` in the latest message). **New conversation:** - **Data sources:** Suggested prompts come from a static config or a `MJ: Conversation` template entity if one exists; agent rail comes from `MJ: AI Agents` filtered by `Status='Active'` and user-permission view. - **Behavior:** Composer is the first focus. Pressing send creates a new `MJ: Conversation` + a `MJ: Conversation Detail` (user message) → routes to a fresh chat thread which then streams the agent response. Voice mic enters `voice-mode.html`. - **Tapping a suggested prompt:** writes the prompt into the composer (or sends immediately, per the suggestion's `autoSend` flag). - **Tapping an agent pill:** prefixes the composer with `@agent-name `. **Chat thread (hero):** - **Data sources:** `MJ: Conversation` (the open one), `MJ: Conversation Detail` (messages, ordered by sequence). Streaming via the existing `ConversationStreamingService` pattern (WebSocket). `MJ: Conversation Artifacts` + `MJ: Conversation Artifact Versions` for inline rendering and the dock. - **Top nav:** - Left: hamburger → opens conversation-list drawer. - Center: conversation title (from `MJ: Conversation.Name` or auto-derived) + a stacked avatar row showing every distinct agent that has participated (`SELECT DISTINCT AgentID FROM ConversationDetail WHERE ConversationID=...`) and message count. **No agent picker chip** — the conversation is multi-agent. - Right: `+` opens `new-conversation.html`. - **Recent conversations strip (under top nav):** horizontally scrollable. First chip is the active conversation (dark, with live-pulse dot), then 3–5 most recent. Each chip shows a tiny avatar stack representing participating agents. Tap → switch to that conversation without leaving the chat surface. - **Messages:** - User messages: right-aligned, `--user-bg` background bubble, top-right and bottom-left rounded corners. - Agent messages: full-width, no bubble. Top row shows agent avatar + name + duration. Below that, step indicators (checkmarks for "Queried X · 12 rows", etc.) rendered as small dim text. Then the message body. Then any inline artifact card. Then action chips (suggested follow-ups). - `@mention` parsing: `@research`, `@skip`, etc. are highlighted in user message bodies (semibold, no special color needed — matches existing Explorer parsing). - **Inline artifact card:** small framed card with brand-color icon, type label, title, meta line, 2–3 row preview, and a "View" footer link. Tap → `artifact-detail.html`. - **Action chips:** rendered from the agent's `SuggestedResponses` (existing MJ pattern). Tap a chip → append text to composer; for `autoSend` chips, send immediately. - **Collapsed artifact dock handle (~32px):** above the composer. Shows artifact count + tiny agent-color dot stack + chevron. Tap or swipe up → `artifacts-dock-open.html`. Auto-pulses briefly when a new artifact is produced, then returns to resting state. - **Composer:** placeholder text `"Reply or @mention an agent…"`. Mic button (brand color) on the right — tap → `voice-mode.html`. No attachment button in Phase 1 (phase 3). **Voice mode (Phase 2 design, Phase 1 visual scaffold):** > **Updated 2026-07-02:** core now provides realtime/voice via `@memberjunction/ai-realtime-client` (the framework-agnostic `BaseRealtimeClient` + provider drivers) fronting the server's `StartRealtimeClientSession` GraphQL transport. The original "record → upload `audio/webm` → server Whisper round-trip" approach is **superseded** — we reuse the core realtime brain from RN instead of building a bespoke STT pipeline. See the revised wiring below. - **Phase 1:** Tapping the mic from any thread navigates here and shows the visual mockup. The actual voice pipeline is stubbed. The screen is functional as a placeholder for the "voice-soon" experience but does not record. - **Phase 2 wiring (revised — reuse core, don't rebuild):** This mirrors the doc's "one TS brain, three UIs" thesis. Since the plan was first written, core shipped a full realtime voice stack; the mobile app should *consume* it rather than hand-roll a Whisper round-trip: - **The brain — `@memberjunction/ai-realtime-client`.** A framework-agnostic (no Angular, no DOM-framework) TypeScript package: the `BaseRealtimeClient` contract plus provider drivers (`openai`, `gemini`, `elevenlabs`, `assemblyai`, `xai`, resolved through `MJGlobal.ClassFactory` by provider key). This is the *client-side mirror* of the server's `BaseRealtimeModel` — the same pluggability machinery (`@RegisterClass`, `ClassFactory`) we already rely on runs it under Hermes unchanged. It owns the full-duplex session: transport, the response state machine, barge-in, tool-call routing, transcript deltas/finals, and narration. **Prompt and tool authority stay server-side** — the client applies the server-built session config verbatim. - **The transport — `StartRealtimeClientSession` (MJAPI GraphQL).** The Angular host calls this mutation to have the server mint an *ephemeral, provider-native* session config (`ClientRealtimeSessionConfig`: provider key, model, a short-lived credential/signed URL, and an opaque `SessionConfig`). The client driver then opens the provider socket **directly** (client-direct topology — audio frames never transit MJAPI, so latency is minimal). Tool results and transcript persistence flow back through the companion `ExecuteRealtimeSessionTool` / `RelayRealtimeTranscript` mutations. This is exactly the flow the Explorer host uses today — see the reference host below. - **What's RN-safe as-is vs. what needs an adapter:** The driver *logic* (contract, state machine, event translation, tool routing) is pure TS and reuses unchanged. The **audio plane is the browser-coupled part** — `@memberjunction/ai-realtime-client`'s shipped mic capture and playback are built on the Web Audio API (`AudioContext` + `AudioWorkletNode`, an `