Developer Docs

iOS Development Setup

Repository: ngwenya-ios
Submodule: ngwenya-front/mobile/ios
Requirements: Xcode 16+, Swift 6+, Apple Silicon Mac
Tested on: M1 Max, 64 GB RAM, macOS 15, Xcode 26.3

Quick Start

# 1. Clone (or init submodule)
cd /path/to/ngwenya-front
git submodule update --init mobile/ios
cd mobile/ios

# 2. Open Xcode and create project (see detailed steps below)
open -a Xcode

# 3. Build & run on Simulator (⌘R in Xcode)

The repo contains only Swift source files — no .xcodeproj is committed. You create the Xcode project locally, add the existing sources, and you're running in under 10 minutes.

Prerequisites

Tool Minimum Check
Xcode 16.0+ xcodebuild -version
Swift 6.0+ swift --version
macOS 15.0+ sw_vers 
# Verify simulator runtimes
xcrun simctl list runtimes | grep iOS
# Should show iOS 17.x or 18.x

# Accept Xcode license (if needed)
sudo xcodebuild -license accept

Project Setup in Xcode

Step 1: Create New Project

  1. File → New → Project... (⇧⌘N)
  2. Select iOS → App → Next
  3. Configure:
Field Value
Product Name Ngwenya
Organization Identifier com.mallnline
Interface SwiftUI
Language Swift
Storage None
  1. Save inside the cloned ngwenya-ios/ directory
  2. Uncheck "Create Git repository"

Step 2: Replace Default Files

Delete Xcode's generated starter files (ContentView.swift, NgwenyaApp.swift, Assets.xcassets), then add the repo's source files:

  1. Right-click Ngwenya group → Add Files to "Ngwenya"...
  2. Select everything in the Ngwenya/ directory:
    • NgwenyaApp.swift
    • Views/, Bridge/, Services/
    • Assets.xcassets/, Info.plist
  3. Options: Create groups ✅, Copy items ❌, Add to target ✅

Step 3: Set Info.plist Path

  1. Select project → Build Settings → search Info.plist
  2. Set INFOPLIST_FILE to Ngwenya/Info.plist

Step 4: Set Deployment Target

General → Minimum Deployments → iOS 17.0

Add Push Notification Capability

  1. Select target → Signing & Capabilities
  2. Click + Capability → Add Push Notifications
  3. Add Background Modes → check ✅ Remote notifications

Push tokens are only available on physical devices. The Simulator works for everything else.

APNs Key Setup (for real push testing)

  1. Apple Developer Portal → Keys → Create a Key
  2. Name: Ngwenya Push Key, check ✅ APNs
  3. Download the .p8 file (one-time download)
  4. Configure the backend (alerts subgraph):
APNS_KEY_ID=ABC123DEF4
APNS_TEAM_ID=YOURTEAMID
APNS_KEY_CONTENTS="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
APNS_BUNDLE_ID=com.mallnline.ngwenya
APNS_PRODUCTION=false

See Mobile Push Infrastructure for the full backend configuration.

Run on Simulator

  1. Select iPhone 16 Pro from the device dropdown
  2. Press ⌘R (Build & Run)

You should see:

  • ✅ 6-tab navigation bar at the bottom
  • ✅ Push permission dialog on first launch
  • ✅ Console: [NgwenyaApp] Push auth error: (expected — simulators don't support APNs)
Feature Simulator Physical Device
Tab navigation ✅ ✅
WebView bridge ✅ ✅
Push token registration ❌ ✅
Camera / biometrics ❌ ✅

Run on Physical Device

  1. Connect iPhone via USB-C / Lightning
  2. Select your iPhone from the device dropdown
  3. ⌘R — Xcode will install and launch
  4. Trust the developer certificate: Settings → General → VPN & Device Management

After granting notification permission, check Xcode console:

[NgwenyaApp] APNs token: a1b2c3d4e5f6...

Local Backend Development

API Endpoint

Update PushNotificationManager.swift to point to your Mac's backend:

// Your Mac and iPhone must be on the same Wi-Fi
private let graphQLEndpoint = "http://192.168.1.XXX:30000/graphql"
// Find your IP: System Settings → Network → Wi-Fi → Details

WebView URL

Update WebViewBridge.swift:

let baseURL = "http://192.168.1.XXX:5173"  // Vite dev server

The Info.plist already includes an ATS exception for localhost to permit HTTP in development.

WebView Bridge Testing

Enable Safari Web Inspector

  • iPhone: Settings → Safari → Advanced → Web Inspector ✅
  • Mac: Safari → Settings → Advanced → Show features for web developers ✅

Inspect the WebView

  1. Navigate to the Malet tab in the app
  2. Open Safari on Mac → Develop → select your Simulator/device → Ngwenya
  3. In the Web Inspector console:
// Verify token injection
window.__NGWENYA_TOKEN__    // → JWT string
window.__NGWENYA_PLATFORM__ // → "ios"

// Test bridge messaging
window.webkit.messageHandlers.ngwenyaBridge.postMessage({
  action: "navigate",
  route: "/cart"
});
// Check Xcode console for: [WebViewBridge] Navigate: /cart

The frontend detects this context via mobileUtils.ts — isMobileWebView(), getMobilePlatform(), and getNativeAuthToken().

Project Structure

Ngwenya/
├── NgwenyaApp.swift              # @main entry + APNs AppDelegate
├── Info.plist                    # Bundle config, URL scheme, ATS
├── Assets.xcassets/              # App icon + AccentColor
├── Views/
│   ├── ContentView.swift         # 6-tab TabView shell
│   ├── LobbyView.swift           # Native discovery feed
│   ├── MaletView.swift            # WKWebView delegate
│   ├── UCartView.swift            # Native cart
│   ├── MurchasesView.swift        # Native order history
│   ├── NotificationsView.swift   # Push notification inbox
│   └── UChatView.swift            # Native messaging
├── Bridge/
│   └── WebViewBridge.swift        # WKWebView + JS bridge + token injection
└── Services/
    ├── AuthManager.swift          # JWT token singleton
    └── PushNotificationManager.swift  # GraphQL push token registration

Troubleshooting

Problem Solution
"No such module 'SwiftUI'" Set deployment target to iOS 17.0+
"Signing requires a development team" Select team in Signing & Capabilities, or disable for sim-only
Push token not in console Simulators don't support APNs — use physical device
WebView blank white screen Update baseURL in WebViewBridge.swift to your local IP
"Multiple commands produce" Delete DerivedData: rm -rf ~/Library/Developer/Xcode/DerivedData/Ngwenya-*