143 lines
5.0 KiB
Markdown
143 lines
5.0 KiB
Markdown
# 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.
|