thethreemagi/IYmtg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Rewrite README with full step-by-step development guide

Browse Source 
- Added Development Roadmap table showing all steps and Mac requirements
- Added Part 3: Card Database explaining IYmtg_Builder_Mac and cards.json
- Added Part 4: Xcode Project Setup from source (create, add files, SPM, capabilities)
- Added privacy plist keys and PrivacyInfo.xcprivacy guidance
- Added OTA model update restart requirement note
- Expanded Release Checklist with database and ML model checks
- Renumbered all parts consistently (Part 1-10)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Mike Wichers
2026-03-05 12:56:11 -05:00
parent a186101cb8
commit d6498d7c14
1 changed files with 243 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

310
README.md
View File

@@ -6,6 +6,35 @@ CRITICAL INSTRUCTION: This document is the single, authoritative Source of Truth
* **Architecture Mandate:** Any future updates must strictly adhere to the defined pipeline: Vector Fingerprinting (Identity) -> OCR (Validation) -> ML Analysis (Condition/Foil).
* **Preservation Protocol:** Do not summarize, truncate, or remove sections of this manual during review.
---
## Development Roadmap
This is the complete sequence of steps to go from source code to a working app. Complete them in order.
| Step | Task | Platform | Status |
| :--- | :--- | :--- | :--- |
| 1 | Workspace setup & visual assets | Any | — |
| 2 | **Build `IYmtg_Builder_Mac`** | Mac only | ⚠️ Not written yet |
| 3 | **Generate `cards.json`** database | Mac only | ⚠️ Depends on Step 2 |
| 4 | **Create Xcode project** from source | Mac only | — |
| 5 | Collect ML training images | Any (physical cards) | — |
| 6 | Train ML models in Create ML | Mac only | — |
| 7 | Configure Firebase (optional) | Any | — |
| 8 | Final configuration & testing | Mac only | — |
| 9 | App Store submission | Mac only | — |
### What You Can Do Without a Mac
* Edit source code
* Run Python automation scripts (`fetch_set_symbols.py`, `generate_images.py`)
* Collect and sort ML training images into `IYmtg_Training/`
* Acquire physical cards from the shopping lists
### What Requires a Mac
Everything else. Apple's `Vision` framework (used to generate card fingerprints) and `Create ML` (used to train models) are macOS-only. The Xcode project also lives on your Mac.
---
## Part 1: App Store Listing
### 1. Metadata
@@ -44,6 +73,8 @@ Help us make IYmtg smarter! If you find a card that scans incorrectly, you can c
* **Market Data:** Switch between major pricing sources (TCGPlayer & Cardmarket).
* **Export Options:** Also supports CSV and digital deck formats for other uses.
---
## Part 2: Workspace & Assets
### Step 1: Workspace Setup
@@ -53,13 +84,13 @@ Help us make IYmtg smarter! If you find a card that scans incorrectly, you can c
```text
IYmtg_Master/
├── IYmtg_App_iOS/ (The Xcode Project)
├── IYmtg_Builder_Mac/ (The Database Builder)
├── IYmtg_App_iOS/ (The iOS App Source Code)
├── IYmtg_Builder_Mac/ (The Card Database Builder — Mac app)
├── IYmtg_Training/ (ML Image Data)
└── IYmtg_Automation/ (Python/Shell Scripts)
```
## 2. Visual Assets
### Step 2: Visual Assets
Place the following assets in `Assets.xcassets` in the Xcode project.
@@ -74,49 +105,175 @@ Place the following assets in `Assets.xcassets` in the Xcode project.
| **share_watermark** | 400x100 | Watermark. | "A watermark logo text 'Verified by IYmtg'. White text with a checkmark icon. Clean, bold font. Solid black background. Professional verification seal style. Aspect ratio 4:1." |
| **card_placeholder**| 600x840 | Loading State. | "A generic trading card back design. Grey and silver swirl pattern. Mystical and abstract. No text. Aspect ratio 2.5:3.5." |
### Image Generation and Resizing
To generate and resize the visual assets for the app, you can use the provided script. This script uses the Gemini Image API to generate images based on the prompts defined in `IYmtg_Automation/image_generation_prompts.json`, and then automatically resizes them.
#### Automated Generation (Recommended)
**Setup:**
1. **Get a Gemini API Key:** You will need an API key from Google AI Studio.
2. **Set the API Key:** Open the `IYmtg_Automation/generate_images.py` file and set your API key in the configuration section.
2. **Set the API Key:** Open `IYmtg_Automation/generate_images.py` and set your API key in the configuration section.
3. **Install dependencies:**
```bash
pip install requests pillow
```
**Usage:**
```bash
python3 IYmtg_Automation/generate_images.py
```
The generated images will be saved in the `Raw_Assets` directory, and the resized images will be saved in the `Ready_Assets` directory.
The generated images will be saved in `Raw_Assets` and resized images in `Ready_Assets`.
#### Manual Resizing (If You Already Have Images)
If you have your own AI-generated images and only need to resize them:
1. **Setup:** Ensure you have Python installed and run `pip install Pillow`.
2. **Folders:** Run the script once to generate the `Raw_Assets` and `Ready_Assets` folders in `IYmtg_Master`.
3. **Generate Placeholders (Optional):** If you don't have AI images yet, run this script to create dummy files in `Raw_Assets` to test the pipeline.
1. **Setup:** Ensure Python is installed and run `pip install Pillow`.
2. **Generate Placeholders (Optional):**
```bash
python3 IYmtg_Automation/generate_placeholders.py
```
4. **Place Images:** Save your real AI results into `Raw_Assets` (overwrite the placeholders), naming them exactly as listed above (e.g., `AppIcon.png`).
5. **Run:** Execute the resize script:
3. **Place Images:** Save your real AI results into `Raw_Assets`, named exactly as listed above (e.g., `AppIcon.png`).
4. **Run:**
```bash
python3 IYmtg_Automation/resize_assets.py
```
6. **Result:** Your Xcode-ready images will be in `Ready_Assets`. Drag them into `Assets.xcassets`.
5. **Result:** Xcode-ready images will be in `Ready_Assets`. Drag them into `Assets.xcassets`.
## 3. Machine Learning Training
---
### **General Data Collection Protocol (CRITICAL)**
## Part 3: Card Database (`cards.json`) — Mac Required
**This is the most critical file in the project.** The app cannot identify any cards without it. It is a JSON file bundled inside the app containing a fingerprint (a mathematical representation) of every Magic card, generated from card images using Apple's Vision framework.
### What `cards.json` Contains
Each entry in the file represents one unique card printing and contains:
- Card name, set code, and collector number
- Whether the card has a foil or serialized printing
- Pricing data
- A `VNFeaturePrintObservation` (binary blob) — the visual fingerprint used for identification
### Step 1: Write `IYmtg_Builder_Mac`
`IYmtg_Builder_Mac/` is currently **empty**. This Mac command-line tool needs to be built before `cards.json` can be generated. It must:
1. Fetch the complete card list from the Scryfall API (`https://api.scryfall.com/bulk-data` → `default_cards` dataset)
2. Download a card image for each unique printing
3. Run `VNGenerateImageFeaturePrintRequest` (Apple Vision) on each image to produce a fingerprint
4. Archive the fingerprint using `NSKeyedArchiver` into a `Data` blob
5. Write all entries to `cards.json` using the `CardFingerprint` model defined in `IYmtg_App_iOS/Data/Models/Card.swift`
6. Place the output at `IYmtg_App_iOS/cards.json`
**Data model reference** (`CardFingerprint` in `IYmtg_App_iOS/Data/Models/Card.swift`):
```swift
struct CardFingerprint: Codable {
let id: UUID
let name: String
let setCode: String
let collectorNumber: String
let hasFoilPrinting: Bool
let hasSerializedPrinting: Bool?
let priceScanned: Double?
let featureData: Data // NSKeyedArchiver-encoded VNFeaturePrintObservation
}
```
**To build `IYmtg_Builder_Mac`:** Give this README section to an AI (Claude or Gemini) along with the `CardFingerprint` struct and ask it to write a Swift command-line tool for macOS. The tool is straightforward — it is a single-purpose script that runs once and can take several hours to complete due to the volume of Scryfall image downloads.
### Step 2: Run the Builder
On your Mac, build and run `IYmtg_Builder_Mac`. The `weekly_update.sh` script automates this:
```bash
chmod +x IYmtg_Automation/weekly_update.sh
./IYmtg_Automation/weekly_update.sh
```
This script:
1. Builds the builder app using `xcodebuild`
2. Runs it (this takes time — Scryfall has ~100,000+ card printings)
3. Moves the output `cards.json` into `IYmtg_App_iOS/` ready to be bundled
**Run this script periodically** (e.g., weekly) to pick up newly released sets.
### Step 3: Add `cards.json` to Xcode
After the builder runs, `cards.json` will be at `IYmtg_App_iOS/cards.json`.
In Xcode:
1. Drag `cards.json` into the project navigator under `IYmtg_App_iOS/`
2. Ensure **"Add to target: IYmtg"** is checked so it is bundled inside the app
---
## Part 4: Xcode Project Setup — Mac Required
The source code in `IYmtg_App_iOS/` is complete. Follow these steps to create the Xcode project on your Mac.
### Step 1: Create the Project
1. Open Xcode → **File → New → Project**
2. Choose **iOS → App**
3. Set:
- **Product Name:** IYmtg
- **Bundle Identifier:** `com.<yourname>.iymtg` (you choose this — note it down, you'll need it for iCloud)
- **Interface:** SwiftUI
- **Language:** Swift
- **Storage:** None (we use SwiftData manually)
4. Save the project **inside** `IYmtg_App_iOS/` — this places the `.xcodeproj` alongside the source files.
### Step 2: Add Source Files
1. In the Xcode project navigator, right-click the `IYmtg` group → **Add Files to "IYmtg"**
2. Select all folders inside `IYmtg_App_iOS/`:
- `Application/`
- `Data/`
- `Features/`
- `Services/`
- `Firebase/`
- `AppConfig.swift`
- `ContentView.swift`
- `IYmtgApp.swift`
- `IYmtgTests.swift`
- `cards.json` (once generated)
3. Ensure **"Copy items if needed"** is **unchecked** (files are already in the right place) and **"Create groups"** is selected.
### Step 3: Add Dependencies (Swift Package Manager)
1. **File → Add Package Dependencies**
2. Add the Firebase iOS SDK:
- URL: `https://github.com/firebase/firebase-ios-sdk`
- Add these libraries to your target: `FirebaseCore`, `FirebaseFirestore`, `FirebaseAuth`, `FirebaseStorage`
### Step 4: Configure Signing & Capabilities
1. Select the project in the navigator → **Signing & Capabilities** tab
2. Set your **Team** and ensure **Automatically manage signing** is on
3. Set **Minimum Deployments** to **iOS 17.0**
4. Click **+ Capability** and add:
- **iCloud** → enable **CloudKit** → add container `iCloud.<your-bundle-id>`
- **Background Modes** → enable **Remote notifications**
5. Lock orientation: **General** tab → **Deployment Info** → uncheck Landscape Left and Landscape Right
### Step 5: Add Privacy Descriptions
In `Info.plist`, add these keys (Xcode will prompt on first run, but adding them manually avoids rejection):
| Key | Value |
| :--- | :--- |
| `NSCameraUsageDescription` | `IYmtg uses the camera to scan and identify Magic: The Gathering cards.` |
| `NSPhotoLibraryUsageDescription` | `IYmtg can save card images to your photo library.` |
Also add `PrivacyInfo.xcprivacy` to the app target to satisfy Apple's privacy manifest requirements (required for App Store submission as of 2024).
### Step 6: Build and Run
1. Select a connected physical iPhone as the build target (camera features do not work in the simulator)
2. Press **Cmd+R** to build and run
3. On first launch the app will show **"Database Missing"** until `cards.json` is bundled (see Part 3)
---
## Part 5: Machine Learning Training — Mac Required for Final Step
Training images can be collected on any device. Model training itself requires Create ML on a Mac.
### General Data Collection Protocol (Critical)
The app sends **cropped** images (just the card, no background) to the AI. Your training data must match this.
1. **Capture:** Take photos of the card on a contrasting background.
@@ -126,6 +283,8 @@ The app sends **cropped** images (just the card, no background) to the AI. Your
3. **Sort:** Place the cropped image into the corresponding folder in `IYmtg_Training`.
4. **Quantity:** Aim for 30-50 images per category for robust results.
> **Note:** The app works without trained models — foil detection defaults to "None" and condition defaults to "NM". You can ship a working app and add ML models later via OTA update.
### Step 1: The Master Foil Shopping List (Required for FoilEngine)
Acquire one of each (~$50 total) to train the Foil Classifier. This ensures the app can distinguish complex modern foil types.
@@ -185,7 +344,7 @@ Acquire these specific cheap cards to verify the logic-based detectors. **Note:*
| **Saturation** | Unl/Revised Sim | *Revised* Basic Land (Washed out) vs *4th Edition* (Saturated). |
### Step 5: Training Folder Structure
Create the following directory tree inside `IYmtg_Training` to organize your image data for Create ML.
The following directory tree is already created in `IYmtg_Training`. Place your cropped images into the appropriate folders.
```text
IYmtg_Training/
@@ -226,13 +385,27 @@ IYmtg_Training/
└── BindersDents/
```
### Step 6: Create ML
1. **Foil Classifier:** Train an Image Classification model using `Foil_Data`. Export as `IYmtgFoilClassifier.mlmodel`.
2. **Stamp Classifier:** Train an Image Classification model using `Stamp_Data`. Export as `IYmtgStampClassifier.mlmodel`.
3. **Condition Classifier:** Train an Object Detection model using `Condition_Data`. Export as `IYmtgConditionClassifier.mlmodel`.
4. **Import:** Drag all `.mlmodel` files into the Xcode Project Navigator.
### Step 6: Train Models in Create ML (Mac)
## 4. Backend & Security
1. Open **Create ML** (found in Xcode → Open Developer Tool → Create ML)
2. **Foil Classifier:** New Project → Image Classification → drag in `Foil_Data/` → Train → Export as `IYmtgFoilClassifier.mlmodel`
3. **Stamp Classifier:** New Project → Image Classification → drag in `Stamp_Data/` → Train → Export as `IYmtgStampClassifier.mlmodel`
4. **Condition Classifier:** New Project → Object Detection → drag in `Condition_Data/` → Train → Export as `IYmtgConditionClassifier.mlmodel`
5. Drag all three `.mlmodel` files into the Xcode Project Navigator (ensure they are added to the app target)
### Set Symbol Harvester (Automation)
Run this script to automatically collect set symbol training data from Scryfall. Works on any platform.
```bash
pip install requests pillow
python3 IYmtg_Automation/fetch_set_symbols.py
```
Output goes to `Set_Symbol_Training/`. Drag this folder into Create ML → Image Classification to train `IYmtgSetSymbolClassifier.mlmodel`.
---
## Part 6: Backend & Security
### Cloud Storage Architecture
The app uses a two-tier cloud strategy:
@@ -269,45 +442,35 @@ To update ML models without an App Store release:
2. Upload the `.mlmodel` file to Firebase Storage in the `models/` folder.
3. The app will automatically detect the newer file, download, compile, and hot-swap it on the next launch.
> **Note:** OTA model updates take effect on the next app launch — not immediately. An app restart is required after a new model is downloaded.
### Privacy Manifest
Ensure `PrivacyInfo.xcprivacy` is included in the app target to satisfy Apple's privacy requirements regarding file timestamps and user defaults.
## 5. Automation
---
Scripts are located in `IYmtg_Automation/`.
### Set Symbol Harvester
Fetches training data for set symbols from Scryfall.
```bash
pip install requests pillow
python3 IYmtg_Automation/fetch_set_symbols.py
```
### Weekly Update Script
Automates the build-and-deploy process for the database builder.
```bash
chmod +x IYmtg_Automation/weekly_update.sh
./IYmtg_Automation/weekly_update.sh
```
## 6. App Configuration
## Part 7: App Configuration
**CRITICAL:** Edit `IYmtg_App_iOS/AppConfig.swift` before building to ensure payments and support work correctly:
1. Set `contactEmail` to your real email address.
2. Set `tipJarProductIDs` to your actual In-App Purchase IDs.
1. Set `contactEmail` to your real email address (required by Scryfall API policy).
2. Set `tipJarProductIDs` to your actual In-App Purchase IDs from App Store Connect.
3. `isFirebaseBackupEnabled` defaults to `false`. Users opt-in from Library settings.
## 7. Development Mode
---
## Part 8: Development Mode
To enable saving raw training images during scanning:
1. Add the compilation flag `ENABLE_DEV_MODE` in Xcode Build Settings.
1. Add the compilation flag `ENABLE_DEV_MODE` in Xcode Build Settings → Swift Compiler → Active Compilation Conditions.
2. Tap the "IYmtg" logo header 5 times in the app to activate.
## 8. Testing
Saved images appear in `Documents/DevImages/` and can be used to supplement your ML training data.
The project includes a comprehensive unit test suite located in `IYmtgTests.swift`.
---
## Part 9: Testing
The project includes a unit test suite in `IYmtgTests.swift`.
**How to Run:**
* Press `Cmd+U` in Xcode to execute the test suite.
@@ -319,31 +482,42 @@ The project includes a comprehensive unit test suite located in `IYmtgTests.swif
**Note:** CoreML models are not loaded during unit tests to ensure speed and stability. The tests verify the *logic* surrounding the models (e.g., "If 3 scratches are detected, grade is Played") rather than the ML inference itself.
## 9. Release Checklist
---
## Part 10: Release Checklist
Perform these steps before submitting to the App Store.
1. **Configuration Check:**
1. **Database:**
* [ ] `cards.json` is present in `IYmtg_App_iOS/` and added to the Xcode target.
* [ ] Builder was run recently enough to include current sets.
2. **Configuration Check:**
* [ ] Open `AppConfig.swift`.
* [ ] Verify `contactEmail` is valid.
* [ ] Verify `contactEmail` is your real email (not a placeholder).
* [ ] Verify `tipJarProductIDs` match App Store Connect.
* [ ] Ensure `enableFoilDetection` and other flags are `true`.
* [ ] Ensure `enableFoilDetection` and other feature flags are `true`.
* [ ] Update `appVersion` (Semantic Versioning: Major.Minor.Patch) and `buildNumber` for this release.
2. **iCloud / CloudKit:**
3. **ML Models:**
* [ ] `IYmtgFoilClassifier.mlmodel` added to Xcode target (or acceptable to ship without).
* [ ] `IYmtgStampClassifier.mlmodel` added to Xcode target (or acceptable to ship without).
* [ ] `IYmtgConditionClassifier.mlmodel` added to Xcode target (or acceptable to ship without).
4. **iCloud / CloudKit:**
* [ ] Signing & Capabilities → iCloud → CloudKit enabled.
* [ ] CloudKit container added: `iCloud.<bundle-id>`.
* [ ] Background Modes → Remote notifications enabled.
* [ ] Minimum deployment target set to **iOS 17**.
3. **Assets:**
* [ ] Ensure `Assets.xcassets` has the AppIcon filled for all sizes.
4. **Testing:**
* [ ] Run Unit Tests (`Cmd+U`) - All must pass.
* [ ] Run on Physical Device - Verify Camera permissions prompt appears.
5. **Build:**
5. **Assets:**
* [ ] `Assets.xcassets` has the AppIcon filled for all sizes.
* [ ] `PrivacyInfo.xcprivacy` is in the app target.
6. **Testing:**
* [ ] Run Unit Tests (`Cmd+U`) — all must pass.
* [ ] Run on Physical Device — verify Camera permissions prompt appears.
* [ ] Run on Physical Device — verify a card scans and saves successfully.
7. **Build:**
* [ ] Select "Any iOS Device (arm64)".
* [ ] Product -> Archive.
* [ ] Product → Archive.
* [ ] Validate App in Organizer.
* [ ] Distribute App -> App Store Connect.
* [ ] Distribute App → App Store Connect.
---
**Version Authority:** 1.0.0