TopDogLabs/BusinessCard
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
9e87de5ce9
BusinessCard/ai_implmentation.md

5.0 KiB
Raw Blame History

AI Implementation Context

This file summarizes project-specific context, architecture, and conventions to speed up future AI work.

Project Summary

BusinessCard is a SwiftUI app for building and sharing digital business cards with QR codes. It includes iOS screens for cards, sharing, customization, contact tracking, and widget previews, plus a watchOS companion to show a default card QR code.

Key Constraints

  • iOS 26+, watchOS 12+, Swift 6.2.
  • SwiftUI with @Observable classes and @MainActor.
  • Protocol‑oriented architecture is prioritized.
  • No UIKit unless explicitly requested.
  • String Catalogs only (.xcstrings).
  • No magic numbers in views; use Bedrock's Design constants.
  • Uses Bedrock package for shared design system and utilities.

Core Data Flow

  • AppState owns:
    • CardStore (cards and selection)
    • ContactsStore (contact list + search)
    • ShareLinkService (share URLs)
  • SwiftData with CloudKit for persistence and sync.
  • App Groups for iOS-Watch data sharing.
  • Views read state via environment and render UI only.

Dependencies

Bedrock Package

Located at /Frameworks/Bedrock (local package). Provides:

  • Design.Spacing, Design.CornerRadius, Design.Opacity, etc.
  • QRCodeGenerator and QRCodeImageView for QR codes
  • Reusable settings components

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

  • Design.CardSize - card dimensions, avatar, QR sizes
  • Design.Shadow.offsetNone - zero offset extension
  • Color.AppBackground, Color.CardPalette, Color.AppAccent, Color.AppText

Important Files

Models

  • BusinessCard/Models/BusinessCard.swift — SwiftData model with:

    • Basic fields: name, role, company, email, phone, website, location
    • Rich fields: pronouns, bio, social links (LinkedIn, Twitter, Instagram, etc.)
    • Custom links: 2 slots for custom URLs
    • Photo: photoData stored with @Attribute(.externalStorage)
    • Computed: theme, layoutStyle, vCardPayload, hasSocialLinks

  • BusinessCard/Models/Contact.swift — SwiftData model with:

    • Basic fields: name, role, company
    • Annotations: notes, tags (comma-separated), followUpDate, metAt
    • Received cards: isReceivedCard, receivedCardData (vCard)
    • Photo: photoData
    • Computed: tagList, hasFollowUp, isFollowUpOverdue
    • Static: fromVCard(_:) parser

  • BusinessCard/Models/CardTheme.swift — card theme palette

  • BusinessCard/Models/CardLayoutStyle.swift — stacked/split/photo

Protocols (POP)

  • BusinessCard/Protocols/BusinessCardProviding.swift
  • BusinessCard/Protocols/ContactTracking.swift
  • BusinessCard/Protocols/ShareLinkProviding.swift

State

  • BusinessCard/State/AppState.swift — central state container
  • BusinessCard/State/CardStore.swift — card CRUD, selection, watch sync
  • BusinessCard/State/ContactsStore.swift — contacts, search, received cards

Services

  • BusinessCard/Services/ShareLinkService.swift — share URL helpers
  • BusinessCard/Services/WatchSyncService.swift — App Group sync to watch

Views

  • RootTabView.swift — tabbed shell
  • CardsHomeView.swift — hero + card carousel
  • CardEditorView.swift — create/edit cards with PhotosPicker
  • BusinessCardView.swift — card display with photo and social icons
  • ShareCardView.swift — QR + share actions + track share
  • CustomizeCardView.swift — theme/layout controls
  • ContactsView.swift — tracking list with sections
  • ContactDetailView.swift — full contact view with annotations
  • QRScannerView.swift — camera-based QR scanner
  • QRCodeView.swift — wrapper for Bedrock's QRCodeImageView
  • WidgetsView.swift — preview mockups

Design + Localization

  • BusinessCard/Design/DesignConstants.swift — extends Bedrock
  • BusinessCard/Resources/Localizable.xcstrings
  • BusinessCard/Localization/String+Localization.swift

watchOS

  • BusinessCardWatch/BusinessCardWatchApp.swift
  • BusinessCardWatch/Views/WatchContentView.swift
  • BusinessCardWatch/State/WatchCardStore.swift
  • BusinessCardWatch/Resources/Localizable.xcstrings

Localization

  • All user-facing strings are in .xcstrings.
  • Supported locales: en, es‑MX, fr‑CA.
  • Use String.localized("Key") for non-Text strings.

Testing

  • BusinessCardTests/BusinessCardTests.swift covers:
    • vCard payload formatting
    • Card CRUD operations
    • Contact search and filtering
    • Social links detection
    • Contact notes/tags
    • Follow-up status
    • vCard parsing for received cards

Known Stubs / TODOs

  • Apple Wallet and NFC flows are alert-only placeholders.
  • Share URLs are sample placeholders.
  • Widget previews are not WidgetKit extensions.
  • See ROADMAP.md for full feature status.

If You Extend The App

  1. Add new strings to the String Catalogs.
  2. Use Design.* from Bedrock for spacing, opacity, etc.
  3. Add app-specific constants to DesignConstants.swift.
  4. Keep view logic UI-only; push business logic to state classes.
  5. Prefer protocols for new capabilities.
  6. Add unit tests for new model logic.
  7. Update ROADMAP.md when adding features.