BusinessCard

A SwiftUI iOS + watchOS app that creates and shares digital business cards with QR codes, quick share actions, customization, and contact tracking. Data syncs across devices via iCloud.

Platforms

• iOS 26+
• watchOS 12+
• Swift 6.2

Features

My Cards

• Full-screen card display: Swipe between your business cards in a full-screen view
• Tap the edit icon (pencil) in the top right to edit the current card
• Tap the plus icon to create a new card
• Set a default card for sharing
• Modern card design: Banner with optional cover photo, company logo, overlapping profile photo, clean contact rows
• Header layout picker: Choose how profile, cover, and logo images are arranged in the card header
  • Profile Banner: Profile photo fills the entire banner (great for personal branding)
  • Cover + Avatar: Cover image as banner with profile photo overlapping at bottom
  • Centered Logo: Cover image with company logo centered and profile avatar smaller
  • Logo Badge: Cover with small logo badge in corner, profile avatar overlapping
  • Side by Side: Avatar and logo displayed together in the content area
• Smart layout suggestions: The app suggests the best layout based on which images you've added
• Live layout preview: See exactly how each layout looks before selecting in both the picker and editor
• Profile photos: Add a headshot from library or camera with crop/zoom editor
• Cover photos: Add a custom banner background from library or camera
• Company logos: Upload a logo from library or camera
• 3-step photo workflow: Choose source (library/camera) → crop/position → save
• Rich profiles: First/middle/last name, prefix, maiden name, preferred name, pronouns, headline, bio, accreditations
• Clickable contact fields: Tap any field to call, email, open link, or launch app

Share

• Floating share button: Centered above the tab bar for quick access
• Dark-themed share sheet: Sleek QR code display with prominent sharing options
• Share options: copy link, SMS, email, WhatsApp, LinkedIn, and more
• Offline sharing toggle: Share your card without internet connection
• Track shares: Record who received your card and when
• Button is hidden when no cards exist
• Placeholder actions for Apple Wallet and NFC (alerts included)

Card Editor

Access via the edit (pencil) icon in the My Cards tab:

• Horizontal color picker: Scrollable theme swatches for quick selection
• Theme picker with multiple color palettes (Coral, Midnight, Ocean, Lime, Violet)
• Expandable name section: Prefix, first, middle, last, maiden name, suffix, preferred name, pronouns
• Edit all card details: Name, role, department, company, headline, bio
• Accreditations: Tag-based input with inline editing

Dynamic Contact Fields

Add unlimited contact fields of any type, reorder by drag-and-drop:

• Contact: Email, phone, website, address
• Social Media: LinkedIn, X/Twitter, Instagram, Facebook, TikTok, Threads, Bluesky, Mastodon, Reddit, Twitch, YouTube, Snapchat, Pinterest
• Developer: GitHub, GitLab, Stack Overflow, CodePen
• Messaging: Telegram, WhatsApp, Discord, Slack, Matrix, Signal
• Support & Funding: Patreon, Ko-fi, Buy Me a Coffee, GitHub Sponsors
• Payment: Venmo, Cash App, PayPal, Zelle
• Scheduling: Calendly
• Other: Custom links with any URL

Each field has:

• Custom icons: Brand-colored icons from asset catalog (not generic SF Symbols)

• Title/Label: Add context like "Work", "Personal", or custom call-to-action

• Deep linking: Opens native apps when available (X, Instagram, etc.)

• Drag-to-reorder: Long press and drag to change order

• Suggestion chips: Quick-fill suggestions for field titles

• Live preview: "Preview card" button to see changes before saving

• Delete cards you no longer need

Contacts

• Add contacts manually: Tap + to create contacts with name, role, company, email, phone
• Profile photos: Add or edit a photo for each contact
• Track who you've shared your card with
• Scan QR codes to save someone else's business card
• Notes & annotations: Add notes about each contact
• Tags: Organize contacts with comma-separated tags
• Follow-up reminders: Set reminder dates with overdue indicators
• Where you met: Record event or location where you connected
• Search contacts using localized matching (searches name, company, role, tags, notes)
• Shows last shared time and the card label used
• Swipe to delete contacts

Widgets (Preview Only)

• Phone widget preview mock
• Watch widget preview mock

watchOS App

• Shows the default card QR code full-screen (no card picker)
• Default card is determined by the iPhone app
• Syncs with iPhone via WatchConnectivity framework
• QR codes are pre-generated on iPhone (CoreImage not available on watchOS)

Data Sync

iCloud Sync (iOS)

Cards and contacts are stored using SwiftData with CloudKit sync enabled. Your data automatically syncs across all your iPhones and iPads signed into the same iCloud account.

CloudKit Schema Safety

Before changing any shipped SwiftData model schema, follow CLOUDKIT_SCHEMA_GUARDRAILS.md. This is the project checklist for safe additive changes and migration-friendly patterns.

iPhone to Watch Sync

The iPhone app syncs card data to the paired Apple Watch via WatchConnectivity framework using updateApplicationContext. When you create, edit, or delete cards on your iPhone, the changes are pushed to your watch automatically.

Note: The watch receives data from the iPhone. To update cards on the watch, make changes on the iPhone first. QR codes are pre-generated on iPhone since CoreImage is not available on watchOS.

IMPORTANT: Do NOT use App Groups for iPhone-Watch communication. App Groups only work between an app and its extensions on the SAME device. iPhone and Apple Watch are separate devices with separate file systems.

Architecture

