Native iOS Shell for a Community Hub & AI Chat

Overview

A native Swift iOS app that wraps the community hub and its AI chat (a customised LibreChat fork) in the hybrid pattern where the conversation is the web page and everything around it is native: composer, dictation, sign-in, notifications, QR scanning and a phone-to-phone “Bump” gesture. Built over 93 commits in roughly four weeks and taken all the way to an App Store submission.

Why It Exists

The hub and chat already lived on the web, but a community app needs the parts a WKWebView cannot do well: a keyboard-correct composer, on-device speech, native Sign in with Apple, push with a badge, camera access for member cards, and a sensor-driven way for two people at an event to exchange contacts. Rebuilding the whole product natively would have duplicated the web work; a thin native shell with a clear bridge contract gives the native feel where it matters and keeps one source of truth for the content.

What We Built

An XcodeGen-generated single-target app (iOS 17+, iPhone only) with the source split by concern under AmbasadaChat/Sources: Web (persistent-session WKWebViews, no accessory bar, pinned viewport / no pinch-zoom, dead-content-process recovery, the window.ambasadaNative JavaScript bridge that flips the web app into native mode by user agent), Composer (native input bar with send/stop and dictation), Speech (on-device recognition, Romanian first), Tabs and Navigation (registry-driven tabs and a router that sends chat URLs to the Chat tab and hub links to the hub tab, including cold-start deep links), Registry (a bundled registry.json with a remote override), Auth (native Apple / Google / LinkedIn sign-in through the Clerk iOS SDK, exchanged for a ticket the web session accepts), Welcome (four native intro pages shown before first sign-in), Push (APNs registration, consent asked once at the moment that earns it, a native notifications screen fed by the hub, badge clearing, taps that read the target URL from the Novu payload), Scan (camera scanner for member cards and documents) and Bump (100 Hz motion sampling with a registry-tuned spike threshold, a room socket that pairs two knocking phones, mutual accept, and a match that opens a card, a hub sheet or a full page). Universal links cover the hub and chat domains, with an ambasada:// scheme and a bundle-id scheme for Clerk callbacks. Six XCTest suites cover auth, bump, inbox, router, session and welcome logic.

Release engineering ships with the repo: a fastlane setup with lanes to create the app record, manage signing, archive, push to TestFlight, upload the entire store listing as code (EN/RO copy, framed screenshots generated by a Node script, review notes, age rating, privacy answers, availability), plus an ota.sh script that archives, packages an IPA and serves it over a Cloudflare dev tunnel for cable-free installs on registered devices. A PrivacyInfo.xcprivacy manifest declares the required-reason APIs and the push token as the only collected identifier.

Technologies & Approach

Swift 5.10 with the project declared in project.yml (XcodeGen) so the .xcodeproj is reproducible and never committed. WKWebView carries the product; a small, explicit bridge contract (window.ambasada.postMessage from the page, window.ambasadaNative.* from native) keeps the two sides decoupled. Clerk’s iOS SDK provides native OAuth and Sign in with Apple; session state is read from the pages rather than URLs. Core Motion and a WebSocket room drive Bump; the Speech framework handles dictation fully on-device. fastlane and a handful of zsh scripts make the store and OTA pipelines repeatable from a shell.

Outcome / Impact

A store-ready iPhone app that gives the community hub and its AI chat a native front door: native sign-in, push with inbox, dictation, scanning and the Bump contact-exchange gesture, with the whole App Store listing, review notes and screenshots versioned next to the code. It is the iOS half of a matched pair with the Android client, sharing the same registry, bridge contract and feature set.

Capabilities Demonstrated

• Hybrid iOS architecture: persistent WKWebViews with a typed JavaScript bridge and user-agent-driven native mode
• Native composer and on-device speech recognition (Romanian-first) over a web chat
• Native Sign in with Apple, Google and LinkedIn via Clerk, handed to a web session as a ticket
• Phone-to-phone “Bump” contact sharing from accelerometer spikes plus a pairing room
• APNs push with one-time consent, a native inbox and badge management
• Universal links and custom URL schemes with tab-aware deep-link routing
• App Store listing, screenshots, privacy manifest and review notes managed as code with fastlane
• Over-the-air IPA distribution through a dev tunnel for fast device testing
• Reproducible Xcode projects with XcodeGen and XCTest coverage of the native logic