TrustMap is an iOS and Mac Catalyst app for saving places you trust and discovering recommendations from friends. It combines a personal place list, social map, reviews, dish notes, photos, friend profiles and activity feeds around one backend-owned source of truth.
This repository contains the SwiftUI client. The companion backend lives in the separate TrustMap-server repository and must be running for the app to sign in, load data, upload photos and sync social features.
- Sign in with Apple.
- Demo access beside Privacy Policy and Support opens a credential sheet for the prepared App Review account. Configure the companion API using
TrustMap-server/docs/demo-access.mdbefore distributing a build with this feature. - Map-based discovery of saved and friend-recommended places.
- Place search with custom place support.
- Place reviews with ratings, notes, photos and visibility controls.
- Dish reviews linked to places and optional place reviews.
- Friend search, friend requests and friend profile views.
- Block users from their profiles; unblock in Settings → Privacy → Blocked Users.
- Report place and dish reviews without entering text by touching and holding a review inside place details.
- Open the author's profile by tapping their name on a place or dish review.
- Feed of visible friend activity.
- Profile management, avatar upload and privacy settings.
- Push notification registration and in-app notification views.
- Account deletion flow.
- iPhone, iPad and Mac Catalyst support from one SwiftUI codebase.
- Swift 6
- SwiftUI
- MapKit
- AuthenticationServices for Sign in with Apple
- UserNotifications and APNs device-token registration
- URLSession-based API client
- Keychain storage for access and refresh tokens
- Xcode project plus a Swift Package target for contract-support tests
.
|-- App/ # App entry point and root navigation shells
|-- Config/ # Shared, Local and Prod build configuration
|-- Core/ # Networking, session, keychain and app state
|-- Features/ # Product features grouped by domain
|-- Resources/ # Assets, Info.plist files, entitlements
|-- Shared/ # Reusable UI, layout and platform helpers
|-- Tests/ # Swift package contract-support tests
|-- TrustMap.xcodeproj
|-- Package.swift
`-- scripts/generate_project.rb
The app is organized by feature. Each feature owns its models, repositories, view models and views where practical. Shared infrastructure lives in Core, while reusable UI components live in Shared.
The networking layer resolves the base API URL from the active build configuration. Authenticated requests use the current access token and can refresh the session when the backend returns an authorization failure. Tokens are stored in Keychain.
The backend is the source of truth for users, places, reviews, photos, visibility and social graph state.
The Xcode project includes two shared schemes:
-
Local- Uses
Config/Local.xcconfig. - Reads
TrustMapAPIBaseURLfromResources/Info-Local.plist. - Targets a backend reachable from a simulator or physical device on the same LAN.
- Uses APNs development environment.
- Uses
-
Prod- Uses
Config/Prod.xcconfig. - Reads
TrustMapAPIBaseURLfromResources/Info-Prod.plist. - Targets the production backend URL configured in
Config/Prod.xcconfig. - Uses APNs production environment.
- Uses
- Xcode with Swift 6 support
- iOS 18 SDK or newer
- A TrustMap backend instance
- Apple Developer account for device builds that use Sign in with Apple, push notifications and automatic signing
The app's deployment target is configured in Config/Base.xcconfig.
Resources/PrivacyInfo.xcprivacy is bundled with the shared app target in Local and Prod, including Mac Catalyst. It declares UserDefaults under required-reason API code CA92.1 for app-owned preferences and sign-in state. App Store Connect data-collection disclosures must still reflect the app and backend; this API declaration does not replace them.
Settings > About includes a Support link to the website, where the contact email support@trustmap.hubertik.com is provided.
Both build schemes include the Privacy Policy (https://trustmap.hubertik.com/privacy), Support (https://trustmap.hubertik.com/support), and Terms of Service (https://trustmap.hubertik.com/terms/) links from Config/Base.xcconfig, expanded into their Info.plist files. They appear below Sign in with Apple and in Settings > About. Privacy Policy, Terms of Service, Support, and the compact Demo button share one row on the welcome screen. The demo sheet retains its full Demo access title. Runtime overrides are available through TRUSTMAP_PRIVACY_POLICY_URL, TRUSTMAP_SUPPORT_URL, and TRUSTMAP_TERMS_OF_SERVICE_URL.
Start the TrustMap backend locally from the sibling TrustMap-server repository. The simplest path is:
cd ../TrustMap-server
docker compose up --buildThe development API listens on:
http://localhost:5104
For a physical iPhone, use a LAN-reachable hostname or IP address instead of localhost.
Create a local override file:
cp Config/Local.override.xcconfig.example Config/Local.override.xcconfigSet the host to your Mac's Bonjour hostname or LAN IP:
TRUSTMAP_LAN_HOST = your-mac-name.local
or:
TRUSTMAP_LAN_HOST = 192.168.1.42
Config/Local.override.xcconfig is ignored by Git.
Open the project:
open TrustMap.xcodeprojSelect the Local scheme and run on a simulator or device.
Production builds use:
Config/Prod.xcconfig
Resources/Info-Prod.plist
The production API base URL is configured through API_BASE_URL in Config/Prod.xcconfig.
Before shipping a production build:
- Confirm the backend URL points to the intended environment.
- Confirm the bundle identifier matches the Apple Developer configuration.
- Confirm Sign in with Apple is enabled for the app identifier.
- Confirm push notification entitlements and APNs environment are correct.
- Confirm the backend allows the production bundle ID in
AppleAuth:AllowedAudiences.
The app uses automatic code signing and the entitlements in:
Resources/TrustMap.entitlements
Current capabilities include:
- Sign in with Apple
- Push notifications
Mac Catalyst signing uses the same entitlements. A normal signed Catalyst build needs a matching Mac Catalyst development or distribution profile for the configured bundle identifier.
For source-only validation on a machine without signing profiles, build with signing disabled where appropriate:
xcodebuild \
-project TrustMap.xcodeproj \
-scheme Local \
-destination 'generic/platform=iOS Simulator' \
CODE_SIGNING_ALLOWED=NO \
buildTrustMap builds as a Mac Catalyst app from the iOS target. The Catalyst UI uses a desktop-oriented SwiftUI shell with sidebar navigation, toolbar actions, keyboard shortcuts, constrained panels and a minimum resizable window size.
Relevant build settings live in Config/Base.xcconfig:
SUPPORTED_PLATFORMS = iphoneos iphonesimulator macosx
SUPPORTS_MACCATALYST = YES
TARGETED_DEVICE_FAMILY = 1,2
This repository includes a Swift Package target for contract-support tests around networking models and client-side API behavior.
Run tests from Xcode, or use Swift Package Manager:
swift testSome full-app behavior depends on the Xcode project, Apple frameworks and a running backend, so Xcode is the primary environment for app validation.
Startup allows 45 seconds for a sleeping backend to respond. Temporary connection failures preserve Keychain tokens and lead to a generic error with a retry button, without technical details or another Apple sign-in. Safe profile reads can retry within that deadline; Apple sign-in and rotating refresh tokens are never replayed automatically. A definitive session rejection still requires sign-in.
When the saved access token expires within 30 seconds, startup calls /auth/refresh
directly and uses the returned profile, avoiding the old /me → refresh → /me
sequence. Concurrent refresh callers share one request and use persisted tokens.
When the welcome screen appears, the app also sends one anonymous, uncached
GET /health/live per app launch to start waking the backend while the user
confirms Sign in with Apple. This probe runs independently of sign-in, allows
45 seconds for the response, and never shows an error or changes credentials.
Successful sign-in cancels any remaining probe. There is no periodic keep-alive,
no probe during session restoration, and no probe in SwiftUI previews.
SessionRestorationTests covers this behavior using the production session store
and API transport with fake HTTP responses. These changes require an updated app;
they do not change the Azure hosting plan or prevent Free F1 from sleeping.
The app expects the backend to provide:
- Apple sign-in exchange through
/auth/apple. - Refresh-token rotation through
/auth/refresh. - Authenticated endpoints for users, friends, categories, places, reviews, feed, map, photos, notifications and device tokens.
- Protected media endpoints that accept the current access token.
- String enum values in JSON payloads.
See the backend documentation for API and deployment details.
Blocking and reporting require the companion server's AddBlockingAndReporting migration. Reports are stored on the server; its default mode prepares private .eml files for moderation without automatic email delivery. See TrustMap-server/docs/blocking-and-reporting.md for configuration.
The following local files and directories are intentionally ignored:
.build/
Config/Local.override.xcconfig
xcuserdata/
*.ipa
*.dSYM
Do not commit signing assets, provisioning profiles, private keys or local environment overrides.
TrustMap supports English (en, the source and fallback language), Polish (pl),
German (de), Spanish (es), French (fr), Italian (it), Portuguese (pt), and
Ukrainian (uk). iOS selects the best supported language from the user's language
preferences; it also exposes the app's language setting in system Settings.
Resources/Localizable.xcstringsowns app copy, stable keys, translations, and native plural rules, including Polish and Ukrainianone/few/many/otherforms.Core/Localization/L10n.swiftprovides the typed Swift interface used by views, models, validation, accessibility labels, and error messages.Resources/InfoPlist.xcstringstranslates camera and location permission prompts for both Local and Prod. The base Info.plist files retain English fallback text.- The welcome map preview uses SwiftUI/MapKit with localized sample copy rather than a screenshot with English text baked into its pixels.
- System controls (including Sign in with Apple), relative dates, numbers, and currency formatting use the system's locale support.
- Push alerts use APNs
loc-key/loc-argsto select their message from the app's compiled catalog in its current language, even while the app is closed. The three normal message keys are shared with in-app notifications.push.*keys supply translated generic and anonymous-actor fallbacks; these keys are consumed by iOS directly rather than the typedL10nAPI. Ship these catalogs before the companion backend's localized push update. - User-generated reviews, place names, usernames, and custom category names are retained. The built-in Restaurants category is translated for display while its canonical API name and ID remain stable.
- Known server error messages are translated for display using the catalog's English entries. Raw associated error values stay unchanged for error handling. New, unknown server messages retain their original text until added to the catalog.
When adding copy, create a stable catalog key, provide every supported translation,
and add a corresponding L10n property or function. Use a native plural variation
for count-dependent nouns; pass complete sentences with arguments rather than
concatenating translated fragments. Technical API identifiers are not localization
keys. Keep localized text out of stored data and request payloads.
Validate catalog coverage and formatting arguments with:
python3 scripts/validate_localizations.py
swift testLocalizationTests checks that every entry is packaged in every language, checks
navigation translations, and exercises compiled Foundation plural rules with
counts such as 1, 2, 5, 12, and 22. For visual QA, set a scheme's Application Language
and run on an iPhone/iPad simulator; verify navigation, form labels, VoiceOver,
empty states, and permission dialogs. Both the existing project and project
regeneration script include the catalogs and all eight development regions.