• Clean Architecture: Clear separation between Views, State, Services, and Models
• Views are dumb: Presentation only, no business logic
• State is smart: @Observable classes with all business logic
• Centralized preferences: AppPreferencesStore is the single source of truth for app-level settings (theme/debug flags)
• Protocol-oriented: Interfaces for services and stores
• Protocol-based providers: AppMetadataProviding and VCardPayloadProviding keep services/state decoupled
• SwiftData + CloudKit: Persistent storage with iCloud sync
• WatchConnectivity: iPhone to Apple Watch sync (NOT App Groups)
• One type per file: Lean, maintainable files under 300 lines
• Reusable components: Shared UI in Views/Components/
• Bedrock package: Shared design system and utilities
• String Catalogs: Localization for en, es-MX, fr-CA
• Single source of truth for names: BusinessCard.fullName is computed from individual name fields (no stored displayName)

Dependencies

Bedrock (Local Package)

The app uses the Bedrock package for:

• Design constants: Design.Spacing, Design.CornerRadius, Design.Opacity, etc.
• QR code generation: QRCodeGenerator, QRCodeImageView
• Reusable UI components: Settings views, badges, effects

App-specific extensions are in Design/DesignConstants.swift.

Settings Layout Contract

SettingsCard is the single owner of horizontal row inset in SettingsView.

• Use SettingsCardRow for custom in-card rows (HStack, status/info rows, custom content).
• Use SettingsDivider between in-card rows (instead of Divider/manual lines).
• Use SettingsNavigationRow(..., backgroundColor: .clear) for standard in-card navigation rows.
• Avoid child .padding(.horizontal, ...) inside SettingsCard unless intentional indentation is required.

Project Structure

BusinessCard/
├── Assets.xcassets/
│   └── SocialSymbols/   # Custom brand icons (LinkedIn, X, Instagram, etc.)
├── Configuration/       # App identifiers and configuration
│   ├── Base.xcconfig         # Source of truth for all identifiers
│   ├── Debug.xcconfig        # Debug configuration (imports Base)
│   ├── Release.xcconfig      # Release configuration (imports Base)
│   └── AppIdentifiers.swift  # Swift interface to configuration
├── Design/              # Design constants (extends Bedrock)
├── Localization/        # String helpers
├── Models/
│   ├── BusinessCard.swift    # Main card model
│   ├── CardHeaderLayout.swift # Header layout options (profile banner, cover+avatar, etc.)
│   ├── Contact.swift         # Received contacts
│   ├── ContactField.swift    # Dynamic contact fields (SwiftData)
│   └── ContactFieldType.swift # Field type definitions with icons & URLs
├── Protocols/           # Protocol definitions
├── Resources/           # String Catalogs (.xcstrings)
├── Services/            # ShareLinkService, VCardFileService, WatchConnectivityService
├── State/               # Observable stores (CardStore, ContactsStore)
└── Views/
    ├── Components/      # Reusable UI (ContactFieldPickerView, HeaderLayoutPickerView, etc.)
    ├── Sheets/          # Modal sheets (ContactFieldEditorSheet, RecordContactSheet, etc.)
    ├── Widgets/         # Widgets feature view + feature-specific components
    └── [Feature].swift  # Feature screens

BusinessCardWatch Watch App/  # watchOS app target (WatchConnectivity sync)
BusinessCardTests/       # Unit tests

Configuration

Required Capabilities

iOS Target:

• iCloud (CloudKit enabled)
• App Groups (group.com.mbrucedogs.BusinessCard) - for future widget access
• Background Modes (Remote notifications)
• Camera (for QR code scanning)

watchOS Target:

• WatchConnectivity (for receiving cards from iPhone)
• Bundle ID must be prefixed with iOS bundle ID (e.g., com.mbrucedogs.BusinessCard.watchkitapp)

Watch App Embedding (CRITICAL)

The watch app must be embedded in the iOS app for deployment. In the iOS target's Build Phases:

1. "Embed Watch Content" phase must exist
2. "Code Sign On Copy" must be CHECKED ✓

Without this, the iOS app installs but the watch app does NOT install on the paired Apple Watch. See Agents.md for full troubleshooting guide.

CloudKit Container

iCloud.com.mbrucedogs.BusinessCard

App Identifiers (xcconfig)

All company-specific identifiers are centralized in Configuration/Base.xcconfig:

COMPANY_IDENTIFIER = com.mbrucedogs
DEVELOPMENT_TEAM = 6R7KLBPBLZ

This flows through:

• Build settings: Bundle IDs, Team ID (via xcconfig → project)
• Entitlements: CloudKit container, App Group (via variable substitution)
• Swift code: AppIdentifiers.* (via Info.plist → Bundle.main)

To migrate to a new developer account: Update Base.xcconfig only. See DevAccount-Migration.md.

Notes

• Share URLs are sample placeholders
• Wallet/NFC flows are stubs with alerts only
• Widget UI is a visual preview (not a WidgetKit extension)

Running

1. Open BusinessCard.xcodeproj in Xcode
2. Ensure Bedrock package is resolved (File → Packages → Resolve Package Versions)
3. Build and run on iOS Simulator or device

Tests

Unit tests cover:

• vCard payload formatting
• Default card selection
• Contact search filtering
• Create, update, delete cards
• Contact tracking (new and existing contacts)
• Theme and layout assignment
• Social links detection
• Contact notes and tags
• Follow-up status and overdue detection
• vCard parsing for received cards
• Adding received cards via QR scan

Run tests with Cmd+U in Xcode.

Roadmap

See ROADMAP.md for planned features and implementation status.

---

Built with SwiftUI, SwiftData, and ❤️