# 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 design constants.

## Core Data Flow
- `AppState` owns:
  - `CardStore` (cards and selection)
  - `ContactsStore` (contact list + search)
  - `ShareLinkService` (share URLs)
  - `QRCodeService` (QR generation)
- Views read state via environment and render UI only.

## Important Files

### Models
- `BusinessCard/Models/BusinessCard.swift` — business card data + vCard payload
- `BusinessCard/Models/Contact.swift` — contact tracking model
- `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/QRCodeProviding.swift`
- `BusinessCard/Protocols/ShareLinkProviding.swift`

### State
- `BusinessCard/State/AppState.swift`
- `BusinessCard/State/CardStore.swift`
- `BusinessCard/State/ContactsStore.swift`

### Services
- `BusinessCard/Services/QRCodeService.swift` — CoreImage QR generation
- `BusinessCard/Services/ShareLinkService.swift` — share URL helpers

### Views
- `BusinessCard/Views/RootTabView.swift` — tabbed shell
- `BusinessCard/Views/CardsHomeView.swift` — hero + card carousel
- `BusinessCard/Views/ShareCardView.swift` — QR + share actions
- `BusinessCard/Views/CustomizeCardView.swift` — theme/layout controls
- `BusinessCard/Views/ContactsView.swift` — tracking list + search
- `BusinessCard/Views/WidgetsView.swift` — preview mockups

### Design + Localization
- `BusinessCard/Design/DesignConstants.swift`
- `BusinessCard/Resources/Localizable.xcstrings`

### 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` includes basic unit tests.

## Known Stubs / TODOs
- Apple Wallet and NFC flows are alert-only placeholders.
- Share URLs are sample placeholders.
- Widget previews are not WidgetKit extensions.

## If You Extend The App
- Add new strings to the String Catalogs.
- Add new constants to `DesignConstants.swift` instead of literals.
- Keep view logic UI-only; push business logic to state classes.
- Prefer protocols for new capabilities.