Native mobile app (Aaperture-mobile) — development handbook

This document is the entry point for resuming work on the React Native app. UI and component rules remain in AGENTS_MOBILE.md. Product scope narrative lives in SCOPE_PRODUIT_COMPLET.md (French) and APP_OVERVIEW.md.

Repository layout

• Monorepo (this repository): aaperture — backend (backend/), web studio (frontend/), OpenAPI (openapi/), shared docs (docs/).
  • In this monorepo, “mobile” = backend routes only (backend/src/mobile/**, OpenAPI paths/mobile/). Not a React Native package.
• Native app (sibling checkout): aaperture-mobile — expected path ../aaperture-mobile relative to this repo (same parent directory). Second Frame product.

Keep mobile-specific runbooks, release notes, and screen maps in aaperture-mobile/docs/ when they only apply to the native codebase. Keep cross-cutting contracts (API behavior, Iris semantics, parity expectations) here under docs/ so web and mobile agents share one source of truth.

Cleanup map: APP_CLEANUP_MAP.md.

Mandatory reading before coding

1. AGENTS_MOBILE.md — tokens, typography, navigation, touch targets, PR checklist.
2. AGENTS_DESIGN.md — brand and visual language aligned with the studio web app.
3. AGENTS_BACKEND.md (documentation interne) § Mobile Module — POST /api/mobile/sync, push tokens, queues (see also backend/src/mobile/README.md).
4. AGENTS_OPENAPI.md (documentation interne) — regenerating the client after API changes.

Web-only detail for the Iris workspace (composer, metadata, streaming) is summarized below and fully described in REFONTE_CHAT_AGENT.md.

Backend surfaces used by the native app

Area	Notes
Auth	Same tenant/user auth model as web; store tokens securely (Keychain / Keystore). Device login: POST /mobile/auth/login, /mobile/auth/google.
Sync	POST /api/mobile/sync — cursor-based delta sync (see AGENTS_BACKEND.md). Persist cursor for offline/resume.
Push	POST /api/mobile/push-tokens, DELETE /api/mobile/push-tokens — register on login, revoke on logout.
Community / network	KEEP — /mobile/me, map, /mobile/network*, messages. Friends domain exposed here.
Friends port	BACKLOG — port web Friends UX into sibling aaperture-mobile (Circles / network).
Doublons port	BACKLOG — web FE removed; reuse studio BE /duplicates + Discord share in aaperture-mobile.
OpenAPI	Regenerate aaperture-mobile API client when openapi/ changes; do not hand-maintain duplicate DTOs long-term.

Absent from native contract (do not build on mobile): progression/gamification (deleted), Gmail plugin, dense CRM editors, SMS (hidden on web). Doublons/Discord is backlog (not in MVP shell) — see table above.

Iris (assistant) parity expectations

When the mobile app exposes Iris or another CRM assistant surface:

• Conversation payload: Follow the same metadata conventions as web — contextTokens array on user messages: { type: string, label: string, id?: string }.
• Supported context types (aligned with web studio) include at minimum: contact, session, quote, invoice, gallery, slideshow (slideshow token id is composite: galleryId + GALLERY_SLIDESHOW_CONTEXT_ID_JOINER + slideshowId; see buildSlideshowContextTokenId / parseSlideshowContextTokenId in frontend/src/components/search/agent/contextTokens.ts).
• Attachments: Web currently ties uploaded files to CRM entities for contact, session, quote, invoice only; until the API extends this, do not assume gallery/slideshow attachment linkage on mobile without checking OpenAPI and AGENTS_BACKEND.md.
• Shortcuts: Web shows keyboard shortcuts in tooltips only (e.g. global search, Iris toggle, send). On mobile, surface equivalents via long-press hints, accessibility hints, or an in-app “Shortcuts” sheet — not as desktop-style kbd badges.
• Inline widgets (2026-07): Interactive modules are persisted in conversation_widgets and referenced in assistant content via [[widget:UUID]] tags. Mobile must:
  • Load widgets with GET /agent/conversations/{conversationId}/widgets (or use widgets / updatedWidgets on POST /agent/chat responses).
  • Render by ConversationWidget.type (request_info, ui_actions, slash_command_form, email_send_confirm, action_result, external_info, export_download, conflict).
  • Submit user input with metadata.widgetResponse: { widgetId, response?, status?: "done" | "canceled" } on the next chat message (same contract as web MessageWithWidgets).
  • Listen for agent:message:complete on the /agent Socket.IO namespace for cross-tab / background completion; merge widget payloads into local conversation state.
  • Do not use legacy formEvent or requestInfoResponse metadata keys.
• Native MVP status (2026-07): aaperture-mobile ships src/features/agent/ with Iris screen, full widget registry, REST + Socket.IO merge, and optimistic send states. Still missing vs web: @ / / composer, conversation file uploads, and smart CRM deep links from action_result.

Product-facing welcome copy on web mentions @ context for contacts, sessions, quotes, invoices, galleries, and slideshows; mirror that capability in mobile UX when the composer ships.

PWA vs native

• Web responsive / PWA: frontend/ — mobile layouts, AgentMobile.tsx, MobileSidebar.tsx; navigation patterns in MOBILE_NAVIGATION.md.
• Native: aaperture-mobile/ — Expo Router, offline-first sync, push; must not diverge on business rules from web for the same tenant APIs.

Documentation maintenance

• Changing mobile API contracts or Iris metadata: update this file or AGENTS_BACKEND.md, then regenerate OpenAPI clients.
• Changing UI parity rules: update AGENTS_MOBILE.md first.
• After adding or renaming files under docs/ that appear on the public doc site, run npm run sync from docs-site/ and update docs-site/sidebars.js if the doc should appear in the sidebar.

Suggested first sprint checklist (restart)

1. Confirm aaperture-mobile runs on supported Expo SDK / Node versions (see mobile repo README).
2. Point the app at staging API; verify auth + sync + push token round-trip.
3. Align design tokens with AGENTS_MOBILE.md (single source in mobile theme).
4. Open tracking issues for parity gaps (screens vs web CRM scope).
5. When implementing Iris: reuse OpenAPI types for chat payloads and match web contextTokens semantics above.