CardsFolder — MVP Plan

Project Goal

Create a fast, offline-first iOS app to store loyalty cards, quickly find them, and show barcodes/QR codes at checkout, with optional iCloud sync later.

Problem Statement

• Fast work with loyalty/discount cards: quick show at checkout, quick selection, quick search.
• Convenient way to save cards (manual + scan).

Success Criteria

• Great performance (smooth UI, fast open/show code, stable scanner).
• Works without internet (offline-first).
• Minimize risk of data loss (reliable persistence, safe edits, later iCloud sync).

Product Scope (MVP)

Cards only, local storage, fast UI, no templates API, no widgets.
Apple Wallet integration is not in MVP (planned as an optional later feature).

Device support:

• The app is designed for iPhone only.
• iPad/tablet-specific layouts and adaptations are out of scope and are not planned.

Scanner note:

• Barcode/QR scanning via custom AVFoundation capture screen (QR + Code128 + EAN-13).
• Text scanning (Vision OCR) is optional for later (heuristics + user confirmation).

Docs

• Roadmap: docs/ROADMAP.md
• MVP checklist: docs/MVP_CHECKLIST.md
• Code style: docs/CODE_STYLE.md

Current Status

• AppRootCoordinator wired.
• CardsCoordinator wired (Add/Capture flows + context menu actions).
• CoreDataService + CardRepository working with async/await.
• Cards module: diffable data source + grid/carousel + custom search overlay + empty state + context menu.
• Grid/carousel cards render saved custom image/color/background appearance.
• Add Card module: modal form + pickers (photo/color/camera) + validation + favorite (pin) draft + card appearance preview.
• Add/Edit persistence is split correctly: create flow calls repository.create, edit flow calls repository.update.
• Capture module: AVFoundation scanning (QR/Code128/EAN-13) with overlay + highlight animation.
• Card Code screen respects the selected QR/Code128/EAN-13 mode when rendering.
• CoreDataService reports persistent-store/save failures without fatalError in release builds.
• Unit test target added with Swift Testing.
• Test coverage now includes AddCardViewModel, CardsViewModel, card cell appearance helpers, CoreDataService, and CoreDataCardRepository local-storage integration tests.

Engineering Setup

• CI build workflow for pull requests and main release branches.
• Xcode project security audit workflow and local audit script.
• Repository hygiene via .gitignore for Xcode/user/build artifacts, SPM output, release output, and local secrets.
• iOS project configuration includes Info.plist permissions, entitlements, app icon/accent color settings, and pinned SPM dependencies.
• Test helpers added: MockCardsRepository and TestCardFactory.

Known Issues (Fix Soon)

• Settings module is still a placeholder.
• Templates module still needs placeholder UI polish.
• CloudKit is configured at the project/model level, but the app still needs a sync strategy and account-state handling.
• Remaining Cards-module view models still need unit coverage (CardCodeViewModel, CaptureCardViewModel).

Next Steps

1. Add unit tests for remaining Cards-module view models (CardCodeViewModel, CaptureCardViewModel).
2. Add loading / empty / content state polish on Cards first launch, refresh, and search results.
3. Settings: theme switch, delete all cards, app version, privacy/legal entry.
4. Templates: polish the "Coming Soon" placeholder.
5. Surface data-layer errors in the UI where recovery is possible.
6. Prepare CloudKit sync layer for multi-device storage (schema, conflict strategy, account status handling).
7. Optional CardCode UX polish: add "Show code" action in context menu in addition to tap.